infront-event-analytics v1.0.5

Infront Event Analytics

A lightweight analytics tracking library designed for video player events and general analytics tracking.

Installation

npm install infront-event-analytics

Basic Usage

import { Tracker } from 'infront-event-analytics';

// Initialize tracker with your analytics endpoint
const tracker = new Tracker('https://your-analytics-endpoint.com');

// Track a video event
tracker.trackCurrentTime('https://your-api-endpoint.com', 30, 'userId', 'videoId');

// Track a page visit
tracker.trackVisit({
    page_title: 'Home Page',
    user_id: 'user-123',
    channel_token: 'channel-456'
});

Features

• Lightweight event tracking
• Video playback analytics
• Continue watching support
• Beacon API support for reliable event sending
• Custom event tracking
• Advanced analytics capabilities
• Automatic user identification
• Table-specific event categorization

API Reference

Tracker Class

The main class for tracking events.

const tracker = new Tracker('https://your-analytics-endpoint.com');

Methods

trackCurrentTime(endpoint, currentTime, userId, inputToken)

Tracks the current time of video playback using the Beacon API.

tracker.trackCurrentTime(
    'https://api.example.com/tracking', 
    120.5,  // current time in seconds
    'user-123', 
    'video-456'
);

trackVisit(properties)

Tracks page visits with custom properties.

tracker.trackVisit({
    page_title: 'Channel Page',
    type: 'channel page',
    organization_id: 'org-123',
    channel_token: 'channel-456',
    user_id: 'user-789'
});

trackImpression(properties)

Tracks video impression events.

tracker.trackImpression({
    video_id: 'video-123',
    user_id: 'user-456',
    channel_token: 'channel-789'
});

trackSectionWatched(properties)

Tracks completion of video sections.

tracker.trackSectionWatched({
    video_id: 'video-123',
    section: 'intro',
    duration: 120,
    user_id: 'user-456'
});

trackSearch(properties)

Tracks search events with automatic lowercase query handling.

tracker.trackSearch({
    search_query: 'Tutorial Videos',
    channel_token: 'channel-123',
    channel_numeric_token: '123',
    user_id: 'user-456'
});

Example Usage with Video Player

import { Tracker } from 'infront-event-analytics';

const tracker = new Tracker('https://your-analytics-endpoint.com');
const cwURL = 'https://api.example.com/continue-watching';

// Track current time during video playback
player.on('timeupdate', (e, data) => {
    tracker.trackCurrentTime(
        cwURL,
        data.currentTime,
        "userId",
        "videoId"
    );
});

// Track video impressions
player.on('play', () => {
    tracker.trackImpression({
        video_id: "videoId",
        user_id: "userId",
        channel_token: "channelToken"
    });
});

// Track video end
player.on('ended', () => {
    tracker.trackCurrentTime(cwURL, -1, "userId", "videoId");
});

// Track before page unload
window.addEventListener('beforeunload', () => {
    tracker.trackCurrentTime(cwURL, player.currentTime, "userId", "videoId");
});

Advanced Features

Analytics Integration

The library provides advanced analytics tracking capabilities. Events are automatically formatted and sent to your analytics endpoint.

Beacon API Support

The library uses the Beacon API when available for reliable event sending, especially useful during page unload.

Error Handling

All tracking methods include error handling and will fail silently to prevent affecting the main application. The library validates endpoint configuration and throws clear errors when misconfigured.

Table-Specific Event Categorization

Events are automatically categorized into specific tables for better data organization:

• Visits: __table: 'visits'
• Video Events: __table: 'video_events'
• Search Events: __table: 'channel_search_trends'

License

MIT License. See LICENSE file for details.