Embed Templates

This guide assumes you are familiar with Dashboards and Workspaces already. If not, please review API Dashboards

Embed templates are a special type of workspace that enables you to create embeddable API logs and charts for customer-facing apps in a few clicks. Unlike public links which enable static embedding, embed templates have dynamic fields which don’t need to be set until the chart is actually rendered similar to merge tags for an email marketing template. This enables real-time sandboxing of data such as setting the user id dynamically when a customer logs into your web app.

Embedded API Logs

Both public links and embed templates can be embedded and styled via iFrame. Both support the same styling parameters such as primary color, etc, but their use case and integration method are quite different. Being static, public links can be embedded in pretty much any HTML page with just a single code snippet. While this makes public links super easy to embed in your website, their sandboxing is limited as the filters need to be known ahead of time.

When the metric is consistent, then a static embed via public link is sufficient. However, what about cases where the filter values are not even known until later. For example, if you want to embed a chart or API log stream in your customer facing dashboard, you don’t know the user id until after the customer signs in. For these you can leverage embed templates with dynamic fields that can be programmatically populated when you render the chart. The integration is slightly more complex than static embed since it requires adding a backend endpoint that can securely generate these links in a trusted environment for your frontend.

  Public Link Embed Template
Type Static Embed Dynamic Embed
Shareable link Yes No
Integration complexity Frontend snippet only Frontend snippet + backend code
Sandboxing Static/Predefined Dynamic/Performed during rendering
Use case Embed static/predefined charts for internal dashboards Securely embed charts with dynamic/unknown filter criteria such as for customer-facing apps

Creating an embed template

A working React app using Moesif embed template is available here.

To embed a chart or API log:

  1. Go to the view you’re interested in such as Event Stream or Time Series.
  2. Add any filters or other chart settings that you want applied to the final template.
  3. Click on the Share button at top right and then select the Embed Template tab.

Create Embed Template

  1. Specify which fields will securely sandbox the data which is usually the user id or company id.
  2. Click the Get Embed Code which will provide you with the snippets to embed and style your chart.

Using the embed template

When you create the template, code snippets will be displayed so you can embed it. The same steps are also outlined below for reference.

Step 1. Add endpoint that generates workspace URLs

In your backend, create a new endpoint that programmatically generates new workspace URLs using your dynamic values. In this example, user_id is a dynamic field that needs to be populated with the correct value.

curl -X POST -H 'Authorization: Bearer YOUR_MANAGEMENT_API_KEY' -H 'Content-Type: application/json' -i 'https://api.moesif.com/v1/portal/~/workspaces/{WORKSPACE_ID}/access_token
  -d '{
  "template": {
    "values": {
      "user_id": "1234"
    }
  }
}'

Moesif will return a workspaces URL and workspace access token that is scoped to the values you specified. In this case, the API data will be scoped to only user id 1234, and no one else.

{
  access_token: '{WORKSPACE_ACCESS_TOKEN}',
  url: 'https://www.moesif.com/public/{WORKSPACE_ACCESS_TOKEN}/ws/{WORKSPACE_ID}?embed=true
}

Step 2. Display the chart

Display the chart using the URL generated in step 1. Because the workspace access token and URL are limited in scope, they are safe to be seen by the authenticated user.

<iframe
  id="preview-frame"
  src="https://www.moesif.com/public/{WORKSPACE_ACCESS_TOKEN}/ws/{WORKSPACE_ID}?embed=true"
  name="preview-frame"
  frameborder="0"
  noresize="noresize">
</iframe>

Workspace Token Options

expiration

Setting this value enables you to control the expiration of the Workspace token. You can set this to the maximum time before you expire user session expires like “kicked out due to inactivity.”

Display Options

There are URL parameters you can add to the final iFrame page to customize the look. Moesif provides a variety of options to show or hide info to fit your requirements. For example if you have a use case where your customers wants metrics on their end-users, you can set show_users and show_user_filters to true while leaving show_companies and show_company_filters set to false.

If you are embedding the chart in a customer-facing dashboard, the defaults are usually sufficient where show_metadata, show_users, show_companies, show_user_filters, and show_company_filters are all set to false as it wouldn’t make sense to surface customer info.

embed

Boolean. When set to true, enables embed mode which hides navigation, user and company info, event metadata, and adjusts chart layout to be embed friendly. This should always be set to true when embedding a chart in an iFrame except for rare cases.

hide_header

Boolean. By default, embed mode includes a small header with filters and chart name. If you want to remove all elements besides the chart itself, set this to true. Because the filters are hidden, you’ll need to add any necessary filters when you initially create the template.

show_metadata

By default, embed mode hides the event metadata. You can override this behavior to show event metadata by setting this option to true.

show_users

By default, embed mode hides the user info. You can override this behavior to show the user info by setting this option to true. If you

show_companies

By default, embed mode hides the company info. You can override this behavior to show the company info by setting this option to true.

show_user_filters

By default, embed mode hides the user filters. You can override this behavior to show user filters by setting this option to true.

show_company_filters

Embed mode will hide company filters, but you can override this behavior to show user filters by setting this option to true.

primary_color

You can set the primary_color to a URL encoded hex value that matches your brand colors such as ?primary_color=%2332CD32 This will change the filter button, the first chart color, among other elements. If your chart has multiple datasets, the secondary elements cannot be changed at this time.

Updated: