@glomex/integration-analytics

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 @glomex/integration-analytics

Available Adapters

NPAW/Youbora

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

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

// Get your integration element
const integration = document.querySelector('glomex-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 '@glomex/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 '@glomex/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 '@glomex/integration-analytics/comscore';

// Get your integration element
const integration = document.querySelector('glomex-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 '@glomex/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 Consent Requirements

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 '@glomex/integration-analytics/nielsen';

// Get your integration element
const integration = document.querySelector('glomex-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 '@glomex/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 Consent

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 '@glomex/integration-analytics/sensic';

// Get your integration element
const integration = document.querySelector('glomex-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 '@glomex/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 Consent Requirements

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
• 🔧 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)

License

MIT

Support

For issues and questions, please visit the glomex documentation or contact support.