Embedding visualization code

You can use a code snippet to easily embed dashboard visualizations in websites or in applications that support HTML.

About this task

You do not need to use public Application Programming Interfaces (APIs) to embed visualizations in websites. Instead, use the Embed function that is available in the dashboard toolbar. This function generates a code snippet that can be put into the code of a website.

Important: This function is available only in IBM® Cognos® Analytics on-premises.

Procedure

  1. Open a dashboard from Content.
  2. After saving changes that you made in the dashboard, select one or more visualizations that you want to embed.
    You can only embed visualizations that are available in the System section of the Visualizations gallery.
  3. Click the Embed icon in the toolbar.
  4. Click the Copy icon to copy the code snippet.
    Note: The next steps require web developer skills.
  5. In an HTML editor, create new HTML file or open the file with the code of the website in which you want to embed visualizations.
    Attention: The HTML file must start with the <!DOCTYPE html> declaration.
  6. Paste the snippet into the HTML file.
  7. Fit embedded visualization to the website:
    • Specify the height of the visualization that you want to embed in pixels for all HTML containers.

    • If you want the language of the visualization to be different than the language of the website, define the language of the visualization in the snippet. For example, to set the product language (pl) to French and the content language (cl) to German, add the query string ?pl=fr&cl=de in the first script element of the snippet:

      .../bi/dashboard/js/api/CognosDashboardApi.js?pl=fr&cl=de

    If only one of the languages is set with the string, this language will be used to both the product and the content.

    If no language is set, the local language of browser will be used.

    Note: The content language is defined by letters and might include a territory variant. For example, use en-US to set English that is used in the United States of America.
  8. Save the HTML file.
  9. If you embed your visualization in a website that is on a domain other than your Cognos Analytics installation, you must enable Cross-Origin Resource Sharing (CORS) for the server in Cognos Analytics. To enable CORS, you can use one of the following ways:
    • Configure the Configuration.cookieSameSite advanced setting in Cognos Analytics. For more information, see Setting the cookieSameSite attribute.
    • Add headers to the configuration of your HTTP server. For example, for HTTP Apache server, you need to add the following headers:
      Header always set Access-Control-Allow-Origin "https://host name:port number"
Header always set Access-Control-Allow-Headers "Content-Type, Content-Encoding, X-Xsrf-Token, X-Audit-Datasearchpath, X-Audit-Type, X-Queryuserid, X-Model-Last-Modified, X-Audit-Searchpath, X-Qs-Querycontext-Id, X-Ca-Affinity, Etag, X-Ca-Transaction, X-Compressed-By, X-Qs-Request-Id"
Header always set Access-Control-Expose-Headers "X-Ca-Affinity "
Header always set Access-Control-Allow-Credentials "true"
Header always set Access-Control-Allow-Methods "POST, GET, PUT, DELETE, PATCH, OPTIONS"
Header onsuccess edit Set-Cookie (.*) "$1; SameSite=None; Secure"

Results

An embedded visualization is now visible on the website. To interact with an embedded visualization, click the visualization and log in with your Cognos Analytics credentials. Such interactions do not affect original visualizations because they are limited to consumer actions.