Embed Templates

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

An embed template is a special type of workspace that enables you to embed API logs and charts right into your customer-facing apps with a few clicks. Dynamic fields make embed templates super powerful since they don’t need to be defined until the chart is actually rendered in your UI. This makes it possible to securely sandbox data based on dynamic fields like user id which is not known until a user signs in similar to how you can set merge tags in an email template.

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 Events from the top menu and select the view you want to embed.
  2. Add any filters and other chart settings that you want applied to the final chart.
  3. Click on the orange Embed button at the top right and then select the Create Template.

Create Embed Template

  1. Either which filters that should be dynamic such as a User Id or a Company Id.
  2. Click the Get Embed Code button. This will display the code snippets to add to your application.

Filter Fields

When you create a template, you can add both static and dynamic filters to limit data access. Both static and dynamic fields prevent a viewer of the chart from accessing data outside of your scope.

  • A static filter is defined when you initially create the template. For example, you may want to limit API logs to only show 4xx and 5xx errors in the last 7 days.
  • A dynamic filter is not defined until later when the chart is rendered. For example, you don’t know the user id until a customer signs into your web portal.

Using the embed template

When you click Get Embed Code, a custom snippet will be provided. The 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/em/ws/{WORKSPACE_ID?embed=true#{WORKSPACE_ACCESS_TOKEN}'
}

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/em/ws/{WORKSPACE_ID?embed=true#{WORKSPACE_ACCESS_TOKEN}"
  name="preview-frame"
  frameborder="0"
  noresize="noresize"
>
</iframe>

Previous API versions placed the workspace token within the URL path. For maximum compatibility, we recommend placing the token in the URL hash as shown above.

Template Creation Options

Dynamic Date Range

When you create a template, the request.time is always set as part of the Sandbox for the template. The date range can be basically “static” value like “Last 7 days” or “Last one month”. For most use cases, this is sufficient.

But if you decide to set the request.time to be dynamic, then at the time you generate the workspace URLs, you must provide the the date range from and to values in ISO timestamps as below.

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"
    }
    "from": "2021-07-16T02:52:39Z",
    "to": "2021-07-16T02:52:39Z"
  }
}'

See example implementation here

Expose Header and Body Keys

By default, header and body keys are not accessible in filters for privacy. If you need to provide your customers the ability to filter on these fields, you can allow this. Keep in mind, all customers see the same keys.

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

The below URL parameters can be added to the iFrame link to customize the look to fit your business requirements.

For embedding charts in a customer-facing portal, the defaults are usually sufficient. Ask Moesif support for more info.

<iframe
  id="preview-frame"
  src="https://www.moesif.com/public/{WORKSPACE_ACCESS_TOKEN}/ws/{WORKSPACE_ID}?embed=true&hide_header=true"
  name="preview-frame"
  frameborder="0"
  noresize="noresize"
>
</iframe>
Name Type description
Embed Boolean When set to true, enables embed mode adjusts 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 Boolean. By default, embed mode includes a small header containing filter dropdowns and chart name. If you want to hide all elements besides the chart itself, set this to true. Because the filters are hidden, you’ll need to ensure any filters are added when you initially create the template.
show_metadata boolean 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 boolean By default, embed mode hides the user info. You can override this behavior to show the user info by setting this option to true.
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.
show_companies boolean By default, embed mode hides the user filters. You can override this behavior to show user filters by setting this option to true.
show_user_filters boolean 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 boolean By default, embed mode hides the company filters. You can override this behavior to show company filters by setting this option to true.
primary_color string You can set the primary_color param to a URL encoded hex value that matches your brand colors such as ?primary_color=%2332CD32
The primary color controls the filter buttons, the color of the first metric in the chart, among other elements.
color_array array When your chart plots multiple metrics such as due to a group by, color_array defines the secondary colors for the chart. This is a URL encoded string that contains a comma separated array of color hashes where the first index is the color for first metric in the chart, the second index is the color for the second metric in the chart, etc.
As example, if you want the following color hashes: #ff0000, #00ff00, #0000ff in this order, you should set color_array as ?color_array=%23ff0000%2C%2300ff00%2C%230000ff
chart_font_color string You can set the chart_font_color param to a URL encoded hex value that matches your brand colors such as ?primary_color=%2332CD32. This modifys the colors of the chart axes labels and chart axes ticks.
chart_font_family string Font family for the chart scale lable, and ticks, follows CSS font-family options. If font not available, will render default font family.
chart_axis_font_size boolean Font size in px for both x-axis and y-axiss ticks.
chart_label_font_size boolean Font size in px for both x-axis and y-axis labels.
chart_x_axis_label strinig The text for the title of the x-axis. (i.e. “# of People” or “Response Choices”).
chart_y_axis_label string The text for the title of the y-axis. (i.e. “Percentage” or “Count”).
hide_chart_axis_label boolean if true, hides both x-axis and y-axis labels.
hide_chart_legend boolean if true, hides chart legend.
drawing object If the embedded view is a TimeSeries Chart or Segmentation Chart, you can add an additional line to represent a threshold. See Drawing

Drawing

You can add static markers to your chart such as to represent a plan quota or SLA agreement. This is done via the drawing parameter. An example of how to add a line to a time series showing a threshold is below:

import qs from 'qs';

const queryParams = {
  drawing: {
    value: number, // required
    name: 'name off the label', // required.

    // below are optional:
    type: 'line',
    borderWidth: 5,
    borderColor: 'rgba(255, 51, 181, 0.3)',
    backgroundColor: 'rgba(255, 51, 181, 0.3)',
    pointRadius: 0,
  }
}

// format it into query string
qs.stringify(queryParams, { format: 'index' });

// and append to the embed url.

Updated: