Embed Compensation Benchmarks

Learn how to embed Visier Compensation Benchmarks in your solution.

Overview

You can embed Visier Compensation Benchmarks in your solution using an iframe. The process to embed Compensation Benchmarks is very similar to Embed the Full Visier Application, which embeds the Visier People application. The key differences are:

• The SDK path to embed Compensation Benchmarks is /jobs/assets/sdk.js compared to Visier People's /hr/assets/embedded/webAssets/sdk.v2.js.
• The function to call Compensation Benchmarks is visierCb compared to Visier People's visier.
• The code snippet to load the Compensation Benchmarks SDK does not require idpUrl because the SDK uses the IdP URL in your tenant's single sign-on configuration.

You can embed both Visier People and Compensation Benchmarks application in your solution. For more information, see Use the Embedded SDK Manager.

Prerequisites

There are a few steps you must take before you can start integrating Visier into your solution, as described next.

• Add trusted domains to the embeddable domains list. Each addition requires a secure domain using Hypertext Transfer Protocol Secure (https). For more information, see Add Your Domain to the Embeddable Domains List.
• Enable single sign-on. For more information, see Set Up Single Sign-On.

  Single sign-on allows Visier to correctly validate SAML assertions associated with the integration.

• Set up the identity provider (IdP) server. For more information, see What is an identity provider (IdP). Additionally, you can view the following example of IdP setup: How to perform IdP-initiated SSO to a Service Provider when PingFederate is the IdP.

  The IdP server stores and manages digital identities. Visier's single sign-on mechanism uses your IdP to check user identity but does not store identity.

• In your Chrome browser, turn off Bypass for network. To turn off Bypass for network, open Chrome DevTools and navigate to Application > Service Workers, then turn off Bypass for network.

After you complete the prerequisites, you can start the technical development to integrate Visier into your solution.

Add Compensation Benchmarks's embedding script to your target page

On the page in which you want to embed Compensation Benchmarks, add the below script. The script downloads the Compensation Benchmarks Embedding SDK and makes Visier's embedding API available through the visierCb function. For example, use the API to keep the Visier session alive with visierCb("trigger", "PARENT_SESSION_ALIVE").

Before running the script, replace the placeholder text with your unique values, such as your unique visierUrl.

// Declare the visierConfig
const visierConfig = {
    visierUrl: "https://example.visier.com/jobs",
};

// Add a script element pointing to the SDK and make its public functions available.
(function(w, d, t, s, c, v, e, x) {
    w['VisierCompBenchmarksEmbedder'] = v;
    w[v] = w[v] || function() {
        (w[v].q = w[v].q || []).push(arguments)
    };
    if (!d.getElementById(s)) {
        e = d.createElement(t);
        x = d.getElementsByTagName(t)[0];
        e.id = s;
        e.async = true;
        e.src = c.visierUrl;
        x.parentNode.insertBefore(e, x);
    }
})(window, document, 'script', '/assets/sdk.js', visierConfig, 'visierCb');

// Bootstrap the SDK with the visierConfig.
visierCb('bootstrap', visierConfig, async function(app) {
    const params = new URLSearchParams(window.location.search);
    app.embedApp('visier-container');
});

// Surface messages to console for development and debugging purposes:
visierCb('on', 'info', function(msg) { console.info("[INFO]: ", msg); });
visierCb('on', 'error', function(msg) { console.error("[ERROR]: ", msg); });
visierCb('on', 'session', function(msg) { console.info("[SESSION]: ", msg); });
visierCb('on', 'debug', function(msg) { console.info("[DEBUG]: ", msg); });

For a full list of visierConfig fields, see visierConfig fields.

Add an iframe to your target page

On the page in which you want to embed the Compensation Benchmarks application, add an iframe and give the iframe an ID. Compensation Benchmarks is embedded in your application through the iframe. The iframe's ID is the string you pass for visier-container to load Visier in your application. For more information, see Load the Visier application in your iframe.

Render Visier in your application

After getting a valid Visier session, you can then render Visier in your application. First, you need to retrieve the available Visier rooms for the navigation bar and then render the associated Visier navigation links in your application.

Fetch navigation links

To render Visier rooms, you must first retrieve links for each navigation item. Call the following code snippet to retrieve navigation links.

visierCb('bootstrap', visierCbConfig, async function(app) {
    app.embedApp('visierCb-container');
    const sections = await app.get('APPLICATION_SECTIONS');
    // Use the returned "sections" array to populate navigation links.
})

View sample response: Navigation links in JSON

Copy

[
  {
    "sectionId": 1,
    "sectionName": "Compensation benchmarks",
    "sectionUrl": "/home",
    "availableRooms": [
      {
        "roomId": 6,
        "roomName": "Market data for current jobs",
        "roomUrl": "/home/current-jobs"
      },
      {
        "roomId": 7,
        "roomName": "Market data for new jobs",
        "roomUrl": "/home/new-jobs"
      },
      {
        "roomId": 5,
        "roomName": "Learn more",
        "roomUrl": "/home/learn-more"
      }
    ]
  }
]

Render navigation links

After fetching the available Visier rooms (application sections), you might want to add links to Visier rooms in your application's navigation bar. The following code sample is an example of how to render Visier links on your navigation bar.

View sample code: Adding rooms that were returned by Visier App Server

Copy

// Add all the rooms from a given list of rooms.
function addRoomsFromVisierSection(rooms) {
   if (rooms) {
       rooms.forEach(function (room, i) {
           addVisierMenu(room.roomId, room.roomName, room.roomUrl, "room");
       })
    } 
}

Direct navigation to Visier iframe

When a user selects a Visier room on your navigation bar, your code should trigger navigation to the iframe.

View sample code: Navigation through Visier menu items using the visierCb function

Copy

visierCb("trigger", "NAVIGATE", selectedUrl);

Hide navigation UI

You can hide Compensation Benchmarks navigation and implement your own navigation breadcrumbs. To hide navigation UI, pass in an optional configuration object when you embed Compensation Benchmarks, as shown in the following code snippet.

1
2
3
visierCb('bootstrap', visierCbConfig, async function(app) {
    app.embedApp('visierCb-container', undefined, undefined, { hideNavigation: true });
})

For more information, see (Optional) Implement breadcrumb navigation. In the (Optional) Implement breadcrumb navigation code snippets, replace visier with visierCb.

Sign out of Compensation Benchmarks

To handle user sign out, send the PARENT_SESSION_CLEANUP event, as shown in the following code snippet.

function logout() {
    if (window.visierCb) {
        visierCb("trigger", "PARENT_SESSION_CLEANUP", function (error) {
            if (error) {
                console.error(error);
            } 
        });
    } 
}

For more information about handling sessions in your application and the embedded Compensation Benchmarks application, see Handle session alignment.

Set up event handling/listeners

The Compensation Benchmarks SDK exposes a number of events that can be used for custom event handlers, which can be added right after calling the bootstrap method.

The following table defines the possible events.

{
  "code": "NAVIGATE_EXTERNAL",
  "message": {
    "url": "#/analytics/myanalyses/0550adf0-2995-4e6f-9f83-1f03a0ae6c54",
    "dest": "Visier"
  }
}

{
    "code": "NAVIGATE_INTERNAL",
    "message": {
        "url": "#/analytics/guidebook?guidebookId=Monitor_Your_Organization_Guidebook",
        "pageId": "Monitor_Your_Organization_Guidebook",
        "title": "Learn About Visier People",
        "description": "Learn about best practices in using Visier and people analytics",
        "parentHierarchy": [
            {
                "url": "#/analytics/guidebook",
                "pageId": "guidebooks",
                "title": "Guidebooks"
            }
        ]
    }
}

{
    "code": "JOB_UPDATE",
    "message": {
        "updatedJobs": [
            {
                "employeeId": "Employee-240",
                "jobId": "J.005189",
                "jobName": "Manager, Customer Service",
                "socCode": "11-1021",
                "socName": "General and Operations Managers"
            }
        ]
    }
}

{
    "code": "JOB_MATCH",
    "message": {
        "matchedJobs": [
            {
                "employeeId": "Employee-140",
                "jobId": "J.020511",
                "jobName": "General Manager (Retail)",
                "careerLevelId": "CL.M03",
                "careerLevelName": "Manager 1",
                "socCode": "11-1021",
                "socName": "General and Operations Managers"
            }
        ]
    }
}

Handle navigation events

Register for navigation events to obtain information about navigation internal to Compensation Benchmarks. You can use the event information to construct your own breadcrumb navigation or to navigate between Compensation Benchmarks and Visier People.

visierCb('on', 'navigate', function(msg) {
    console.info("[NAVIGATE]: ", msg);
    switch (msg.code) {
        case "NAVIGATE_EXTERNAL":
            // Trigger navigation in the Visier People SDK imported as 'visier'
            visier('trigger', 'NAVIGATE', msg.message.url);
            break;
        case "NAVIGATE_INTERNAL":
            console.log("Navigate to internal room: ", msg.message.url);
            break;
        default:
            console.error("Unknown navigation code: ", msg.code);
    }
});

Select a single sign-on provider

If your organization has more than one SSO configuration, you can set the following parameters to specify which SSO provider to use for embedding Compensation Benchmarks.

• idpIssuer: Used to select the SSO configuration by matching the Issuer field of the SSO configuration.
• idpUrl: Used to select the SSO configuration by matching the IdP URL field of the SSO configuration. Matching by idpUrl is convenient when working with both the Compensation Benchmarks and Visier People SDKs because idpUrl is a mandatory parameter for the Visier People SDK. When matching, query parameters in the URL are ignored but otherwise the URLs must match exactly.

If you don't specify idpIssuer or idpUrl, the SDK uses the first SSO configuration. If you specify both idpIssuer and idpr, the SDK uses idpIssuer.

Use the Embedded SDK Manager

Prerequisites: Initialize the Visier People SDK. For more information, see Embed the Full Visier Application.

The Embedded SDK Manager is a helper API that works with the Compensation Benchmarks SDK and the Visier People SDK to coordinate navigation and session management if you use both SDKs, such as to navigate from Compensation Benchmarks to compensation analyses in Visier People.

Initialize the Visier People SDK

To use the SDK Manager, your containing application must first load the full Visier application SDK  as described in Embed the Full Visier Application. At minimum, invoke the bootstrap method. After initialization, you can use the SDK anywhere in your application, such as to load Vee or display analyses independently of Compensation Benchmarks.

We recommend that you only load the Visier People SDK once per browser window.

Initialize the Embedded SDK Manager

Next, initialize the Embedded SDK Manager. This process is similar to initializing the Visier People SDK, however, note that:

• In analysisSdk, provide the name to reference the Visier People SDK.  In the sample code, the analysisSdk is visier to align with the name in Embed the Full Visier Application.
• In embedApp, provide the ID of a div, not an iframe. The SDK Manager creates iframes inside the provided div to contain the Compensation Benchmarks application and the Visier People application.

• To size the iframes correctly inside the provided div, provide iframe sizing in your CSS, as shown in the following sample code.

  Copy

  Sample code: CSS to size the iframe

  1
  2
  3
  4
  5
  #comp-benchmarks-container iframe {
      width: 100%;
      height: 100%;
      border: none;
  }

const compBenchmarksConfig = {
    visierUrl: "https://example.visier.com/jobs",
    idpUrl: "https://idp.example.com",
    # IMPORTANT: The analysisSdk value must match the name you use to load the Visier People SDK.
    analysisSdk: "visier",
};

(function(w, d, t, s, c, v, e, x) {
    w['VisierCompBenchmarksManager'] = v;
    w[v] = w[v] || function() {
        (w[v].q = w[v].q || []).push(arguments)
    };
    if (!d.getElementById(s)) {
        e = d.createElement(t);
        x = d.getElementsByTagName(t)[0];
        e.id = s;
        e.async = true;
        e.src = c.visierUrl + s;
        x.parentNode.insertBefore(e, x);
    }
})(window, document, 'script', '/assets/sdk-manager.js', compBenchmarksConfig, 'compBenchmarks');

compBenchmarks('bootstrap', compBenchmarksConfig, async function(app) {
    // IMPORTANT: This container should be a div, not an iframe.
    // We will create and manage two iframes within this div.
    app.embedApp('comp-benchmarks-container');
    // Get navigation sections.
    const sections = await app.get('APPLICATION_SECTIONS');
    handlecompBenchmarksSections(sections);
});

After embedApp completes, the Compensation Benchmarks welcome page appears in your iframe in the provided div; in the sample code above, the provided div is comp-benchmarks-container.

Fetch navigation links

Use APPLICATION_SECTIONS to obtain information for navigating between different parts of the application. This resource contains names and target URLs for sections contained in the Compensation Benchmarks and Visier People applications. You can use the returned URLs to trigger navigation using the trigger method.

compBenchmarks('bootstrap', compBenchmarksConfig, async function(app) {
    app.embedApp('comp-benchmarks-container');
    const sections = await app.get('APPLICATION_SECTIONS');
    // Use the sections array returned to populate navigation links.
});

Trigger navigation

Use the trigger method to navigate within the iframe. In the url argument, use the URLs returned by the APPLICATION_SECTIONS resource or the navigate event. Do not hard-code the URLs into your application. If the URL is not currently visible, the SDK Manager switches to the correct application's iframe.

compBenchmarks('trigger', 'NAVIGATE', url);

Handle navigation between Compensation Benchmarks and Visier

The SDK Manager registers navigation events from both the Compensation Benchmarks SDK and the Visier People SDK. The SDK Manager handles NAVIGATE_EXTERNAL events automatically handled to make the correct iframe and section visible. You can listen for navigation events from both SDKs.

Add event handling/listeners

Use the on method to register handlers for events from the Compensation Benchmarks application. For more information about events, see Set up event handling/listeners. To register for events from the Visier People, use the on method directly on the Visier People SDK, not the SDK Manager, as shown in the following code snippet.

visier("on", event, handler)

Remove event handling/listeners

Use the off method to remove handlers for events from the Compensation Benchmarks application. For more information about events, see Set up event handling/listeners. To remove events from the Visier application, use the off method directly on the Visier People SDK, not the SDK Manager, as shown in the following code snippet.

visier("off", event, handler)

Synchronize sessions

The SDK Manager listens for parent session events from the Visier People SDK and relays those events to the Compensation Benchmarks application. You can handle events like PARENT_SESSION_ALIVE and PARENT_SESSION_CLEANUP in the Visier People SDK, but both the Compensation Benchmarks and Visier People applications will see those events and take the appropriate action.

To turn off listening for parent session events, use syncParentSession: false in the bootstrap on the SDK Manager.