Embed API - Embed Options

👤 This documentation is intended for Site Administrators. For users looking for a non-programatic solution to sharing dashboards externally, refer to the documentation on Shared Dashboards and Scheduled Email Reports.

Note: Whitelabeled Embeds are an add-on feature. Site administrators can contact their Account Manager for additional information. 

<div><UL>
<LI><a href="#JSONOptions">JSON Options</a></LI>
<UL>
<LI><a href="#Dashboard">Dashboard</a></LI>
<LI><a href="#Chart">Chart</a></LI>
<LI><a href="#EmbedVersion">Embed Version</a></LI>
<LI><a href="#DaterangeFilter">Daterange Filter</a></LI>
<LI><a href="#AggregationFilter">Aggregation Filter</a></LI>
<LI><a href="#CustomFilters">Custom Filters</a></LI>
<LI><a href="#UnusedFilters">Unused Filters</a></LI>
<LI><a href="#VisibleFilters">Visible Filters</a></LI>
<LI><a href="#ChartBorders">Chart Borders</a></LI>
<LI><a href="#DataLatency">Data Latency</a></LI>
<LI><a href="#ExpirationDate">Expiration Date</a></LI>
<LI><a href="#Puttingialltogether">Putting it all Together</a></LI>
</UL>
<LI><a href="#CurlCommands">Curl Commands</a></LI>
<UL>
<LI><a href="#Create">Create</a></LI>
<LI><a href="#List">List</a></LI>
<LI><a href="#Delete">Delete</a></LI>
</UL>
<LI><a href="#PostMessages">Post Messages</a></LI>
<UL>
<LI><a href="#FilterChange">Embedded Filter Change</a></LI>
<LI><a href="#EmbedSize">Embed Size</a></LI>
<LI><a href="#Drilldown">Embedded Drilldown</a></LI>
<LI><a href="#RefreshTrigger">Embed Refresh Trigger</a></LI>
</UL>
<LI><a href="#LookingforMore">Looking for More?</a></LI>
</UL></div>

<HR>

<a name="JSONOptions"></a>

JSON Options

A summary of the Embed API request can be found on the documentation here. The below options review additional parameters that can be defined in the encoded data JSON blob.

<a name="Dashboard"></a>

Dashboard

The dashboard number can be found in the dashboard's URL. i.e. if the URL looks like

https://app.periscopedata.com/app/example-site/10/example-dashboard-name

then the dashboard number is 10, and the JSON blob will say

"dashboard": 10,

<a name="Chart"></a>

Chart

To embed a single chart, the user will include the chart parameter after the dashboard parameter.

The chart number can be found by clicking the hamburger menu of the chart and clicking "Share Link". If the URL from that link looks like

https://app.periscopedata.com/app/example-site/10/example-dashboard-name/example-chart-name?widget=1234

The chart number is the widget ID. In this example it is 1234 so the JSON blob will say

"dashboard": 10,
"chart":1234,

<a href="#top">Back to top</a>

<a name="EmbedVersion"></a>

Embed Version

The default embed version is "true." In case the extra padding from the embed should be removed, use embed version "v2":

"embed": "v2"

Note: To remove the "Powered by Periscope Data" footer from embedded dashboards, site administrators must contact their Customer Success Manager for additional information.

<a name="DaterangeFilter"></a>

Daterange Filter

When using the pre-built daterange filter options or selecting a number of days before the current date, include it using:

"daterange": {"days": 7}

When using a custom range, the user must specify the start and end dates:

"daterange": {"start": "2015-01-01", "end": "2015-01-01"}

If the daterange parameter is not included, the dashboard will default to including all dates.

<a href="#top">Back to top</a>

<a name="AggregationFilter"></a>

Aggregation Filter

To include the dashboard aggregation in the JSON blob, add the following on its own line in the blob:

"aggregation": "daily"

If the aggregation parameter is not included, the dashboard will default to using "daily" as the aggregation period.

<a name="CustomFilters"></a>

Custom Filters

If the user wants to pass custom filters to the embed, include them like so:

"filters": [{"name": "Filter1", "value": "value1"}, {"name": "Filter2", "value": "1234"}]

If there are multiple filter values to be included for the same filter, there are the options to either include it twice or pass an array:

"filters": [{"name": "Filter1", "value": "1234"}, {"name": "Filter1", "value": "5678"}]
"filters": [{"name": "Filter1", "value": ["1234", "5678"]}]

To embed child filters, an additional parameter that specifies the group (parent value) must be included. This will always be equivalent to the value of the parent filter being embedded:

"filters": [{"name": "ParentFilter", "value": 1234}, {"name": "ChildFilter", "value": "5678", "group": "1234"}]

When using filters in the chart titles, the display value, which is populated into the chart title, must be included. The JSON blob cannot be used with the array syntax to ensure proper parsing:

"filters": [{"name": "Filter1", "value": "1234", "display": "Display1"}]

<a href="#top">Back to top</a>

<a name="UnusedFilters"></a>

Unused Filters

If the user is not using a filter, simply omit it from the blob and no value will be passed for it.

<a name="VisibleFilters"></a>

Visible Filters

If the filters should be accessible to the end user of the embed, include the filter names in the JSON blob as visible filters. The selected filters must be visible on the underlying dashboard in Periscope as well.

"visible": ["Filter2", "Filter3", "aggregation", "daterange"]

<a name="ChartBorders"></a>

Chart Borders

Turn chart borders off by setting them to off:

"border": "off"

<a href="#top">Back to top</a>

<a name="DataLatency"></a>

Data Latency

By default embedded dashboards will reflect the current state of the in-app dashboard. If there are special requirements around the freshness of the data or if the embedded dashboard references different filter combinations than are used in the in-app dashboard, add a time threshold to the request:

"data_ts": 1446069112

The data_ts value is integer seconds since the epoch (Note: millisecond precision is not supported). Charts with data older than this timestamp will show loading and get scheduled to refresh when page loads. Typically, the data_ts parameter should be a dynamic value if the embedded dashboard is meant to continuously refresh. These data_ts parameters pull the current epoch time (in seconds) and subtract the desired refresh interval (in seconds). For best results, Periscope recommends a refresh interval no more frequent than every 10 minutes (600 seconds).

Below are a few examples of dynamic data_ts parameters:

Salesforce

data_ts: Math.trunc(new Date()).getTime() / 1000) - 600

Ruby on Rails

data_ts: Time.now.getlocal('-07:00').to_i - (10 * 60)

Python 2

import time;
data_ts: time.time()-600

Python 3

import datetime;
data_ts: datetime.datetime.now().timestamp() - 600

<a href="#top">Back to top</a>

<a name="ExpirationDate"></a>

Expiration Date

Limit how long the embedded dashboard link is valid with

"expires_at": 1456069112

The expires_at value is integer seconds since the epoch. Accessing the embedded dashboard after this time will show a message explaining the dashboard has expired.

Add the following parameter to allow viewers of the shared dashboard to continue viewing it past the expiration time. After the expiration time, viewers will not be ejected from viewing the dashboard until they refresh the page or close their browser.

 "maintain_sessions_after_expiration": true 

<a href="#top">Back to top</a>

<a name="Puttingialltogether"></a>

Putting It All Together

After each piece is assembled, the final product will look something like this:

{
       "dashboard": 7863,
       "chart":1234,
       "embed": "v2",
       "aggregation": "daily",
       "daterange": {"start": "2015-01-01", "end": "2015-01-01"},
       "filters": [{"name": "Filter1", "value": "value1"}, {"name": "Filter2", "value": "1234"}],
       "visible": ["Filter2", "Filter3", "aggregation", "daterange"],
       "border": "off",
       "data_ts": 1446069112,
       "expires_at": 1456069112
   }

<a href="#top">Back to top</a>

<a name="CurlCommands"></a>

Curl Commands

There are three API endpoints for creating, listing, and deleting embedded dashboard and chart links. For each, the site_name can be found in the dashboard's URL. i.e. if the URL looks like

https://app.periscopedata.com/app/example-site/10/example-dashboard-name

then the site_name is example-site. The API_KEY can be found in the "Billing and Authentication" section of the gear menu in the bottom left corner. 

<a name="Create"></a>

Create

The create command allows creation of a shared dashboard link via API. The JSON format for filters in the create API is the same as the API for embedded dashboards laid out above.

curl https://app.periscopedata.com/api/v1/shared_dashboard/create --data-binary '{"dashboard":1000,"filters":[{"name":"Site","value":41,"display":"US"}]}' -H "HTTP-X-PARTNER-AUTH: site_name:API_KEY"

Once the shared dashboard link has been created, additional embed options, such as the data_ts and expires_at parameters, must then be appended to the end of the generated url following a '?'. For example:

https://app.periscopedata.com/shared/abcdefgh123456?embed=v2&border=off&data_ts=1521674700

<a name="List"></a>

List

The list command will return a list of open shared dashboard links for the specified dashboard ID.

curl https://app.periscopedata.com/api/v1/shared_dashboard/list --data-binary '{"dashboard":1000}' -H "HTTP-X-PARTNER-AUTH: site_name:API_KEY"

<a name="Delete"></a>

Delete

The Delete command will delete the referenced shared dashboard. The token to be used is the last part of a shared dashboard URL. i.e. if the shared URL looks like

https://app.periscopedata.com/shared/9dda9dda-9dda-9dda-9dda-9dda9dda9dda

then the token is 9dda9dda-9dda-9dda-9dda-9dda9dda9dda.

curl https://app.periscopedata.com/api/v1/shared_dashboard/delete --data-binary '{"token":"9dda9dda-9dda-9dda-9dda-9dda9dda9dda"}' -H "HTTP-X-PARTNER-AUTH: site_name:API_KEY"

<a href="#top">Back to top</a>

<a name="PostMessages"></a>

PostMessages

Embedded dashboard and charts release three different PostMessages to communicate with the outer webpage and allows one PostMessage to communicate with the embed.

<a name="FilterChange"></a>

Embedded Filter Change

When a user changes a filter set on an embedded chart or dashboard, Periscope will send a PostMessage in the following format. The PostMessage contains the complete list of filters applied to the embed. The format of the parameters will follow the same convention as the Embed API. The webpage code can use this information to send filter combinations to the Render API add-on or to send information on filter usage within embeds.

{    
     event_type: "viewport_changed",     
     aggregation: "weekly",    
     daterange: {"start": "2015-01-01", "end": "2015-01-01"},    
     filters: [{"name": "Filter1", "value": "1234"}...]
}

Note: Please click here for more information on the Render API add-on.

<a name="EmbedSize"></a>

Embed Size

Upon page load, Periscope will send a PostMessage with the size of the dashboard or chart. The message will be in the following format, with the height and width of the dashboard/chart, which can then be used to properly size the iFrame for the embed.

{
     event_type: "dashboard_resize",
     dashboard_height: 100,
     dashboard_width: 200
}

<a name="Drilldown"></a>

Embedded Drilldown

When a user clicks on an embedded chart with drilldowns enabled, Periscope will send a PostMessage in the following format. The PostMessage contains the new dashboard ID and the new/updated filters and values. The webpage code can use this information to update the JSON used to create the embedded URL.

{
    event_type: "drilldown",
    destination_dashboard_id: 1234,
    filter_values: [ { filter_name: "foo", column_value: "bar" }, ... ]
}

With the information from the PostMessage, the website code can be written to create a new JSON to create a new URL for the target dashboard. This new JSON blob has the same available parameters from above, and is entirely controlled by the user.

<a name="RefreshTrigger"></a>

Embed Refresh Trigger

While the data_ts parameter checks data freshness and triggers query refreshes on an embed page load, this PostMessage allows the outer webpage to trigger query refreshes while the page is open, without the need to refresh the browser page. If the iframe code is: 

<html><body><iframe src="https://app.periscopedata.com/shared/...." height=800 width=1000></iframe></body></html>

Then the Javascript API to call would be:

$('iframe').contentWindow.postMessage({event_type: "refresh_charts"}, "*")

This PostMessage can be triggered using a setInterval() method or attached to a button to trigger the charts to refresh either manually or on a schedule. The max refresh rate using this trigger is once a minute, though once every ten minutes is recommended.

Note: Enabling this API on embeds is NOT recommended for sites that already experience heavy query load or query queues on their site. Public embeds can increase the number of queries run against a connection and increasing the number of refreshes requested may cause further delay and queuing. Embeds that use this API should be restricted to dashboards with few charts and low runtimes.

<a name="LookingforMore"></a>

Looking for More?

Try our community page for guidance on topics like: 

<a href="#top">Back to top</a>

Our support team is ready to help