Sending Custom Events

Custom events let you track actions that happen around your video, such as an Add-to-Cart click, a checkout start, or a form submission. Vidalytics associates each event with the related video so you can use its event count in Vid Stats.

How Custom Events Work

Your page decides when an action has happened and pushes its name to the Vidalytics queue. Each push records one occurrence for the selected video. Add the push call to your code or tag manager at the point you want to measure.

Important

A Vidalytics player must be present on the same page where you push a custom event. The player does not need to have finished loading when the event occurs.

Set Up the Queue

Initialize window.vidalyticsEvents once, as early as possible in the page's <head>. It should appear before the Vidalytics embed and before any site or tag manager script that may push an event. This ensures the queue is available even when an action happens before the player finishes loading.

index.html

<head>
  <script>
    window.vidalyticsEvents = window.vidalyticsEvents || [];
  </script>

  <!-- Load tag manager or other site scripts after the queue. -->
</head>

<body>
  <!-- Your Vidalytics embed code usually lives in the page body. -->
</body>

If your website builder does not allow scripts in <head>, place the initializer at the earliest available position in the page, before the embed code and before the first call to window.vidalyticsEvents.push().

Important

Use a single window.vidalyticsEvents queue per page. The name is case-sensitive, so always use the exact capitalization shown here. After initialization, add items with .push() and do not replace the queue with a new array. The queue does not carry over when the visitor navigates to another page.

Send an Event

Push a string when the action happens. The initialization line is only needed if you did not already initialize the queue in <head>:

window.vidalyticsEvents = window.vidalyticsEvents || [];
// ^ Only needed if the queue was not initialized before
window.vidalyticsEvents.push('Checkout Start');

For example, send an event when a custom buy button is clicked:

const buyButton = document.querySelector('#buy-button');

buyButton?.addEventListener('click', () => {
  window.vidalyticsEvents.push('Add To Cart');
});

You can also use the object format. Without an embedId, this behaves the same as pushing a string:

window.vidalyticsEvents.push({ event: 'Checkout Start' });

Choose Event Names

Event names can contain spaces and preserve their capitalization. Use short, consistent labels that will be easy to recognize in Vid Stats, for example:

Custom CTA Click
Add To Cart
Checkout Start
Order Form Submitted

Leading and trailing whitespace is removed, but capitalization and spacing inside the name are preserved. For consistent reporting, use the same spelling every time. For example, do not alternate between Checkout Start and checkout start.

At this time, the API records the event name only. Do not place changing values such as order IDs, email addresses, or prices in the name. Each different name can become a separate metric, and event names are not intended for personal or sensitive data.

Vid Stats currently lists up to 100 unique custom event names for each video. Use a stable set of names instead of generating a new name for each order, viewer, or session.

Supported Formats

Use a string for the first available player, or an object when you need to specify the target:

// First available player
window.vidalyticsEvents.push('Checkout Start');

// First available player, using the object format
window.vidalyticsEvents.push({ event: 'Checkout Start' });

// One specific player
window.vidalyticsEvents.push({
  event: 'Checkout Start',
  embedId: 'vidalytics_embed_XXXXXXXXXXXXXXXX',
});

// First active player from an ordered list of variants
window.vidalyticsEvents.push({
  event: 'Checkout Start',
  embedId: [
    'vidalytics_embed_XXXXXXXXXXXXXXXA',
    'vidalytics_embed_XXXXXXXXXXXXXXXB',
  ],
});

At this time, an event object supports event and the optional embedId. Additional custom properties are not supported yet.

Target a Player

If your page contains more than one Vidalytics player, include an embedId to associate the event with the correct video:

window.vidalyticsEvents.push({
  event: 'Add To Cart',
  embedId: 'vidalytics_embed_XXXXXXXXXXXXXXXX',
});

Tip

Not sure which ID to use? See What is my Embed ID? for help finding it in your embed code.

We recommend using the full embed ID from your video's embed code. The following formats are also accepted and all refer to the same player:

XXXXXXXXXXXXXXXX
vidalytics_embed_XXXXXXXXXXXXXXXX
#vidalytics_embed_XXXXXXXXXXXXXXXX

If the page can load one of several video variants, pass an array of embed IDs. The event is sent to the first matching player that is active on the page.

Warning

An array is a fallback list. It sends the event to one matching player, not to every player in the array.

Vid Conditions example

When Vid Conditions can show one of several videos on the page, include every possible embed ID in the array:

window.vidalyticsEvents.push({
  event: 'Checkout Start',
  embedId: [
    'vidalytics_embed_XXXXXXXXXXXXXXXA',
    'vidalytics_embed_XXXXXXXXXXXXXXXB',
  ],
});

When embedId is omitted, the event goes to the first available Vidalytics player on the page. This is convenient for single-video pages, but explicit targeting is safer when a page has multiple players.

Queue and Delivery Behavior

You do not need to wait for the Player API to become ready. Events pushed before the player initializes remain pending and are sent when tracking for the matching player is ready. If you target an embed that has not loaded yet, the event waits for that embed.

Processed items remain in window.vidalyticsEvents, similar to a tag manager data layer. The array therefore acts as a history of pushes. Its length does not show how many events are still waiting to be sent.

Events may take some time to appear in Vid Stats. Delivery confirmations are not currently available when adding an item with .push().

Empty or whitespace-only names, malformed items, and invalid embedId values are ignored. An event targeted to a valid embed ID that has not registered yet remains pending and is not reassigned to another player.

Custom Events in Vid Stats

After the data is processed, custom event names appear automatically in Vid Stats. You do not need to create or configure them in the dashboard first.

Vid Stats area	What you can do
Summary and tables	View event totals. Use Custom page events in the column picker to show or hide individual events.
Engagement and Trends	Select the custom events you want to include from the metrics menu.
Funnel	Add a custom event as a funnel step.
Exports	Include selected custom event metrics in the exported file.

Counts follow the selected date range and segment. Custom page events are shown separately from Vidalytics player CTA metrics.

Verify Your Setup

During implementation, use this checklist:

Add a console.log() beside your .push() call to confirm that the page handler or tag manager trigger runs.
Inspect window.vidalyticsEvents in the browser console and confirm that the expected item is present.
On a multi-player page, compare embedId with the ID in the matching embed code.
Check the browser console for an error beginning with [Vidalytics Events].
Allow for analytics processing before checking the event count in Vid Stats.

Remember that an item remaining in window.vidalyticsEvents is normal. The public queue keeps its history after events are processed.

TypeScript

You can add the following declarations to a .d.ts file in your project.

vidalytics.d.ts

export type VidalyticsEventsItem =
  | string
  | { event: string; embedId?: string | string[] };

declare global {
  interface Window {
    vidalyticsEvents?: VidalyticsEventsItem[];
  }
}

Troubleshooting

The Event Does Not Appear in the Queue

Confirm that the queue is initialized before your code calls .push().
Add a console.log() inside the event handler to confirm that the page action triggers it.
Check that you use the exact case-sensitive name window.vidalyticsEvents.
Make sure another script does not replace the queue after it is initialized.

The Event Is in the Queue but Not in Vid Stats

Confirm that a Vidalytics player is present on the same page.
If you provided an embedId, confirm that the matching player actually loads.
Check that the event name is a non-empty string.
Allow the analytics data to finish processing before checking Vid Stats again.

The Event Is Associated with the Wrong Video

This can happen when embedId is omitted on a page with multiple players. Pass the full ID from the intended video's embed code instead of relying on the first available player.

An Array Sends Only One Event

This is expected. An embedId array is an ordered fallback list for pages that load one of several video variants. It does not broadcast the event to every ID.

#Sending Custom Events

#How Custom Events Work

#Set Up the Queue

#Send an Event

#Choose Event Names

#Supported Formats

#Target a Player

#Queue and Delivery Behavior

#Custom Events in Vid Stats

#Verify Your Setup

#TypeScript

#Troubleshooting

#The Event Does Not Appear in the Queue

#The Event Is in the Queue but Not in Vid Stats

#The Event Is Associated with the Wrong Video

#An Array Sends Only One Event