Custom Analytics Dashboards

💡 This features is available for Enterprise plans only

Builder allows you to track custom metrics to associate with how your content performs.

This can be great for use cases like

Measuring A/B test performance by custom events, such as add to cart rates or average order value
Breaking down impressions and conversions by which product was viewed or ordered
Completely custom insights and dashboards associated with Builder content and sessions

Tracking custom events

import { builder } from '@builder.io/sdk';

// Track an event
builder.track('yourEventName')

// Add custom properties
// You can add any key:value pairs you need in the `meta` object
// Values can be any valid JSON type - string, number, boolean, null, object, array
builder.track('addToCart', { meta: { productId: 'abc123', somethingElse:  true } })

Creating custom dashboards

You can create both global custom dashboards (to look at performance of content across entries) as well as per-entry custom dashboards (look at custom metrics on a per-content entry basis, such as custom views on a/b test winner).

Try create a global custom dashboard, go to builder.io/insights and choose + new dashboard.

To create a per-entry dashboard open up a piece of content in Builder, go to the insights tab and choose + new dashboard.

When you click to create a new dashboard you will be taken to a new content entry where you can build and customize your dashboard. Customization happens within the Builder editor, and we provide a few example SQL tables to get you started. You can drag them onto the page and start editing the SQL within them via the edit button, then click publish to make the dashboard within the insights tab.

Using context and inputs

When you drag one of the example SQL tables onto the page when creating or editing a dashboard, you will see a few special things going on in the SQL code. For example it might look like this:

SELECT *
FROM @events 
WHERE 
  -- show results for the last week in milliseconds.
  -- 8.64e+7 = 1 day in ms
  _PARTITIONTIME >= "${sqlDate(Date.now() - Number(inputs.sinceDaysAgo || 7) * 8.64e+7)}"
  ${context.content ? `AND CONTENT_ID = "${context.content.id}"` : ''}
LIMIT 10

If you are used to regular SQL this might look a bit strange to you, because of the presence of inputs, context, plus the ${}stuff going on. The reason for this is that the SQL you put into the the table is essentially a string, and when you use ${}you are using javascript string interpolation. This allows us to provide useful and dynamic information within the SQL query, such as the id of the content or user input from whoever is interacting with the chart.

You can use context to get additional information, such as the id of the current content, allowing you to make queries that target only that content. The inputs variable is populated with the names and values of the inputs you add to the SQL chart. To add additional inputs, click on "show advanced" in the edit menu for the SQL table or chart you are working on and add any additional fields you would like the people using your custom chart to be able to control.

Querying custom properties and events

Let's say you are tracking a custom event called addToCart in your code. Those events can be queried within the custom dashboard by editing a SQL query to have the type set to whatever your event is called.

Custom properties can be specified on those track calls, and then can be queried as well. Custom properties are stored as JSON in the metadata field. You can use JSON_EXTRACT_SCALARto specify and query for events that contain certain metadata.

For example, if we are making the following track call in our code:

builder.track('addToCart', { meta: { productId: 'abc123' } })

We can use the following SQL to get every addToCart event with the productId 'abc123' associated with it.

SELECT CONTENT_ID, COUNT(*) as count FROM @events 
WHERE
  type = "addToCart"
  AND JSON_EXTRACT_SCALAR(metadata, "$.productId") = "abc123"
GROUP BY CONTENT_ID
ORDER BY count DESC
LIMIT 10

Was this article helpful?