Skip to content
Skip to main contentWhere does your team stand on AI adoption?
CONTACT SALESSTART BUILDING

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

// Or, track an event within your project's code 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');

In addition to tracking custom events, you can also pass data about user interactions with Builder content to an analytics provider for further analysis and personalization. To learn more, visit Passing Data to an Analytics Provider.

Importing the SDK

To import the latest SDK, specify the framework as follows:

import { track } from '@builder.io/sdk-...' // Next.js, App Router import { BuilderContent } from "@builder.io/sdk"; // Qwik import { getContent } from "@builder.io/sdk-qwik"; import { getContent, RenderContent, getBuilderSearchParams, type RegisteredComponent, } from "@builder.io/sdk-qwik"; // React, Remix, Hydrogen, Gatsby import { BuilderComponent, builder, useIsPreviewing } from "@builder.io/react"; import { BuilderComponent, builder } from "@builder.io/react"; import { BuilderComponent } from '@builder.io/react'; // Vue import { getContent, RenderContent, isPreviewing } from '@builder.io/sdk-vue/vue2'; import { getContent, RenderContent, isPreviewing } from '@builder.io/sdk-vue/vue3'; // Nuxt import { RenderContent, getContent, isPreviewing } from '@builder.io/sdk-vue' // Svelte import { RenderContent } from '@builder.io/sdk-svelte'; // Angular import { BuilderModule } from '@builder.io/angular';

Accessing custom events in the overview dashboard

To display metrics for your custom events on the overview dashboard, take the following steps from the content entry where you use your custom event:

  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.

For more information, refer to Viewing Metrics with Insights.

Using event tracking with Gen 2 SDKs

With the Builder Gen 2 SDKs, you can use Builder's event tracking module 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:

// Make sure you're using a Gen 2 SDK import { track } from '@builder.io/sdk-vue' track({ type: 'impression' | 'conversion' | 'click' | 'some-custom-event', apiKey: YOUR_API_KEY });
Was this article helpful?