Mode White-Label Embeds make it easy to integrate embedded analytics into your application or customer portal.

Acting as a seamless part of your application, White-Label Embeds securely deliver the right data to the right customers on demand. With Mode, your team can ship winning customer-facing analytics initiatives in a matter of days, not weeks or months. White-Label Embeds are:

  • Powered by the simplicity of SQL queries managed in Mode
  • Customizable to match your brand
  • Securely integrated into your app with just a few lines of code

Molecule's customer-facing reporting [Molecule’s customer-facing reporting, built into their application with White-Label Embeds]

Experience White-Label Embeds in Action

As a companion to this guide, we’ve built a very simple site to provide examples of White-Label Embed capabilities within an application. Parch and Posey is a (hypothetical) company that sells paper to a wide range of customers. Using White-Label Embeds, Parch and Posey is able to share personalized insights with each of its customers. Log in to Parch and Posey’s portal here any of the account following credentials:

Username Password
walmart pw
merck pw
utc pw

Once logged in, explore the following key features of Mode White-Label Embeds.

Interactivity

There are a several options for providing interactivity with White-Label Embeds that range in complexity. Generally the simplest solution that solves for your intended use case is best, as it will require less time and effort to implement.

  • Leverage natively interactive chart types. Try clicking on any of the charts in the example to focus on different series. The simplest solution for providing interactivity is to utilize chart types that are inherently interactive. Some options include:
    • Multi-series charts. Mode native multi-series charts provide your customers with the ability to toggle series on and off.
    • Pivot tables. Mode pivot tables allow your customers to explore datasets with dynamic grouping, filtering, and aggregation.
    • Plotly Python charts. With Plotly and Mode you can build beautiful, interactive data visualizations on top of a dataset in Python.
  • Add Mode Filters. Allow report viewers to instantaneously filter the dataset and visualizations. After signing the White-Label Embeds URL, you can add a snippet to your page to include a button that opens the Filters. Plus, with the Mode API, you can customize the Filter toggle to match the rest of the embed aesthetic.
  • Create filters in HTML. You can create data filters by adding custom HTML to your report. In the example reports, try toggling between monthly and quarterly views to see HTML filters in action. We’d also be happy to tell you more about the powerful filtering capabilities coming soon.
  • Add a form to your application. If you want to allow for an even greater level of interactivity (such as toggling to a completely different chart type), you can add a form to your application which enables end users to toggle between different parameters. Those parameter values can be used to customize the embed URL with your user’s selections. The application can then generate a new signed URL and refresh the embed to display the resulting report with the user’s selected parameters. In Parch and Posey’s White-Label Embed, you can toggle between an account overview with several charts and tables, or a detailed breakdown of every order.
  • Enable CSV exports. Empower customers to download their data as a CSV. This doc explains the process of enabling CSV exports from White-Label Embeds.

Interactive White-Label Embeds

Custom visualizations

Click the “All Orders” tab. Here you’ll find a completely custom data visualization. It’s built using HTML, CSS, and JavaScript that’s hosted in Mode right along side your SQL query. There’s no limit to what you can create.

On-brand reports

Molecule’s embedded analytics offering, featured at the beginning of this guide, is a great example of how flexible Mode’s out-of-the-box charts can be. By simply modifying the CSS of our pre-built charts, you can completely change the look and feel to match your application. Check out this guide for some tips on getting started.

Setting up White-Label Embeds

Now that you have an idea of what you’d like to create for your customers, here’s how to get started.

Enable White-Label Embeds for your organization

White-Label Embeds are a premium feature. To learn more about White-Label Embeds, reach out to your Mode account manager or contact our success team.

Create an access key and secret

Create a new token from the Signature Tokens tab. When you create the token, make sure to save your secret in safe place. You’ll need this secret to sign embeds. Because the access secret can provide access to reports in Mode, treat the secret the same as you would your Mode password.

Create a report in Mode

Create a report in Mode with the data you want to share.

Start by writing the SQL queries that return the desired data for one specific customer. Using the Report Builder, create the layout to embed in your application. Click “Edit HTML” to start customizing.

Once you’ve completed the report tailored for one specific customer, replace their identifier in the SQL query/queries with a parameter that your application will interact with to show data personalized to the user. For example, using a field like account_id as a parameter will enable your customers to see only data associated with their account.

Create an embed URL

Mode reports can be embedded using iframes or JavaScript links. Embeds can be created by clicking on the “Share” menu on a report, and selecting the embed tab. This will generate an embed snippet like the one below.

<iframe src="https://modeanalytics.com/my_organization/reports/aaabbbcccdd/embed" width="100%" height="300" frameborder="0"></iframe>

White-Label Embeds use the same structure, but require modifications to the URL in the embed snippet.

To create a White-Label Embed, first add two additional query strings to the URL in the embed report parameter values and a max age. These can be added to the URL using the following syntax.

.../embed
 ?param_foo=bar // Parameter "foo"
 &max_age=3600 // Max age

Determine who sees what

  • Parameters: The parameter query string allows you to display different results to different viewers. You can pass parameter values using a param query string, which should be formatted as param_PARAMETER_NAME=PARAMETER_VALUE. If you pass in a parameter value, the embed will either run the report with the chosen value, or show the last run of the report that used that parameter value.

Determine the report update cadence

  • Max age: This query string specifies how old, in seconds, of a run you want to display. If the last run is more than the max age value old, the report will rerun; if it’s been run more recently, the embed will show that run.

In the example above:

  • If the report has never been run where foo=bar, the embed will run the report with foo=bar and display the result when the report finishes.
  • If the report has been run where foo=bar but that run occurred more than 3,600 seconds ago, the embed will run the report with foo=bar and display the result when the report finishes.
  • If the report has been run where foo=bar and that run occurred less than 3,600 seconds ago, the embed will show the most recent run where foo=bar.

To create a White-Label Embed, your application should first generate an embed URL with the correct query strings. In most cases, you’ll want to pass contextual information about the current application viewer as a report parameter. This will ensure that the viewer will see data relevant to them.

Sign the embed URL securely

Once your application has created an embed URL, it will need to sign that URL. You sign embeds by adding three additional query strings to your URL: timestamp, access_key, and signature.

The final signed URL will look like this:

.../embed
 ?access_key=ACCESS_KEY
 &max_age=3600
 &param_foo=bar
 &signature=SIGNATURE
 &timestamp=TIMESTAMP
  • Timestamp: The current timestamp in Epoch time, in seconds.
  • Access Key: A signature token access key created in Step 2 of Enabling White-Label Embeds.
  • Signature: A hexadecimal SHA256 hash of your embed URL. This signature verifies the authenticity of your request and prevents people from tampering with the URL.

URL signatures must be created via a process that isn’t transparent to your end users (e.g., by your application server).

Signatures must not be created by the site or client hosting the embed; doing so may expose your access secret and compromise the security of your embeds.

To create a signature, you should first create an embed URL like the one outlined in Create an Embed URL. Next, add the timestamp and access_key query strings to this URL, and order the query strings alphabetically. The resulting URL should match the format below.

// VALID URL
.../embed
 ?access_key=ACCESS_KEY
 &max_age=3600
 &param_foo=bar
 &timestamp=TIMESTAMP

 // INVALID URL - Query strings out of order
 .../embed
 ?param_foo=bar
 &max_age=3600
 &timestamp=TIMESTAMP
 &access_key=ACCESS_KEY

 // INVALID URL - No timestamp and access key
  .../embed
  ?param_foo=bar
  &max_age=3600

Next, create a request string for your embed. This string should have five values, separated by commas.

  1. An HTTP verb. For White-Label Embeds, this should always be GET.
  2. The request content type. For White-Label Embeds, the request type should be an empty string.
  3. An MD5 hash of the request body. For White-Label Embeds, the request body will always be an empty string, so the MD5 hash will always be 1B2M2Y8AsgTpgAmY7PhCfg==.
  4. The request URL. This should be the URL—the one containing an access key and timestamp—created above.
  5. The current timestamp. This should match the timestamp in the URL.

The resulting string should match this format.

'GET,,1B2M2Y8AsgTpgAmY7PhCfg==,``https://modeanalytics.com/ORGANIZATION_NAME/reports/aaabbbcccdd/embed?access_key=ACCESS_KEY&max_age=3600&param_foo=bar&timestamp=TIMESTAMP,TIMESTAMP``'

Finally, create a signature from this string. The signature should be a hexadecimal SHA256 hash of the string, and should use your access secret created in Step 2 of Enabling White-Label Embeds as the key.

 ## Creating a signature in Ruby
digest = OpenSSL::Digest.new('sha256')
signature = OpenSSL::HMAC.hexdigest(digest, ACCESS_SECRET, request_string)

Append this signature to your embed URL, as shown in the example at the start of this section and duplicated below. (Note that the query strings in the signed URL don’t need to be in alphabetical order.)

.../embed
 ?access_key=ACCESS_KEY
 &max_age=3600
 &param_foo=bar
 &timestamp=TIMESTAMP
 &signature=SIGNATURE

This embed URL will now provided access to the specified report. If any part of the URL is changed—including the report identifier, the parameter value, the max age value, or the timestamp—the URL won’t work. Moreover, the URL expires after 10 seconds, ensuring that even valid URLs can’t be saved and reused.

Click here for some examples of how to generate signed URLs.

Parameters

You can add Parameters which are interactive forms to White-Label Embeds so that people viewing your embeds can update the data that they see in the embed. Before adding Parameters to your White-Label Embeds, you’ll need to set up your application to sign embed URLs, which is outlined in the article on getting started with White-Label Embeds.

Because Mode’s built-in Parameter forms can’t currently be added to White-Label Embeds, you can add Parameters to a While-Label Embed by adding a form to your application. Those Parameter values can be used to customize the embed URL with your user’s selections. The application should then generate a new signed URL and refresh the embed to display the resulting report with the user’s selected Parameters.

The diagram below outlines this in more detail.

Adding Parameters to White-Label Embeds

  1. Create a way for users to select Parameters in your application.
  2. Users can select these Parameters, which get passed to your application’s server.
  3. The server adds these Parameters to embed URL. The specifics of the embed URL are described here, and should follow the format shown below (the user-selected Parameters value is in {}):

    .../embed
    ?access_key=ACCESS_KEY
    &max_age=3600
    &param_foo={user_selected_parameter}
    &signature=SIGNATURE
    &timestamp=TIMESTAMP
    
  4. The application signs the new embed URL using the same method to sign any White-Label Embed URL.

  5. The application updates the embed with the new signed URL to display report results for user-selected Parameters.

  6. You can now test your White-Label Embed to see what it looks like and verify your application is signing embeds correctly. If you run into any error messages, check out this troubleshooting guide.

Mode’s White-Label Embeds allow report viewers to export raw data, enabling teams to explore datasets that power these reports.

While signed embeds must be generated on your application’s server, export links only require updating the client hosting the embed. This is made possible by providing a link to directly download the CSV. Query names and query results, including results not displayed in the embed itself, are included in the CSV. Please ensure you are comfortable with exposing this information to whomever may export the data.

Enabling CSV Exports

  1. Generate the signed embed and embed it to your application.

    Example: The code below shows a simple site containing a white-label embed.

    <h1> My Customer Portal </h1>
    
    
    <iframe src="https://modeanalytics.com/org_name/reports/report-token/embed?access_key=[access_token]&max_age=[max_age]&param_bar=foo&timestamp=[timestamp]&signature=[signature]" width="100%" height="800" frameborder="0"></iframe>
    
  2. When the embed loads, it will post a message that contains a download URL.

  3. Add the event listener to the page so users can retrieve the download.

    Example: The following script adds this URL to a download link on the page.

    <h1> My Customer Portal </h1>
    
    
    <iframe src="https://modeanalytics.com/org_name/reports/report-token/embed?access_key=[access_token]&max_age=[max_age]&param_bar=foo&timestamp=[timestamp]&signature=[signature]" width="100%" height="800" frameborder="0"></iframe>
    
    
    <a id="csv-export-link" href=""> CSV Export </a>
    
    
    <script>
      window.addEventListener('message', function (e) {
        // always check the origin and make sure it is from modeanalytics.com
        if (e.origin === 'https://modeanalytics.com') {
          if (e.data['type'] == 'reportExportPaths') {
           var modeBaseUrl = e.origin
           var csvExportUrl = e.data['report_csv_export_path']
           csvExportLink = document.getElementById('csv-export-link')
           csvExportLink.href = modeBaseUrl + csvExportUrl
          }
        }
     })
    </script>
    

Note:

  • The CSV download link is generated every time a White-Label Embed renders and expires after 24 hours.
  • If the White-Label Embed is not signed correctly, the embed will not post an event.

Managing permissions within your organization

Given that you are using White-Label Embeds to power in-app analytics for hundreds of customers, you may want to limit who can access the source reports in Mode. To manage reports access permissions move them into private Spaces, which only authorized people can access. This is a good way to ensure someone doesn’t inadvertently interfere with the reports powering your White-Label Embeds.

Testing and troubleshooting

You can test your White-Label Embeds using this handy form.

If you encounter any unexpected issues, check out this troubleshooting doc which addresses some common errors and don’t hesitate to contact our success team.

Embedding in Salesforce

Getting started

Mode reports can be embedded into Salesforce using VisualForce objects. They can be configured so that the Mode report will refresh when a page is loaded in Salesforce, and, if desired, the Mode report can accept parameters that are pulled from Salesforce objects (such as a customer ID). Here’s an example:

Embed Mode Reports in Salesforce

In order to do this, you need to have permission in Salesforce to create VisualForce objects, to change page layouts in Salesforce. In addition, you will need the ability to embed a Mode report.

Steps to embed

Preparing a Mode report for embedding
  1. Start by making a report.
  2. Add parameters to your report as desired. In the example below, we use a parameter called organization_id, which represents the unique id of a customer. This allows us to show the results for the appropriate customer when an Account Executive loads that customer’s Account page in Salesforce.
  3. When the report is ready, click Share and select Embed. Copy the code under <iframe> and save it for the next steps.
Create the Visualforce Page
  1. Navigate to Setup -> Develop -> Visualforce Pages. Click the “New” button.
  2. Give it a name like “AccountOrgStats”. We recommend starting the name with the Salesforce object in which you intend to display the Mode embed. In this example, the embed will go in the Account object.
  3. Drop this code into the editor:

    <apex:page standardController="Account">
    <apex:iframe src="<REPORT EMBED URL>?run=now&param_<PARAMETER NAME>={!<SALESFORCE FIELD>}" scrolling="true" frameborder="0" />
    </apex:page>
    
  4. <Report URL> can be copied by navigating to desired report and clicking Share -> Embed. Copy the iframe embed code, then just paste in the URL (don’t use the entire code snippet). You should already have this from step 3 in Mode (see above).

  5. <Parameter> Name can be found in the SQL code of that report. You should copy it exactly as it is referenced in the SQL.

  6. <Salesforce Field> is referenced as <object>.<fieldname>. Note that custom fields have the suffix __c. That’s two underscores and a lower case “c.”

  7. Note: You can see that we’ve set standardController="Account". You’ll want to change this if the VisualForce page will go on a different Salesforce Object

  8. Here’s what the code looks like when populated with all the information:

    <apex:iframe src="https://modeanalytics.com/modeanalytics/reports/2277bhs889d5a1cd/embed?run=now&param_organization_id={!Account.OrganizationAccountID__c}" scrolling="true" frameborder="0" />
    </apex:page>
    
  9. Once you enter this, click “Save”

Add the Visualforce Page to your desired object
  1. Go to Setup -> Customize -> Accounts -> Page Layouts. Click “edit” next to “Account Layout.” Note that if you are adding your Visualforce Page to a different object in Salesforce, substitute that object name for “Account” in this step.
  2. At the top of the main window, there is a box with a bunch of options for things you can drag into your report layout. Select Visualforce Pages, then drag Section onto the page where you’d like the Mode embed to go. In the popup, Select 1 column. Give it a name.
  3. In the same box where you found Section you will find the VisualForce page you created. Drag it into the Section you just added to the layout.
  4. Edit the properties on the Visualforce Object (not the Section) by hovering on it and clicking the gear icon in the upper right. Change the width and height to your liking.
  5. Go back to Customize -> Accounts -> Page Layouts and do this same thing for “Admin Account Layout” and any other layouts in which you’d like to see the embedded Mode report.

Embedding in WordPress

Getting Started

To easily integrate custom, interactive analytics directly into your WordPress site, use our plugin with Mode White-Label Embeds. This plugin also makes it simple to add Parameters to your embedded reports. Admins can set up user authentication Parameters or tokens to ensure viewers only have access to the data they are meant to see.

Embed Mode Reports in WordPress

To embed your report into the WordPress site, you will need to create a White-Label Embed first. Visit this page for setup instructions. Once are you done, use this tool to see what your White-Label Embeds will look like and verify your application is signing the embeds correctly.

Tip: This User Switching Plugin can help you quickly swap between user accounts in WordPress. This is handy for seeing what your users are able to see on each page, or for admins to switch between multiple accounts to manage reports.

Steps to embed

Create an access key and secret

A Mode admin must create a Mode access key and access secret; these will be used to create the White-Label Embed and to authenticate in WordPress. To create these tokens:

  1. Click on the avatar to open Organization Settings.
  2. On the navigation panel, click on Sharing and Embedding.
  3. Create a New Signature Token within the Embedding tab to sign embeds.

Note: Because the access secret can provide access to reports in Mode, treat the secret the same as you would your Mode password.

Step 1: Add Org or User Specific Parameters in Mode

Mode allows you to parameterized reports. Learn how to add a Parameter to your query.

Step 2: Create a User-Specific Token in WordPress
  1. Go to User Settings and then select a User Profile.
  2. Scroll to the bottom of the user profile page.
  3. Select Add Token.
  4. Create a unique token in the Token Name. We recommending creating one token per report.
  5. In Custom Value, enter the parameter value you intend to replace the token with. The parameter value should be specific to the user who is viewing the report. Make sure that the value you insert to substitute the token is the same value that you’ve assigned in your Mode report.
Step 3: Add Token Parameter into a report in WordPress
  1. Go to Settings then Mode Analytics.
  2. In the Parameter section of the report, enter the following:
    • Parameter Slug: The same Parameter you used in the Mode Report.
    • Data Type: Select Text, as the Default Value will be the User Token you created above.
    • Default Value: The user-specific token name you created on the WordPress User Profile above.
1) Install the Mode WordPress plugin

To start, your organization should have a WordPress.com Business account or a WordPress.org account. Log in to your WordPress dashboard to install the plugin:

  1. In the left navigation panel, click Plugins and then Add New.
  2. Search for Mode Analytics and the latest version will appear at the top of the list of results.
  3. Click Install Now.
  4. Wait for the installation to finish, then click Activate.
2) Input your Mode credentials into WordPress

In the WordPress dashboard, go to Settings then Mode Analytics. Paste your Mode Access Key and Access Secret into the plugin.

3) Add and configure your report

Click Add Report and fill in the following fields:

  • Max Age: Add an integer input that specifies the maximum age (in seconds) of a report run. If the last run is older than the max age, the report will rerun; if it’s been run more recently, the embed will show that run.
  • Report URL: Copy and paste your Mode report URL.
  • Embed Type: From the drop-down menu, select White-Label Embeds.
  • Short Code Report Name: Select a name to be used to embed this report.
  • Select Buttons (Optional): For White-Label Embeds, you have the option to allow CSV export and report Filters. For Filters to work in WordPress, remember to select Add Filter in your Mode report.
4) Configure parameter(s) (if required):

On a report, click Add Parameters and fill in the following fields:

  • Parameter Slug: This should be consistent with the Parameters used in the report.
  • Data Types: Select the type of data input: text, number, or date.
  • Users Can Edit: This enables report viewers to select Parameters.
  • Default Value: Select which Parameter you would like viewers to see as the default.

WordPress admins can also create user authentication Parameters or tokens for embedded reports that need to be filtered based on a logged-in user attribute.

5) Embed the Report into a WordPress Page
  1. On the left navigation panel, select Pages, and click New Page.
  2. Create a page title.
  3. In the content section, insert the Short Code Report name from your plugin settings: [mode-analytics report_name="Short Code Report Name"]
  4. Under Publish, select Preview Changes. Or, view the page outside of the editor by clicking the Permalink.

When you embed a Mode report in a webpage, the default is to display the most recent run. The embed code looks like this:

<iframe src="https://modeanalytics.com/benn/reports/35c937ba174f/runs/3cc6946d3f43/embed" width="100%" height="300" frameborder="0"></iframe>

With [Mode's WordPress plugin](https://help.modeanalytics.com/articles/embed-reports-in-wordpress/), admins can set up user authentication Parameters or tokens. You can create a custom attribute for each user’s profile that will dynamically replace the token (e.g., `{{account_id}}` in the Parameter default value field) when an embed is rendered. This will ensure that the user is shown the embed with the correct Parameters.

Last updated April 18, 2018