Embed Templates

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

An embedded template is a special type of workspace that enables you to embed API logs and charts directly into your customer-facing apps with a few clicks.

Dynamic fields make embedded 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. When a user logs in, their user ID is then used to fetch the relevant data for display.

Embedded API Logs

Both public links and embedded templates allows users to embed and style a chart generated in Moesif via an iFrame element in their UI. Both support the same styling parameters such as primary color, etc, but their use case and integration method are quite different.

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. The charts displayed are not able to support dynamic filtering. When the metric/filter is consistent, then a static embedded chart via a public link is sufficient.

Embedded templates contain dynamic fields that can be programmatically populated when you render the chart. This offers a more customized approach to rendering logs and charts. The integration is slightly more complex than statically embedding a chart, like with a public link, 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 screen.
  2. from the Chart Type Selector, choose the chart type you’d like to embed.Generating an embedded template
  3. Add any filters and other chart settings that you want applied to the final chart.
  4. Click on the orange Embed button in the top right and then select the Create Template.Generating an embedded template
  5. A modal will then appear. Fill in the field for Workspace Name, choose Share Type as Embed Template, and select which filters should be dynamic such as User Id or Company Id.Generating an embedded template
  6. Click the Get Embed Code button. Generating an embedded template
  7. Moesif will then display code snippet examples with your chart details to add to your application.

Generating an embedded template

If you don’t require any dynamic filters, use a Public Share for the chart instead.

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 chart on the Events screen. When you create the template, this filter is also applied to it. 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. This is the defining difference between an embedded template and a public link since the latter does not have dynamic capabilities. For example, you don’t know the user id until a customer signs into your web portal.

Using the embed template

To see a step-by-step guide on how to do this, check out our guide on embedded templates.

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 a users session. When the session is expired, the template will show the users that they have been “kicked out due to inactivity”.

Display Options

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

The below URL parameters can be added to the iFrame link to customize the look to fit your business requirements. An example is also provided below which shows the embed and hide_header display options added to the URL in the iFrame’s src field.

<iframe
  id="preview-frame"
  src="https://www.moesif.com/public/em/ws/{WORKSPACE_ID}?embed=true&hide_header=true#{WORKSPACE_ACCESS_TOKEN}"
  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 modifies the colors of the chart axes labels and chart axes ticks.
chart_font_family string Font family for the chart scale label, 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-axis ticks.
chart_label_font_size boolean Font size in px for both x-axis and y-axis labels.
chart_x_axis_label string 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. An example may be a line across the chart at a specific threshold so that users can trace their usage against their quota.

Drawing a static marker is done via the drawing parameter. The options specified for the drawing must be defined and formatted as a query parameter. It must be attached to the embed URL in the same way that the display options are attached in the section above.

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 of 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: