Tracking and Dashboards

Builder.io provides Insights tab for viewing the metrics such as engagement and conversion for Pages & Sections.

Insight Dashboard

• Select the Insights tab from the top of the Visual Editor.
• You'll get the Insights Dashboard on the Screen, Similar to the image below.

Custom Dashboard

To get customized matrix for your page you can create a custom dashboard. It allows to create an SQL table & visual chart representation with custom SQL query.

to start,

• Click the New dashboard option from the insights section.
• Select the Simple SQL Table or SQL histogram option from the toolbar in left side of the page.

  SQL Table	Chart

• Drag & drop any of them into the visual editor, and you can customize the data using the SQL editor in the Options tab on the right. It also supports the JS interpolation with the ${} syntax to inject dynamic values into your query, for example:

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

Interpolated JS statements have access to the browser's JS API as well as the context and inputs objects.

context comes with the details of the current content.

inputs is populated with the names and values of the inputs that you add to your SQL table or chart. It can be added from the Advance Options on the right. In the above query we have accessed the value of inputs.sinceDaysAgo which is coming from the custom input element.

In the following image, the inputs are sinceDaysAge event & userType. Notice that the naming convention for the inputs are in pascal case.

Querying custom properties and events

You can scope your SQL queries to custom events using the type column. You can further refine those queries based on metadata associated with your custom events using the JSON_EXTRACT_SCALAR SQL function.

For example, the following JS code tracks adding an item to a shopping cart with a productId of abc123 and the property somethingElse set to true:

// 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 } })

You can use the following SQL to get every addToCart event that has a productId of abc123, including the one tracked above:

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

• type = "addToCart" scopes the query to only return addToCart events.
• JSON_EXTRACT_SCALAR(metadata, "$.productId") = "abc123" first expands the event's value on the metadata column, which contains all properties tracked using the meta property on the client side as a JSON object. Then it extracts the productId property from that object and compares it to abc123. If the event's productId matches abc123, then it's included in the returned record set.

Running ad hoc SQL queries on custom dashboards

Instead of permanently modifying a dashboard's SQL queries each time to see the different result, you can run ad hoc queries on any dashboard on the Insights tab.

• Open the dashboard from the Insight tab and select the Toggle SQL from the top right corner of any table or chart.
• You can use SQL editor to write your own ad hoc query & after that select the Run at the bottom to execute the query.

Your ad hoc query is added into your browser's current URL as a query parameter, which allows you to share your modified table or chart as a link.

However, it won't change the permanent SQL query that retrieves data for your table or chart.

Limitations

The maximum bytes that can be queried in one call is 350GB.

Tracking Custom Events

You can track custom events to evaluate your content's performance. For example, you can:

• measure A/B test performance by custom events, such as add-to-cart rates or average order value
• break down impressions and conversions by product views or orders
• build completely custom dashboards associated with Builder content and sessions

Tracking custom events in JavaScript

You can track a custom event using JavaScript or with the Visual Editor's JS editor or within your own codebase. Custom events can have any name.

In Builder content or from the custom JavaScript panel, track an event within an action binding:

builder.track('yourEventName');

Alternatively, you can track a custom event using JavaScript within your own codebase:

import { builder } from '@builder.io/sdk';
builder.track('yourEventName');

If you're using web components, such as Shopify hosted, you can access the global Builder instance from any script tag or function. Note that in this case, you might need to wrap the call in a setTimeout() to ensure BuilderWC is loaded:

BuilderWC.builder.track('yourEventName');

Accessing custom events in the overview dashboard

To display metrics for your custom events on the overview dashboard, follow these steps:

1. Navigate to the Insights tab.
2. Click on the three dots in the top right corner and choose Customize Metrics.
3. Select Manage Custom Events.
4. Add a new event to start tracking your custom event on the dashboard.
5. Enter the Event Name, matching the string supplied to builder.track().
6. Add a Display Name to label your custom metric on the dashboard.
7. Optionally add a Description for the event.
8. Click Submit and make sure the new event is checked to start tracking.

that new event will be starting to visible on insights section along with the other tiles.

Using event tracking with Gen 2 SDKs

You can use it to,

• track events
• track data retrieval
• handle API requests

You can create event objects, check if tracking is enabled, and send the event data to a tracking API.

To track and send the event data to the tracking API, use the track() function with an object containing the type property.

The type property specifies the type of event you want to track. It can be one of the predefined values:

• impression
• conversion
• click
• some-custom-event

You can choose the appropriate type based on the event you want to track. For example:

import { track } from '@builder.io/sdk-vue'

track({
  type: 'impression' | 'conversion' | 'click' | 'some-custom-event',
  apiKey: YOUR_API_KEY
});