@onlive.ai/tracker v1.0.9

Onlive Tracker

This project contains tracking events and data schemas for the Onlive platform.

Key Features

• Type Safety: Full TypeScript support with property autocomplete
• Schema Validation: Uses Zod to validate event payloads at runtime
• Modular Design: Easily add new events and property types
• Reusable Property Sets: Define common property sets in data files

👨‍💻 Development

Install dependencies

pnpm install

Build

pnpm build

Publish

pnpm changeset publish

Documentation Generator

This project includes a documentation generator that analyzes TypeScript files in the events and data folders to generate comprehensive Markdown documentation based on JSDoc comments and Zod schemas.

How to Generate Documentation

Run the following command to generate documentation:

pnpm generate-docs

This will:

1. Analyze all event files in src/tracker/events
2. Analyze all data files in src/tracker/data
3. Extract JSDoc comments and Zod schema definitions
4. Generate a comprehensive Markdown file at docs/tracker-documentation.md

How It Works

The documentation generator:

• Parses TypeScript files using the TypeScript compiler API
• Extracts JSDoc comments for descriptions, examples, and metadata
• Analyzes Zod schema definitions to determine property types and constraints
• Generates structured Markdown with tables for properties and their descriptions
• Creates a table of contents with links to each section

Documentation Format

The generated documentation includes:

• A table of contents with links to each section
• Events section with each event type detailed:
  • Description
  • Property table (name, type, possible values, description, required)
  • JSON example
• Data section with each data structure detailed:
  • Description
  • Property table (name, type, possible values, description, required)
  • JSON example (when available)

Requirements for JSDoc Comments

For best results, use the following JSDoc format in your event and data files:

/**
 * @name event_name
 * @description Detailed description of the event
 *
 * @example
 * {
 *   "property1": "value1",
 *   "property2": "value2"
 * }
 */

For properties, use:

/**
 * @description Description of the property
 * @example "possible value", "another value"
 */
property: z.string();

📖 Usage

You can use the library as ES module, as CommonJS or as UMD dependency.

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

ESM Example

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

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

// Track a widget impression
await tracker.send('widget_impression', {
  org_id: '123e4567-e89b-12d3-a456-426614174000',
  org_name: 'Example Org',
  app_id: '123e4567-e89b-12d3-a456-426614174001',
  app_name: 'Example App',
  widget_id: '123e4567-e89b-12d3-a456-426614174002',
  widget_type: 'chat',
  page_url: 'https://example.com/product',
  timestamp: Date.now(),
});

CommonJS Example

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

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

// Track a widget impression
await tracker.send('widget_impression', {
  org_id: '123e4567-e89b-12d3-a456-426614174000',
  org_name: 'Example Org',
  app_id: '123e4567-e89b-12d3-a456-426614174001',
  app_name: 'Example App',
  widget_id: '123e4567-e89b-12d3-a456-426614174002',
  widget_type: 'chat',
  page_url: 'https://example.com/product',
  timestamp: Date.now(),
});

UMD Example

<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('widget_impression', {
    org_id: '123e4567-e89b-12d3-a456-426614174000',
    org_name: 'Example Org',
    app_id: '123e4567-e89b-12d3-a456-426614174001',
    app_name: 'Example App',
    widget_id: '123e4567-e89b-12d3-a456-426614174002',
    widget_type: 'chat',
    page_url: 'https://example.com/product',
    timestamp: Date.now(),
  });
</script>

Adding a New Event Type

1. Create a new track type file in tracks/types/my-event.track.ts:

import { z } from 'zod';
import { OrganizationData } from '../data/organization.data';
import { ApplicationData } from '../data/application.data';

export const MyEventTrack = z.object({
  ...OrganizationData.shape,
  ...ApplicationData.shape,
  my_property: z.string(),
  timestamp: z.number(),
});

export type MyEventTrack = z.infer<typeof MyEventTrack>;

2. Add the new event to the registry in tracks/registry.ts:

import { MyEventTrack } from './types/my-event.track';

export const TrackRegistry = {
  // ...existing events...
  my_event: MyEventTrack,
} as const;

3. Export the new event type in tracks/index.ts:

export * from './types/my-event.track';

Creating New Property Sets

1. Create a new data file in tracks/data/my-properties.data.ts:

import { z } from 'zod';

export const MyPropertiesData = z.object({
  property1: z.string(),
  property2: z.number(),
});

export type MyPropertiesData = z.infer<typeof MyPropertiesData>;

2. Use the property set in a track type:

import { MyPropertiesData } from '../data/my-properties.data';

export const MyEventTrack = z.object({
  ...MyPropertiesData.shape,
  // ...other properties
});

Architecture

• tracks/registry.ts: Central registry for all event types
• tracks/tracker.ts: Main tracker class with type-safe send method
• tracks/types/: Contains all event type definitions
• tracks/data/: Contains reusable property sets

Benefits

• Prevents typos in event names and property names
• Ensures all required properties are included
• Provides autocomplete for event properties in your IDE
• Validates property values at runtime