Tracker Library

The Onlive Tracker Library is a powerful and lightweight solution for capturing user interaction events in your web application. Designed with type safety and developer experience in mind, it uses Zod for schema validation to ensure that all tracking data is accurate and consistently structured. This allows you to reliably track a wide range of events, from simple page impressions to complex form interactions, with full confidence in your data integrity.

This documentation provides instructions on how to install and use the Onlive Tracker library in your projects.

Installation

You can install the tracker library using your favorite package manager:

# PNPM
pnpm add @onlive.site/tracker

# NPM
npm install @onlive.site/tracker

# Yarn
yarn add @onlive.site/tracker

Usage

The Onlive Tracker library can be used in different environments, including modern ESM projects, traditional CommonJS setups, and directly in the browser via a CDN.

ESM Example

For modern JavaScript projects using ES modules, you can import and use the Tracker class as follows:

import { Tracker } from '@onlive.site/tracker';

const tracker = new Tracker({ apiUrl: 'https://srvless.onlive.site/tracking' });

// Track a widget impression
await tracker.send('impression', {
  // Impression Data
  impression_type: 'widget',

  // Organization Data
  organization_id: '123e4567-e89b-12d3-a456-426614174000',
  organization_name: 'Onlive Site.',

  // Session Data
  guest_id: '550e8400-e29b-41d4-a716-446655440000',

  // Origin Data
  page_url: 'https://example.com/products/item123',
  page_referrer: 'https://google.com/search',

  // Widget Data
  widget_id: 'abc12345-e89b-12d3-a456-426614174000',
  widget_name: 'lola_assistant',
  widget_type: 'OnliveAppChatbot',

  // Extra Data
  extra: {
    car_brand: 'cupra',
    car_model: 'leon',
  },
});

CommonJS Example

For Node.js environments using CommonJS, you can use require to import the library:

const OnliveTracker = require('@onlive.site/tracker');

const tracker = new OnliveTracker.Tracker({ apiUrl: 'https://srvless.onlive.site/tracking' });

// Track a widget impression
await tracker.send('impression', {
  // Impression Data
  impression_type: 'widget',

  // Organization Data
  organization_id: '123e4567-e89b-12d3-a456-426614174000',

  // Widget Data
  widget_id: 'abc12345-e89b-12d3-a456-426614174000',
  widget_name: 'lola_assistant',
});

UMD (CDN) Example

You can also use the tracker directly in an HTML file by including it from a CDN. This is useful for simple web pages or integrations where a full build setup is not available.

<script src="https://cdn.onlive.site/@onlive.site/tracker@latest/umd/tracker.js"></script>
<!-- OR <script src="https://cdn.onlive.site/@onlive.site/tracker@<version>/umd/tracker.js"></script> -->
<script>
  const { Tracker } = window.OnliveTracker;
  const tracker = new Tracker({ apiUrl: 'https://srvless.onlive.site/tracking' });

  // Track a widget impression
  tracker.send('impression', {
    // Impression Data
    impression_type: 'page',

    // Organization Data
    organization_id: '123e4567-e89b-12d3-a456-426614174000',

    // Origin Data
    page_url: 'https://example.com/product',
  });
</script>

Configuration

When instantiating the Tracker, you can pass a configuration object with the following properties:

Name	Type	Default	Description
apiUrl	string	-	Required. The URL of the tracking server.
instanceName	string	-	A name for the tracker instance, useful for handle multiple instances.
dryRun	boolean	false	If true, events are logged to the console instead of being sent to the server.
allowBotTraffic	boolean	false	If false, traffic from known bots will be ignored.
removeExtraneousValues	boolean	true	If true, any properties not defined in the event schema will be removed before sending.
emitters	object	{ windowEvent: true, dataLayer: true, windowPostMessage: true }	An object to control where events are emitted.

Production and Staging URLs

• Production apiUrl: https://srvless.onlive.site/tracking
• Staging apiUrl: https://lfhew0-srvless.onlive.site/tracking

Sending Events

To send an event, use the send method on your tracker instance. It takes the event name and a payload object with the event's data.

tracker.send('event_name', {
  property1: 'value1',
  property2: 'value2',
});

The send method is type-safe, providing autocompletion and validation for event properties if you are using TypeScript.

Setting Base Data

If you need to send the same data with every event (e.g., organization ID, application ID), you can use the setBase method to avoid repetition.

tracker.setBase({
  org_id: '123e4567-e89b-12d3-a456-426614174000',
  org_name: 'Example Org',
  app_id: '123e4567-e89b-12d3-a456-426614174001',
  app_name: 'Example App',
});

// Now, you only need to provide the properties specific to the event
await tracker.send('impression', {
  widget_id: '123e4567-e89b-12d3-a456-426614174002',
  widget_type: 'chat',
  page_url: 'https://example.com/product',
});

The base data will be automatically merged with each event payload.