Displaying Keyfax Self-Service

Our recommendations for displaying Keyfax Self-Service.

NOTE This information is not applicable to Keyfax Staff as Keyfax Staff is already generally launched within it's own unique browser control or browser tab.

This article relates to Keyfax Self-Service integrations where you may wish to display Keyfax Self-Service from within your existing tenant portal.

Unlike Keyfax Staff where advisor access can be closely controlled, tenants can access Keyfax Self-Service on a wide variety of browsers and devices and as such Omfax Systems would encourage integrators to keep any Keyfax Self-Service integration as simple as possible to support the broadest range of browsers and devices.

When integrating Keyfax Self-Service into your tenant portal we would generally suggest using a pop-up window to display Keyfax or simply opening Keyfax within the same browser tab or a new browser tab. We would generally advise avoiding an iframe to display Keyfax as iframes have various usability issues and security restrictions.

Why choose a tab or pop-up window over an iframe?

Browsers are increasingly blocking 3rd party cookies. Features such as Intelligent Tracking Protection (ITP) within WebKit & Privacy Sandbox within Chromium block all 3rd party cookies (cookies on requests to domains that are not the same as the domain showing within the browsers address bar). In many cases 3rd party cookies are blocked by default regardless of the samesite and or secure cookie attributes which can have unexpected side effects within Keyfax.

Apple has forced browser vendors on iOS / macOS to adopt ITP and as part of this 3rd party cookies must be disabled by default by browsers on iOS/macOS. Chrome will be deprecating support for all 3rd party cookies at the end of 2023 with a feature called Privacy Sandbox.

As browsers are blocking 3rd party cookies more and more to help future proof host integrations Omfax Systems would not recommend displaying Keyfax within a 3rd party / cross-domain iframe and instead if Keyfax and your host application need to be installed on different domains would recommend displaying Keyfax as a 1st party web site either by displaying Keyfax within a browser pop-up window or a full browser tab. Displaying Keyfax within a pop-up window allows the browser to display the browser address bar at the top of the pop-up window to the user and so the browser treats pop-up windows as 1st party web sites.

For the best user experience and most reliable, future proof Keyfax integration Omfax Systems would generally suggest displaying Keyfax as a 1st party web site. Omfax Systems can visually customise the look and feel of your Keyfax installation to perfectly match your existing tenant portal or branding to provide a more seamless, consistent experience to your end-users.

Pop-Up Considerations

Displaying Keyfax within a pop-up window will ensure Keyfax is presented as a 1st party web site however pop-up windows do come with their own drawbacks. For example it's possible the pop-up window could be blocked by a users pop-up blocker and / or the user may need to perform additional steps to allow the pop-up window.

For the best possible end-user experience Omfax Systems would generally suggest simply displaying Keyfax within the same browser tab or within a new browser tab and having Keyfax return to your tenant portal after Keyfax completes.

Example pop-up window integration

Our KeyNamics for Power Pages Portals integration already displays Keyfax within a pop-up window as shown here...

• https://keynamicsportal.powerappsportals.com/page/minimal/

The full JavaScript code used for this example can be found here...

• https://keynamicsportal.powerappsportals.com/keyfax.js

The full CSS code used for this example can be found here...

• https://keynamicsportal.powerappsportals.com/keyfax.css

In the below examples we'll share some basic code and considerations to help you achieve a similar behavior with your Keyfax integration. Please remember however that the code presented below is the minimal to help you get started and we would encourage you to review the full JavaScript & CSS linked above for a more complete working example.

Displaying Keyfax within a pop-up window

Once Keyfax has returned a launch URL (after you call the start-up web service) you would typically take this launch URL and display this within a browser pop-up window. To help we've provided the following createPopUp() method below...

var newWindow = null; // A global here for convenience / readability purposes - you would want to consider scope here and possibly wrapping this within a object literal or closure to avoid polluting the global scope
function createPopUp(url, title, w, h) {

    var screenX = typeof window.screenX !== 'undefined' ? window.screenX : window.screenLeft,
        screenY = typeof window.screenY !== 'undefined' ? window.screenY : window.screenTop,
        outerWidth = typeof window.outerWidth !== 'undefined' ? window.outerWidth : document.documentElement.clientWidth,
        outerHeight = typeof window.outerHeight !== 'undefined' ? window.outerHeight : document.documentElement.clientHeight,
        isMobile = function () {
            return (outerWidth <= 1024);
        },
        targetWidth = isMobile() ? null : w,
        targetHeight = isMobile() ? null : h,
        V = screenX <= 0 ? window.screen.width + screenX : screenX,
        left = parseInt(V + (outerWidth - targetWidth) / 2.5, 10),
        top = parseInt(screenY + (outerHeight - targetHeight) / 2.5, 10),
        features = [];

    // Build features
    if (targetWidth !== null) {
        features.push('width=' + targetWidth + "px");
    }
    if (targetHeight !== null) {
        features.push('height=' + targetHeight + "px");
    }
    features.push('left=' + left);
    features.push('top=' + top);
    features.push('scrollbars=1');
    features.push('popup=1');

    try {
        // Attempt to open
        newWindow = window.open(url, title, features.join(','));
        // Detect if the pop-up window was blocked and present a friendly message
        if (!newWindow || newWindow.closed || typeof newWindow.closed == 'undefined') {
            // Display blocked message
        }
    } catch (e) {
        // Log
        if (window.console) {
            window.console.log("An error occurred opening the Keyfax pop-up window. Error: " + e.message);
        }
    } finally {
        // Set focus if window opened successfully
        if (newWindow !== null && newWindow !== undefined && !newWindow.closed) {                
            if (newWindow.focus) {
                newWindow.focus();
            }
        }
    }

};

function getViewportSize(w) {

    // Use the specified window or the current window if not supplied
    w = w || window;

    // This works for all browsers except IE8 and before
    if (w.innerWidth !== null) {
        return {
            w: w.innerWidth,
            h: w.innerHeight
        };
    }

    // For IE (or any browser) in Standards mode
    var d = w.document;
    if (doc.compatMode === "CSS1Compat")
        return {
            w: d.documentElement.clientWidth,
            h: d.documentElement.clientHeight
        };

    // For browsers in Quirks mode
    return {
        w: d.body.clientWidth,
        h: d.body.clientHeight
    };

}

You would call the createPopUp() method like so...

// Get view port dimensions
var viewPortSize = getViewportSize(window);
// Show pop-up slightly smaller than the current view port
createPopUp("https://demo.keyfax.biz/Interview/Main/Main.aspx?guid=KF-5fd93ebe-b103-4e45-97da-124a4f92835e&co=DemoLive#", "Keyfax", Math.floor(viewPortSize.w - 200), Math.floor(viewPortSize.h - 200));

Handling users closing the pop-up

To detect if users close the Keyfax pop-up window additional client-side JavaScript code would be necessary. In the above example we use a setInterval JavaScript timer to continually check the pop-up window status and if the code detects the window has been closed the parent or opening page can be updated to inform the user.

To achieve this we'll add a new addPopUpCloseListener method which will periodically check the newWindow global variable as defined above. This new method can be seen below...

var popupInterval = null; // Again defined as a global variable for convenience / readability
function addPopUpCloseListener() {

    // Ensure pop-up is active
    if (newWindow === null) {
        return;
    }

    // Poll to check when pop-up window is closed
    popupInterval = window.setInterval(function () {
        if (newWindow  === null) {
            // Remove pop-up close listener
            removePopUpCloseListener();
            // Return early
            return;
        }
        if (newWindow.closed) {
            // Update parent page DOM to display "Window Closed" message
            // Remove pop-up close listener
            removePopUpCloseListener();
            // Reset window reference
            newWindow = null;          
        }
    }, 100);

}

function removePopUpCloseListener () {
    if (popupInterval) {
        window.clearInterval(popupInterval);
    }            
}

This listener should be added immediately after calling createPopUp. For example...

// Get view port dimensions
var viewPortSize = getViewportSize(window);
// Show pop-up slightly smaller than the view port
createPopUp("https://demo.keyfax.biz/Interview/Main/Main.aspx?guid=KF-5fd93ebe-b103-4e45-97da-124a4f92835e&co=DemoLive#", "Keyfax", Math.floor(viewPortSize.w - 200), Math.floor(viewPortSize.h - 200));
// Add pop-up window close listener
addPopUpCloseListener();

Closing the pop-up once Keyfax completes

To close the pop-up window once Keyfax has completed you would typically pass in a "ReturnURL" as part of the Keyfax start-up data to return the user back to a custom page once Keyfax completes. This custom page would contain client side code to either automatically close the pop-up window or allow the user to manually close the window.

For example to automatically close the pop-up window you would simply invoke window.close() when the user lands back on the custom completed page. You could also optionally add a button to allow the user to close the window and simply add window.close() into the buttons click handler.

You can also invoke client-side JavaScript code on the parent / opening page. For example if you had a global method on your parent page called handleKeyfaxCompleted you could invoke this method from the custom completed page within the pop-up window like so window.opener.handleKeyfaxCompleted(). The handleKeyfaxCompleted() method on your parent page could be responsible for updating DOM elements on your parent / opening page to thank the user for the submission or perform additional logic.

Displaying a pop-up overlay

Whilst not functionally required you'll notice in the above KeyNamics for Power App Portals example the background becomes blurred when you open the Keyfax pop-up window. This is achieved by adding a semi-transparent overlay and applying a blur effect to parent pages CSS whenever the Keyfax pop-up window is active. Whilst beyond the scope of this guide if you wanted to achieve a similar effect we would encourage you to review the showPopUpOverlay() and hidePopUpOverlay() methods within the full JavaScript linked above. The full CSS used is also linked above.

How does this work on a device with constrained screen space

For example on a mobile device you would typically not have enough screen space to display a pop-up window.

Mobile browsers are aware of this and all mobile browsers we've tested seem to treat the call to window.open() similar to a regular anchor tag with a target="_blank" attribute, You'll notice on a mobile device or tablet that a pop-up window won't display and instead the browser will simply spawn a new tab. The mobile browser is aware this tab was opened in the context of a pop-up window and allows calls to window.close() to automatically close the tab if desired.