Skip to main content

Consuming Events

The tracker library emits tracking events through multiple mechanisms to facilitate integration with various analytics platforms and custom event consumers. This document explains how to consume these events using the three available sources and provides practical examples for integrating with Adobe Analytics and Google Analytics.

For a detailed list of all possible events and their data structures, please refer to the Tracker Events and Data documentation.

Event Emission Sources​

The tracker emits events through the following mechanisms:

1. Window Event (CustomEvent)​

A custom event is dispatched on the window (or globalThis) object:

window.dispatchEvent(
  new CustomEvent('onlive-analytics-event', {
    detail: {
      event: 'event_name',
      data: {
        /* event data */
      },
    },
  }),
);

2. Data Layer Push​

The event is pushed to a global data layer array, similar to how Google Tag Manager operates:

window.onliveDataLayer.push({
  event: 'event_name',
  data: {
    /* event data */
  },
});

3. Window PostMessage​

A message is posted to the top window, which can be consumed by other frames or scripts:

window.top.postMessage(
  {
    provider: 'onlive',
    event: 'event_name',
    data: {
      /* event data */
    },
  },
  '*',
);

Consuming Events​

1. Listening to the Custom Window Event​

You can listen for the custom event using addEventListener:

window.addEventListener('onlive-analytics-event', (e) => {
  const { event, data } = e.detail;
  // Handle the event
});

2. Consuming from the Data Layer​

You can use a polling mechanism or a Proxy to observe pushes to the data layer:

Polling Example​

const originalPush = window.onliveDataLayer.push;
window.onliveDataLayer.push = function (...args) {
  args.forEach(({ event, data }) => {
    // Handle the event
  });
  return originalPush.apply(this, args);
};

3. Listening to PostMessage Events​

You can listen for messages on the window:

window.addEventListener('message', (e) => {
  if (e.data && e.data.provider === 'onlive') {
    const { event, data } = e.data;
    // Handle the event
  }
});

Integration Examples​

This section provides concrete examples of how to forward tracker events to popular analytics platforms.

Basic Forwarding​

If you only need to forward events directly without custom transformations, you can use a simple listener.

window.addEventListener('onlive-analytics-event', (e) => {
  const { event, data } = e.detail;

  // Forward to Google Analytics
  if (window.gtag) {
    window.gtag('event', event, data);
  }

  // Forward to Segment
  if (window.analytics && typeof window.analytics.track === 'function') {
    window.analytics.track(event, data);
  }

  // Forward to Adobe Analytics
  if (window.s && typeof window.s.tl === 'function') {
    window.s.tl(true, 'o', event, data);
  }
});

Advanced: Custom Integration​

This approach is useful when your analytics platform requires specific event names and parameters that differ from the raw events emitted by the tracker. Below are examples for different platforms.

Custom Google Analytics Integration​

window.addEventListener('onlive-analytics-event', (e) => {
  const { event, data } = e.detail;

  // Widget Impression
  if (event === 'impression' && data.impression_type === 'widget') {
    window.gtag('event', 'widget_impression', {
      event_category: 'Onlive',
      event_label: 'Widget Impression',
    });
  }

  // Appointment Confirmed
  if (event === 'task_success' && data.task_name === 'book_meeting') {
    window.gtag('event', 'appointment_confirmed', {
      event_category: 'Onlive',
      event_label: 'Appointment Confirmed',
      task_name: data.task_name,
    });
  }
});

Custom Adobe Analytics Integration​

window.addEventListener('onlive-analytics-event', (e) => {
  const { event, data } = e.detail;

  // Widget Impression
  if (event === 'impression' && data.impression_type === 'widget') {
    window.s.linkTrackVars = 'eVar1,events';
    window.s.linkTrackEvents = 'event1';
    window.s.eVar1 = 'Widget Impression';
    window.s.events = 'event1';
    window.s.tl(true, 'o', 'Onlive Widget Impression');
  }

  // Appointment Confirmed
  if (event === 'task_success' && data.task_name === 'book_meeting') {
    window.s.linkTrackVars = 'eVar1,eVar2,events';
    window.s.linkTrackEvents = 'event2';
    window.s.eVar1 = 'Appointment Confirmed';
    window.s.eVar2 = data.task_name;
    window.s.events = 'event2';
    window.s.tl(true, 'o', 'Onlive Appointment Confirmed');
  }
});

Custom Segment Integration​

window.addEventListener('onlive-analytics-event', (e) => {
  const { event, data } = e.detail;

  // Widget Impression
  if (event === 'impression' && data.impression_type === 'widget') {
    window.analytics.track('Widget Impression', {
      platform: 'Onlive',
      impression_type: data.impression_type,
    });
  }

  // Appointment Confirmed
  if (event === 'task_success' && data.task_name === 'book_meeting') {
    window.analytics.track('Appointment Confirmed', {
      platform: 'Onlive',
      task_name: data.task_name,
    });
  }
});

Best Practices​

  • Choose the right source: Use the event source that best fits your integration scenario. For most analytics platforms, the data layer or custom event is recommended.
  • Validate event data: Always validate the structure of the event data before forwarding to third-party services.
  • Avoid duplicate handling: If you listen to multiple sources, ensure you do not process the same event more than once.
  • Performance: Avoid heavy processing in event listeners to keep the UI responsive.
  • Security: When using postMessage, always validate the origin and structure of incoming messages.

Additional Notes​

  • The event name and data structure are defined in the Tracker Events and Data documentation and should be consistent across all sources.
  • You can enable or disable each emitter via the tracker configuration (emitters property).
  • For advanced integrations, consider batching or debouncing events before forwarding to analytics platforms.

References​