A Mode report can be embedded into another website, such as a private wiki, blog, or any other website or application with access to the internet. An embed will display the full contents of the underlying report including charts, tables, and other custom visualizations. Any report can be embedded as either an Internal Embed or a White-Label Embed (WLE), depending on your needs.
An Internal Embed built using your private data is only visible to logged-in members of your Mode organization who would otherwise have access to the underlying report. Here’s an example of what an Internal Embed looks like:
Click the green Powered by Mode link at the bottom of the embed to open the underlying report in Mode.
NOTE: Generally, you must be logged in to Mode and have access to the underlying report in order to view an Internal Embed. However, the above embedded report is built on Mode’s Public Warehouse and is therefore viewable by anyone on the internet. Learn more about embedding reports built on Mode’s Public Warehouse.
A White-Label Embed (WLE) may be seen by viewers who are not logged in to Mode or members of your organization who do not have access to the underlying report. For a given embed, your host application securely controls who can see what using a signature process (and optionally, using parameters).
A White-Label Embed differs from an Internal Embed in a few key ways:
- No Mode viewer authentication: With WLEs, the embed host application, instead of Mode, handles any required viewer authentication and programmatically controls access to the embedded reports by generating a unique, rapidly-expiring signed embed URL and (optionally) parameters.
- No Mode branding: There is no Mode Analytics branding in the embed border or loading animation.
- Reduced viewer interactivity: Some interactive features of Mode’s built-in charts and tables are not available, including some drill-down features and chart-specific URLs.
- Reduced underlying data access: To prevent unintentional leakage of sensitive data, viewers cannot see any of the underlying report’s metadata, code, historical runs, or query results. You may, however, elect to expose the ability for viewers to download a CSV of the embedded report’s results in your host application.
To show a White-Label Embed in action, we built a lightweight analytics portal for a fictional paper company named Parch & Posey. The analytics in the portal are provided by two parameterized and White-Label Embedded Mode reports.
Access the Parch & Posey example portal using any of the following credentials:
When accessed, the portal runs the embedded reports with a parameter value specific to the logged-in customer. This means that the embeds will display data only for the logged-in customer. If a viewer attempts to change the embed URL in any way (including the parameter value) and then access the URL, the signature will no longer be valid and the URL will return an error.
To embed a report, the following requirements must be met:
- The Mode organization containing the target report must be on a paid plan.
- If you plan to implement a White-Label Embed, White-Label Embeds must be included in your organization’s paid plan.
- The creator of the embedded report must be an active member of the same Mode organization that contains the report.
Embed a Mode report into a host application by following the steps below.
Create an embed URL
An embed can point to either a standard report URL (which displays results from the most recent report run) or a static report run URL (which displays results from a specific run).
TIP: Static report run URLs always include
/runs/[RUN_TOKEN]/in the URL path.
Obtain the the URL that suits your specific case and add
/embed to the end of the path, for example:
Set refresh frequency
Control how often your embed refreshes by specifying a
max_age in the embed URL query string. The
max_age specifies the maximum allowable age, in seconds, that a cached report run’s results may be:
- If the report has never run or the most recent run of the report is older than the specified number of seconds, the report will be fully run when accessed. Otherwise, the most recent report run results from Mode’s servers will be returned.
- If the URL query string includes values for parameters, Mode will return the most recent cached results using the same set of parameter values as long as those results are not older than the value of
max_age. If the report has never been run with the specified parameter values, Mode will run the report using them.
This ensures the embedded report’s data is refreshed as regularly as necessary while allowing you to balance the load the embed places on your database. For example, including
max_age=3600 in the URL query string ensures that the underlying report will refresh once the most recent results are more than 3600 seconds (i.e., one hour) old.
TIP: A valid embed URLs must include a
max_age. To ensure the embedded report’s data is refreshed every time the embed is accessed, specify
The following example URL will update all queries and visualizations in the target report if it was last run over 3600 seconds (i.e., 1 hour) prior to being accessed:https://modeanalytics.com/benn/reports/31baa986cdfd?max_age=3600
Specify parameter values (if required)
A field-value pair must be provided for each report parameter, if any are defined in the underlying report.
For example:https://modeanalytics.com/[ORG_NAME]/reports/[REPORT_TOKEN]/embed?param_sales_region=North%20America ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TIP: Remember to URL encode parameter values with special characters.
Sign the embed URL (WLE only)
IMPORTANT: The following steps only apply if you are implementing a White-Label Embed. If you are implementing an Internal Embed, skip to the next step.
To create a signed embed URL, follow the steps below to add three fields to the query string: a
timestamp, a signature token
access_key, and a unique
signature that your host application generates each time the embed is rendered.
Before you begin, ensure your back-end environment has access to the following information:
- Signature token: Generated by an admin of the organization that contains the target report. Ensure you have both the public access key and private access secret.
- Embed URL: Includes the full path and query string (from the first two steps of this guide).
- Dynamic parameter values: All parameter values, including dynamically generated ones from your application’s database, (e.g., customer ID, etc.) must be URL encoded. You’ll need these values to build the request URL (outlined in step 2 below).
- Current timestamp: The current time, in seconds, in UNIX epoch time.
IMPORTANT: Your host application must create the
signatureusing a process that is not transparent to embed viewers. Exposing your signature token’s access secret in front-end, client-side code will compromise the security of your Mode account.
1. Enable WLE for the report
White-Label Embedding must be explicitly enabled on a report-by-report basis. To enable it:
- Open the report that you want to White-Label Embed and click Edit in the header.
- Select Embed in the header.
- In the pop-up, click the White-Label Embed tab.
- Toggle the switch so it says White-Label embedding of this report is ON.
TIP: If you don’t see the White-Label Embed tab, your organization does not have White-Label Embeds enabled. Contact your organization’s Mode admins or Mode support to learn more about enabling White-Label Embeds.
2. Build request URL
To create a valid request URL from an embed URL:
- Add the
access_keyfields to the query string, set equal to the current UNIX epoch time and the signature token access key, respectively.
- Sort the query string alphabetically by field name.
For example:https://.../embed?run=now¶m_sales_region=North%20America https://.../embed?access_key=9a51794bgrb3¶m_sales_region=North%20America&run=now×tamp=1532446786 ^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^ Access key Sorted alphabetically UNIX epoch time
3. Generate a signature
To sign your WLE embed URL, you must first construct a
request_string will be hashed to create the signature.
request_string consists of a constant (
GET,,1B2M2Y8AsgTpgAmY7PhCfg==), your request URL, and the current timestamp, separated by commas. For example:
IMPORTANT: The fields in the
request_urlquery string must be in the order given above (i.e., sorted alphabetically) or the signature will be invalid.
Now, generate a signature by creating a base64-encoded SHA256 hash of the
request_string using the signature token access secret as the
secret (i.e., hashing key). For example:
4. Create a signed embed URL
Create a signed embed URL by adding the
signature field, set equal to the signature generated in the previous step, to the end of the query string of the
request_url. For example:
The signed embed URL will now provide access to the specified report. If any part of the URL is changed or if the signature expires (which happens after 10 seconds), your host application must regenerate the signature.
The following examples show how to assemble a
request_string and generate a signed embed URL given a signature token
timestamp, and a
request_url with all components of the query string already in alphabetical order:
Place the embed URL into an iframe
To finish creating your embed, add an iframe to your host application with the
src attribute set equal to the embed URL (for an Internal Embed) or signed embed URL (for a White-Label Embed). For example: