Embed a Visualization

Learn how to embed a visualization in the flow of your users' work.

Who can use this feature?

Users with this permission capability:

  • Embed Analytic Content

Not sure if you have this feature or capability? Reach out to your administrator.

This feature enables you to view a visualization within the context of your day-to-day work with the correct data security context, as shown next.

Users only see embedded visualizations if they have access to Visier. If required, you can enable automated user provisioning to ensure users have access to Visier. For more information, see Auto Provisioning.

Prerequisites

Note:  

  • Work with your tenant administrator, IT administrator, and/or development team to ensure the following prerequisites are completed to enable this feature.
  • Before embedding Visier in your application, review Visier's Supported Browsers and System Requirements.
  • Enable single sign-on prior to embedding a visualization within your trusted domain. This ensures that users are authorized to view data within the visualization. For more information, see Set Up Single Sign-On.
  • Ensure that only trusted domains can embed Visier visualizations. You must list the domains (web addresses) of the applications that will be hosting the embedded visualization. Creating a list of trusted domains such as a production domain will ensure that unauthorized clients cannot access sensitive data. To ensure security, only HTTPS domains are allowed. For more information, see Add Your Domain to the Embeddable Domains List.
  • Confirm that the Embed Analytic Content capability or an administrator capability is assigned to your user. For more information, see Capabilities List and Assign Permissions to a User.
  • Make the analysis that contains the visualization publicly available in your production tenant. You cannot embed an analysis that only exists in a draft project. For more information about projects, see Projects.
  • 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. If turned on, Bypass for network prevents you from embedding Visier in your application, so be sure to turn it off before embedding.
  • Enable the sharing click-through link. For more information, see Step Five: Redirect users into your application.
  • Ensure that the user experience after clicking on the embedded visualization works as expected; for example, clicking on the visualization redirects the user to the full analysis or to the embedded Visier application. For more information, see Embed Visier With Distributed Access and Embed the Full Visier Application.

Step One: Copy the code snippet to embed

To embed a visualization in your application or web portal, the visualization must be part of a user-created or a Visier-provided Guidebook analysis. Visualizations are embedded as rasterized images, which are pixelated images with height and width values. Rasterized images are not interactive.

Note: This capability is currently limited to embed only the first visualization that is displayed within an analysis. To embed multiple visualizations, you must create multiple analyses.

  1. Navigate to an analysis. There are two ways to navigate to an analysis:
    • If you created the analysis and have the Embed Analytic Content capability:
      1. Open the solution experience and, on the navigation bar, click Analyses .
      2. Select the analysis you created that contains the visualization you want to embed in your application or web portal. The first visualization displayed in the analysis will be embedded in your target environment.
      3. In the upper-right corner, click the More items button > Embed Analysis.
    • If you are embedding a visualization from a Visier-created analysis and have an administrator capability:
      1. Open a project and navigate to Model > Analyses.
      2. In the list of analyses, hover over the analysis and click the Embed button . The first visualization displayed in the analysis will be embedded in your target environment.
  2. Enable the Embed for Child Tenants toggle. This allows your analytic tenants to inherit the feature.
  3. Copy the code snippet in the dialog, and then click Confirm.

Step Two: Paste the code snippet in your application

After copying the code snippet from Visier, open the source code for your own web application so that you can embed the code snippet in your system. The code snippet provides the minimum amount of code required to embed the visual. In addition to the code snippet, you can specify a few other options to customize the embedded visualization. For more information, see visierConfig fields below.

  1. Paste the code snippet into your source code.

    Note:  

    • Check that the correct loginURL is used in the code snippet. This URL must handle the automatic login workflow that triggers a SAML authentication request when loading the embedded visual. For more information, see Set Up Single Sign-On.
    • The code snippet is JavaScript that you must place inside an HTML (<script>) tag in your webpage. We recommend that you put the code snippet in the <head> element of your webpage. For more information, see tag_script and html_head.

    • We recommend that you only use a single instance of the sdk.v2.js file. The SDK is designed to handle a single instance, so using multiple instances may lead to unexpected results. With a single instance, you’ll get the best performance because the SDK only initializes once. Plus, you only have to manage a single session which makes usage tracking easier.

    • For more information about the SDK file in the code snippet, see SDK file history.
    • For more methods you can use with the visier function, see Embedding API Methods.
  2. Change the field containerId: "ENTER_CONTAINER_ID" in your portal to the id of the HTML element where you want to embed the visual. Ideally, the id is a <div> element.
  3. Optional: Customize the embedded visualization. For more information, see visierConfig fields below.

    Result: Anyone within your organization will be able to view the relevant visualization data with the correct user data security context.

The following code sample is an example of an HTML tag with Visier's code snippet.

Copy 
<!doctype html>
<html lang="en">


<head>
   <title>Embed Chart</title>
   <meta charset="UTF-8">
   <script>
        // Declare the visierConfig
            const visierConfig = {
                visierUrl: "https://example.visier.com/hr",
                idpUrl: "https://idp.example.com" // The idpUrl must point to the endpoint that automatically posts a SAML assertion to Visier.
            };

        // Add a script element pointing to the SDK and make its public functions available.
            (function(w, d, t, s, c, v, e, x) {
                w['VisierEmbedder'] = v;
                   w[v] = w[v] || function() {
                    (w[v].q = w[v].q || []).push(arguments)
                };
                   if (!d.getElementById(s)) {
                    // Add the script if it was not already added before.
                    e = d.createElement(t);
                    x = d.getElementsByTagName(t)[0];
                    e.id = s;
                    e.async = true;
                    e.src = c.visierUrl ? c.visierUrl + s : (c.loginUrl ? c.loginUrl.split("/auth/embedded")[0] + s : s);
                    x.parentNode.insertBefore(e, x);
                }
            })(window, document, 'script', '/assets/embedded/webAssets/sdk.v2.js', visierConfig, 'visier');

        // Bootstrap the SDK with the visierConfig.
            visier('bootstrap', visierConfig); {
                app.embedCharts([
                    {
                        contentId: "00000000-0000-0000-0000-000000000000",
                        containerId: "chart-container"
                    }
                ]);
            });
   </script>
</head>


<body>
   <div class="chart-container" id="chart-container">
       <p>Placeholder before chart is rendered</p>>
</body>


</html>

visierConfig fields

The following fields in the visierConfig code snippet allow you to configure how each embedded visualization is displayed in your application or web portal.

Field Description Type Required Notes
visierUrl The URL that handles the automatic login workflow that triggers a SAML authentication request when loading the embedded visual. Visier uses this URL to download the sdk.v2.js file.

string

Required

 

loginUrl (Deprecated)

 The URL that handles the automatic login workflow that triggers a SAML authentication request when loading the embedded visual. string Required Deprecated. Use visierUrl.
idpUrl

The IdP URL that handles hidden sessions and posts valid SAML assertions. For more information about SAML assertions, see SAML assertion parameters.

The idpUrl must point to the endpoint that automatically posts a SAML assertion to Visier. The session connection timeout limit is 5 seconds. If a session isn't connected in 5 seconds, the user sees a message. This enables the user to manually validate themselves against your IdP and establish a session with Visier using a popup window.

string Optional  

requestTimeout

 

The amount of time in milliseconds that Visier will wait while processing a request before stopping the request. If the default timeout of 10000 milliseconds (10 seconds) is too short, use this field to define a longer timeout time.

number

Optional

Default is timeout after 10000 milliseconds.

startSession

If true, the API authenticates immediately in the bootstrap call.

Boolean

Optional

Default is false.
charts An array containing the visualizations to embed. array of objects Required Define multiple objects to embed multiple visualizations.
  contentId The unique identifier of the visualization. string Required This is automatically included in the visual’s code snippet.
containerId The container where you want the visualization to appear. string Required This is a container in your code.
width

The width in pixels of the rasterized image.

Caution: Do not set a dynamic width. This will break the caching.

 number Optional If you do not define width, the default is a large visualization.
height The height in pixels of the rasterized image. number Optional If you set width, height is not required. If width is not set, height defines how to shrink or grow the rasterized image.
filters An array that represents the filters to apply to the visualization. array Optional For more information, see Pass Filters with Embedded Visier Visualizations.
  includeExclude An object representing the dimension members to include or exclude in a visualization. object Optional For more information, see Include/exclude filter.
numericRangeFilter An object representing a range of numbers to filter by in a visualization. object Optional For more information, see Numeric range filter.

Step Three: Run your web application

In your web application, you should now see Visier content in place of the HTML element you provided as containerId.

The following screenshot is an example of an embedded visualization.

Event handling

Visier's embedded APIs emit events, each of which emit a message with a message code, a localized string describing the code, and the source of the message. You can set up handlers to listen to each event type, and target specific embedded visualizations using the source field that's returned in the message.

The following examples illustrate different event handling options available to you.

  • For chart failures, you can listen on error events and hide the visualization because it will likely be empty on failure.
  • For charts taking time to load, you can listen on info events and hide the chart until a EMBEDDED_CHART_RENDERED message is emitted.
  • For passing in dynamic filters, you can listen on info events and wait until a EMBEDDED_CHART_READY_FOR_FILTERS message is emitted. This message is emitted after Visier's listener is set up, but before the visual is loaded or rendered. You can then make a POST request to pass in the filters. For more information about filters, see Pass Filters with Embedded Visier Visualizations.

You can create event handlers to listen to the iframe events with the function on with the visier function, as shown next.

visier('on', eventName, handlerFn);

Note:  

  • eventName is one of info, error, session, or debug.
  • handlerFn is the event handler function that takes in an emitted event as an input parameter. This should be the name of your event handler function; it does not have to read "handlerFn". The emitted event has the following message structure:
    Copy
    interface EventMessage {
        code: string;
        message: string;
        source: string;
    }

Events

Info event type

Info is an informational event, such as if the visualization is rendered. The following table defines the possible info messages.

Message Description
EMBEDDED_CHART_READY_FOR_FILTERS The embedded chart is ready to accept dynamic context filters.

EMBEDDED_CHART_RENDERED

The embedded chart has finished rendering.

VISIER_APP_LOADED

The embedded application loaded successfully. You can use this event to keep track of whether the app is already loaded to prevent loading more than once.

Error event type

Error is an error event for failures that prevent the app or embedded visualization from continuing, such as incorrect configurations. The following table defines the possible error messages.

Message Description

Applicable To
CANNOT_FIND_ANALYSIS The given analysis could not be found. The ID may be invalid, it may have been deleted, or the user does not have access.

Embedded visualizations only
CANNOT_FIND_CONTENT Could not find a valid visual in the provided analysis for embedding.

Embedded visualizations only

CHART_DATA_ERROR

Chart data was not present or incorrect type was found.

Embedded visualizations only

CONFIG_INVALID

Chart config is invalid. The chart field in the config should be an array of objects.

Embedded visualizations only

CONTAINER_MISSING

The container to embed the content in cannot be found.

Embedded application or embedded visualizations

FILTERS_NOT_DEFINED

No filters were defined when invoking dynamic filters.

Embedded visualizations only

INVALID_APP_URL

Either an invalid URL was passed to the embedApp method or no default URL could be found.

Embedded application only

INVALID_COMMAND

Cannot embed content. Feature flag disabled.

Embedded application or embedded visualizations

INVALID_FILTER_MEMBER

No driving analytic object found.

Embedded visualizations only

SW_LOADING_TIMEOUT

These timeout errors emit if there are unexpected issues with the authentication set up or if the set up took longer than expected, such as due to network latency. Possible causes include:

  • The IdP failed to authenticate the user. Check the Network tab.
  • The service worker failed to load. Look for errors in the Console tab and turn on enableDebugLogging.

Embedded application or embedded visualizations

UNSUPPORTED_FILTER_TYPE

An invalid filter was found. The filter syntax may be incorrect.

Embedded visualizations only

VISIER_APP_DOWN

When Visier is unavailable, render and log an error message.

Embedded application or embedded visualizations

Session event type

Session is an event that is emitted during stages of session management, such as when the platform is attempting to establish a session. The following table defines the possible session messages.

Message Description
AUTO_LOGIN_FAILED

Failed to authenticate the user. Scenarios in which this message may be emitted include, but are not limited to:

  • Failed to authenticate with your IdP because the IdP is not configured properly or is down.
  • Failed to initiate authentication with Visier. Your IdP is not properly configured to send the SAML response to Visier's servers.
  • Failed to authenticate with Visier; for example, the user doesn't exist and auto provisioning is disabled.
  • Authentication process took too long. We recommend extending timeoutRequest in visierConfig in the case of network latency or slow servers.
  • The embeddable domain wasn't added in Visier. There's usually an accompanying error log in the browser's Console stating that it refused to frame the given site due to the content security policy. We recommend checking if your IdP and embedding site was added to the list of emeddable domains in Visier. For more information, see Add Your Domain to the Embeddable Domains List.
SESSION_ERROR

Represents a blocked user flow. Scenarios in which this message may be emitted include, but are not limited to:

  • The SSO configuration for the specified Visier tenant is incorrect or disabled.
  • Auto provisioning is disabled and the user does not have a Visier profile.
  • The tenantCode claim in the SAML assertion is invalid.
  • The SAML assertion sent to Visier's ACS URL is malformed.

SESSION_ESTABLISHED

This message is emitted once an authenticated session has been established with Visier for the current user. We recommend starting a background process to keep the Visier session alive on a regular interval after the session has been established.

USER_AUTO_PROVISION_FAILED

Represents a blocked user flow. The user doesn't exist in Visier and a new Visier user couldn't be created for the current user. Auto provisioning must be enabled. For more information, refer to the message.

USER_AUTO_PROVISION_SUCCESS

This message is emitted when a new Visier user is created automatically for the current user. Auto provisioning must be enabled in your Visier tenant's settings under "Tenant Single Sign-On" and it must be the first time this user is using Visier.

VISIER_SESSION_ALIVE

These events are emitted when the user is active in the Visier application. This allows the parent application to keep its own user session alive when the user is active in Visier but not in the parent application. By default, these messages are emitted once every five minutes, but this can be configured in your Visier tenant under "Embedded App Config".

VISIER_SESSION_EXPIRED

If the user is active in the parent application but not in Visier, the user's session in Visier can expire.

Note: Sending the Visier application iframe PARENT_SESSION_ALIVE messages, as in keepVisierSessionAlive(), prevents the Visier session from expiring. Best practice is to handle expired Visier sessions nonetheless.

To create a new session in the background, call embeddingApp.bootstrapSession();. Once complete, new requests will pick up the new authentication tokens.

Alternatively, call embedApp to restart the process again, including authentication. This will reload the application, which will help clear any errors surface earlier due to the session expiry.

Debug event type

Debug is an event that emits debugging information, including a unique code and time stamp for when the event occurred.

A majority of Visier's embedding logic occurs in the web client, unseen and untracked. You can use debug events to facilitate the debugging process with Visier. If you encounter unexpected errors that you can't resolve, you can reproduce the issue with these debug events logged to your browser Console and then share a copy of the Console logs with Visier Technical Support. You can optionally share the the HAR file from the Network tab as well.

Navigate event type

Navigate is an event that emits internal and external routing information, such as if a user navigates from Guidebooks to Analyses. The following table defines the possible navigate messages.

Message Description
NAVIGATE_EXTERNAL

Indicates navigation from one application to another.

NAVIGATE_INTERNAL

Indigates navigation within Visier; for example, from Guidebooks to Analyses.

SDK file history

Review the latest changes to the sdk.v2.js file.

Last updated date

Changes

August 7, 2024

Added support for embedding multiple full application iframes on the same page. This change includes:

  • New visier-container parameter for navigate that allows you to specify an iframe ID. This parameter is required if embedding more than one iframe.
  • New navigate event. This event emits internal and external routing information, such as if a user navigates from Guidebooks to Analyses.

January 10, 2024

Because Google is deprecating third-party cookies, we updated sdk.js to sdk.v2.js. V2 ensures a more resilient integration framework by minimizing dependencies on browsers like Chrome. Failing to adopt these changes will result in users being unable to access analytics in Visier where you've embedded it in your applications. Google's grace period allows transitioning away from third-party cookies until June 30, 2024. This means you have until June 30, 2024 to transition to sdk.v2.js. If you embed the full Visier application and individual Visier visualizations, please ensure that both embedding methods now use sdk.v2.js.

In this section