Creating and Using Templates

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

Creating an Embedded 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.
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.
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.
6. Click the Get Embed Code button.
7. Moesif will then display code snippet examples with your chart details to add to your application.

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 an Embedded 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 'https://api.moesif.com/v1/portal/~/workspaces/{WORKSPACE_ID}/access_token' -H 'Authorization: Bearer YOUR_MANAGEMENT_API_KEY' -H 'Content-Type: application/json'
  -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": "2023-07-16T02:52:39Z",
    "to": "2023-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_daterange	boolean	Boolean. If you set hide_header to true, but you still wish to show the date range select that was part of the header, you can set this to true.
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 any brand colored buttons, links, 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. This will also control the color of status codes in the even log. 1xx is 1st element, 2xx is second element and so on.
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.
hide_event_selection	boolean	For Event log view only; if true, the checkboxes for selecting event and any buttons that are acting upon selected events will be hidden.
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.

Sharing a Static Embed with a Passcode

When sharing a chart, you can also protect it using a passcode. To share a link that is protected by passcode, in the Embed / API Access modal that appears when creating or updating an embedded template, select the Passcode option in the iFrame section of the screen.

Once selected, you’ll see the passcode protected URL as well as the generated passcode to share with authorized users.