A unified analytics integration package for the turbo player. This package provides adapters for various analytics providers including NPAW/Youbora, Comscore, Nielsen, and Sensic.

Installation

npm install @turbo-player/integration-analytics

Available Adapters

NPAW/Youbora

NPAW analytics integration for video analytics and quality of experience monitoring.

import { connectToNpaw } from '@turbo-player/integration-analytics/npaw';


const integration = document.querySelector('my-integration');

// Simple setup for NPAW analytics (that also handles consent)
const { npawPlugin, destroy } = connectToNpaw(integration, {
  accountCode: 'your-npaw-account-code'
});

Advanced NPAW Configuration

import { connectToNpaw } from '@turbo-player/integration-analytics/npaw';

const { npawPlugin, destroy } = connectToNpaw(integration, {
  accountCode: 'your-npaw-account-code',
  appName: 'my-app',
  appVersion: '1.0.0'
});

npawPlugin.setAnalyticsOptions({
  userId: 'my-user-id',
  'content.customDimensions': {
    tenant: 'my-tenant'
  }
});

// Clean up when done
destroy();

Direct NPAW Integration

import { NpawTurboPlayerAdapter } from '@turbo-player/integration-analytics/npaw';
import NpawPlugin from 'npaw-plugin';

const npawPlugin = new NpawPlugin('your-npaw-account-code');
npawPlugin.registerAdapterFromClass(integration, NpawTurboPlayerAdapter);

Comscore

Comscore Streaming Analytics integration for measuring streaming video consumption.

import { connectToComscore } from '@turbo-player/integration-analytics/comscore';


const integration = document.querySelector('my-integration');

// Connect Comscore analytics
const disconnect = connectToComscore(integration, {
  publisherId: 'your-publisher-id',
  publisherName: 'Your Publisher Name'
});

// Clean up when done
disconnect();

Comscore Configuration Options

Option	Type	Required	Description
`publisherId`	`string`	Yes	Your Comscore publisher ID
`publisherName`	`string`	Yes	Your publisher name (e.g., "Joyn")
`debug`	`boolean`	No	Enable debug mode for implementation validation
`warnCallback`	`(error: Error) => void`	No	Custom callback for warning messages
`configureContentMetadata`	`(metadata) => metadata \| null`	No	Customize content metadata before tracking

Advanced Comscore Configuration

import { connectToComscore } from '@turbo-player/integration-analytics/comscore';

const disconnect = connectToComscore(integration, {
  publisherId: 'your-publisher-id',
  publisherName: 'Your Publisher Name',
  debug: true,
  warnCallback: (error) => {
    console.warn('Comscore warning:', error.message);
  },
  configureContentMetadata: (metadata) => {
    // Customize metadata or return null to skip tracking
    metadata.setGenreName('Sports');
    return metadata;
  }
});

Comscore tracking only occurs when the user has given consent according to IAB TCF:

Purpose 1 consent (Store and/or access information on a device)
Vendor 77 consent (Comscore)

Nielsen

Nielsen Digital Content Ratings integration for streaming measurement.

import { connectToNielsen } from '@turbo-player/integration-analytics/nielsen';


const integration = document.querySelector('my-integration');

// Connect Nielsen analytics
const disconnect = connectToNielsen(integration, {
  appId: 'your-app-id',
  country: 'de'
});

// Clean up when done
disconnect();

Nielsen Configuration Options

Option	Type	Required	Description
`appId`	`string`	Yes	Nielsen App ID (starts with 'P' for production, 'T' for test)
`country`	`string`	Yes	Two-letter country code for country-specific metadata mapping (e.g., 'de' for Germany)
`debug`	`boolean`	No	Enable Nielsen SDK debug mode
`warnCallback`	`(error: Error) => void`	No	Custom callback for warning messages
`configureContentMetadata`	`(metadata) => metadata \| null`	No	Extend/modify content metadata for tracking
`configureAdMetadata`	`(metadata) => metadata`	No	Extend/modify ad metadata for tracking

Supported Countries

Nielsen uses country-specific metadata mappings:

'de' - Germany (uses AGF-specific custom variables)
Other country codes - Base metadata only (assetid, type, program, title, length for content; assetid, type for ads)

For Germany (country: 'de'), the following metadata is automatically built:

Content metadata: assetid, program, title, length, nol_c0 (part number), nol_c2 (web only flag), nol_c5 (page URL), nol_c7 (video ID), nol_c9 (video title), nol_c10 (publisher), nol_c12 (video type), nol_c15 (format ID), nol_c18 (livestream flag)
Ad metadata: assetid, type, length, title, nol_c1 (universal ad ID), nol_c2, nol_c4 (ad form), nol_c10, nol_c11 (ad ID), nol_c12, nol_c17 (placement type), nol_c18

For unsupported country codes, only base metadata is provided. Use configureContentMetadata and configureAdMetadata to add country-specific fields manually:

const disconnect = connectToNielsen(integration, {
  appId: 'your-app-id',
  country: 'fr', // No built-in mapping for France
  configureContentMetadata: (baseMetadata) => {
    // baseMetadata contains: assetid, type, program, title, length
    return {
      ...baseMetadata,
      program: integration.content?.show?.name ?? '',
      // Add France-specific fields as needed
    };
  },
  configureAdMetadata: (baseMetadata) => {
    // baseMetadata contains: assetid, type
    return {
      ...baseMetadata,
      title: integration.currentAd?.title ?? ''
    };
  }
});

Advanced Nielsen Configuration

The configureContentMetadata and configureAdMetadata callbacks receive country-specific metadata that is automatically built from integration data. You can extend or modify this metadata:

import { connectToNielsen } from '@turbo-player/integration-analytics/nielsen';

const disconnect = connectToNielsen(integration, {
  appId: 'your-app-id',
  country: 'de',
  debug: true,
  warnCallback: (error) => {
    console.warn('Nielsen warning:', error.message);
  },
  configureContentMetadata: (metadata) => {
    // metadata contains country-specific fields (e.g., AGF fields for 'de')
    // Return null to skip tracking this content
    if (!integration.content) return null;
    
    return {
      ...metadata,
      // Add custom fields or override existing ones
      subbrand: 'abc' // VCID provided by Nielsen
    };
  },
  configureAdMetadata: (metadata) => {
    // metadata contains country-specific ad fields
    return {
      ...metadata,
      subbrand: 'abc'
    };
  }
});

Nielsen does not require consent checks and uses a synchronous stub pattern. Events are queued until the SDK loads from CDN.

Sensic (GfK)

Sensic (formerly GfK) integration for streaming measurement in Germany and Austria.

import { connectToSensic } from '@turbo-player/integration-analytics/sensic';


const integration = document.querySelector('my-integration');

// Connect Sensic analytics
const disconnect = connectToSensic(integration, {
  media: 'your-media-id',
  platform: 'web',
  country: 'de'
});

// Clean up when done
disconnect();

Sensic Configuration Options

Option	Type	Required	Description
`media`	`string`	Yes	Sensic media identifier
`platform`	`'web' \| 'tv'`	Yes	Platform type
`country`	`string`	Yes	Two-letter country code (e.g., `'de'`, `'at'`)
`warnCallback`	`(error: Error) => void`	No	Custom callback for warning messages
`buildCustomParams`	`(customParams) => Record<string, string> \| null`	No	Extend/modify custom parameters for tracking
`buildStreamId`	`(streamId) => string`	No	Extend/modify stream ID for tracking

Advanced Sensic Configuration

The buildCustomParams and buildStreamId callbacks receive country-specific values as input and are called on each stream start (VoD content, live content, and linear ads). Use integration.content for content data or integration.currentAd for ad data:

import { connectToSensic } from '@turbo-player/integration-analytics/sensic';

const disconnect = connectToSensic(integration, {
  media: 'your-media-id',
  platform: 'web',
  country: 'at',
  warnCallback: (error) => {
    console.warn('Sensic warning:', error.message);
  },
  buildCustomParams: (customParams) => {
    // customParams contains country-specific params (e.g., AT params for Austria)
    // Return null to skip tracking this stream
    return {
      ...customParams,
      genre: integration.content?.genre ?? '',
      showId: integration.content?.show?.id ?? ''
    };
  },
  buildStreamId: (streamId) => {
    // streamId contains country-specific stream ID
    return streamId || integration.content?.id ?? '';
  }
});

Sensic tracking only occurs when the user has given consent according to IAB TCF:

Vendor 758 consent (Sensic)

Supported Countries

Sensic loads country-specific measurement scripts:

'de' - Germany (https://de-config.sensic.net/s2s-web.js)
'at' - Austria (https://at-config.sensic.net/s2s-web.js)

For TV platforms, the CTV variant is loaded automatically (e.g., https://de-config.sensic.net/ctv/s2s-web.js).

Features

🎯 Easy Integration: Simple setup with turbo player
📊 Multiple Providers: Support for NPAW, Comscore, Nielsen, and Sensic (all certified by the providers)
🔧 Smart Metadata Mapping: Automatically maps player content metadata to each analytics provider's format, with full support for custom overrides
📱 Cross-Platform: Works with web, mobile web, and embedded players
🔒 Consent Handling: Built-in consent management support with IAB TCF compliance
🎬 Comprehensive Tracking: Tracks content and linear ad playback (preroll, midroll, postroll)