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 the following versions: :
-
IBM®
Cognos® Analytics
on-premises
-
IBM
Cognos Analytics on
Cloud Hosted
It is not available in the Cognos Analytics on Cloud On-Demand.
Procedure
- Open a dashboard from Content.
- 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.
- Click the Embed icon
in the toolbar.
- Click the Copy icon
to copy the code snippet.
Note: The next steps require web developer skills.
- 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.
- Paste the snippet into the HTML file.
- 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.
- Save the HTML file.
- 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.
Note: Before you make any changes, review
the appropriate CORS documentation for your environment and tools. For more information, see
CORS
protocol.
The following example illustrates the headers that you need to add for an HTTP Apache
server:
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, x-audit-dashboardid"
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"
<If %
{REQUEST_METHOD}
== OPTIONS>
RedirectMatch
204 .*
</If>
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.