@glomex/integration-analytics 1.1480.0 → 1.1481.0

package/README.md

@@ -1,6 +1,6 @@
 # @glomex/integration-analytics
 
-A unified analytics integration package for the [turbo player](https://www.npmjs.com/package/@glomex/integration-web-component). This package provides adapters for various analytics providers including NPAW/Youbora, with planned support for Nielsen, Comscore, and more.
+A unified analytics integration package for the [turbo player](https://www.npmjs.com/package/@glomex/integration-web-component). This package provides adapters for various analytics providers including NPAW/Youbora, Comscore, Nielsen, and Sensic.
 
 ## Installation
 
@@ -21,7 +21,9 @@ import { connectToNpaw } from '@glomex/integration-analytics/npaw';
 const integration = document.querySelector('glomex-integration');
 
 // Simple setup for NPAW analytics (that also handles consent)
-const { npawPlugin, destroy } = connectToNpaw(integration, 'your-npaw-account-code');
+const { npawPlugin, destroy } = connectToNpaw(integration, {
+  accountCode: 'your-npaw-account-code'
+});
 ```
 
 #### Advanced NPAW Configuration
@@ -29,7 +31,8 @@ const { npawPlugin, destroy } = connectToNpaw(integration, 'your-npaw-account-co
 ```typescript
 import { connectToNpaw } from '@glomex/integration-analytics/npaw';
 
-const { npawPlugin, destroy } = connectToNpaw(integration, 'your-npaw-account-code', {
+const { npawPlugin, destroy } = connectToNpaw(integration, {
+  accountCode: 'your-npaw-account-code',
   appName: 'my-app',
   appVersion: '1.0.0'
 });
@@ -55,22 +58,249 @@ const npawPlugin = new NpawPlugin('your-npaw-account-code');
 npawPlugin.registerAdapterFromClass(integration, NpawTurboPlayerAdapter);
 ```
 
-## Planned Adapters
+### Comscore
+
+[Comscore Streaming Analytics](https://www.comscore.com/) integration for measuring streaming video consumption.
+
+```typescript
+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
+
+```typescript
+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](https://www.nielsen.com/solutions/audience-measurement/streaming-measurement/) integration for streaming measurement.
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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](https://sensic.net/) (formerly GfK) integration for streaming measurement in Germany and Austria.
+
+```typescript
+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:
+
+```typescript
+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
 
-The following adapters are planned for future releases:
+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`)
 
-- [Nielsen](https://www.nielsen.com/solutions/audience-measurement/streaming-measurement/) - `@glomex/integration-analytics/nielsen`
-- [Comscore](https://www.comscore.com/) - `@glomex/integration-analytics/comscore`
-- [GfK Sensic](https://sensic.net/) - `@glomex/integration-analytics/sensic`
-- [Datazoom](https://www.datazoom.io/) - `@glomex/integration-analytics/datazoom`
+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 various analytics providers
+- 📊 **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
+- 🔒 **Consent Handling**: Built-in consent management support with IAB TCF compliance
+- 🎬 **Comprehensive Tracking**: Tracks content and linear ad playback (preroll, midroll, postroll)
 
 ## License
 

package/dist/base-event-mapper.d.ts

@@ -0,0 +1,56 @@
+import { type IntegrationElement } from '@glomex/integration-web-component';
+/**
+ * Base class for analytics event mappers that handles:
+ * - Event subscription/unsubscription
+ * - Event queuing until SDK is ready
+ * - Common state management (stopped, inAd, contentStarted, hasContentImpression)
+ */
+export declare abstract class BaseEventMapper {
+    #private;
+    protected readonly integration: IntegrationElement;
+    protected readonly onWarn: (error: Error) => void;
+    constructor(integration: IntegrationElement, onWarn: (error: Error) => void);
+    /** Whether the event mapper has been stopped/destroyed */
+    protected get isStopped(): boolean;
+    /** Whether we are currently in an ad */
+    protected get isInAd(): boolean;
+    /** Whether onContentStart has been called */
+    protected get contentStarted(): boolean;
+    /**
+     * Mark SDK as ready and flush any queued events.
+     */
+    protected markSdkReady(): void;
+    protected onContentStart(): void;
+    protected onContentImpression(): void;
+    protected onContentPlay(): void;
+    protected onContentPause(): void;
+    protected onContentSeeking(): void;
+    protected onContentSeeked(): void;
+    protected onContentBufferingStart(): void;
+    protected onContentBufferingEnd(): void;
+    protected onContentEnded(): void;
+    protected onContentTimeUpdate(): void;
+    protected onVolumeChange(): void;
+    protected onPresentationModeChange(): void;
+    protected onAdImpression(): void;
+    protected onAdPaused(): void;
+    protected onAdResumed(): void;
+    protected onAdBufferingStart(): void;
+    protected onAdBufferingEnd(): void;
+    protected onAdEnd(): void;
+    protected onAdTimeUpdate(): void;
+    /**
+     * Override to perform SDK-specific cleanup (e.g., send end/stop signal).
+     * Called once when destroy() is invoked.
+     */
+    protected onDestroy(): void;
+    /**
+     * Tears down the event mapper:
+     * 1. Marks as stopped (prevents further event processing)
+     * 2. Calls onDestroy() for SDK-specific cleanup
+     * 3. Removes all event listeners
+     *
+     * Safe to call multiple times - subsequent calls are no-ops.
+     */
+    destroy(): void;
+}

package/dist/base-event-mapper.js

@@ -0,0 +1,313 @@
+import { IntegrationEvent } from '@glomex/integration-web-component';
+/** Ad break types that are tracked (linear ads) */
+const LINEAR_AD_BREAKS = ['preroll', 'midroll', 'postroll'];
+/**
+ * All playback events that analytics adapters may track
+ */
+const PLAYBACK_EVENTS = [
+    IntegrationEvent.CONTENT_START,
+    IntegrationEvent.CONTENT_IMPRESSION,
+    IntegrationEvent.CONTENT_PLAY,
+    IntegrationEvent.CONTENT_PAUSE,
+    IntegrationEvent.CONTENT_SEEKING,
+    IntegrationEvent.CONTENT_SEEKED,
+    IntegrationEvent.CONTENT_BUFFERING_START,
+    IntegrationEvent.CONTENT_BUFFERING_END,
+    IntegrationEvent.CONTENT_ENDED,
+    IntegrationEvent.CONTENT_STOP,
+    IntegrationEvent.CONTENT_TIME_UPDATE,
+    IntegrationEvent.CONTENT_VOLUME_CHANGE,
+    IntegrationEvent.PLAYER_SET_PRESENTATION_MODE,
+    IntegrationEvent.AD_IMPRESSION,
+    IntegrationEvent.AD_PAUSED,
+    IntegrationEvent.AD_RESUMED,
+    IntegrationEvent.AD_BUFFERING_START,
+    IntegrationEvent.AD_BUFFERING_END,
+    IntegrationEvent.AD_COMPLETE,
+    IntegrationEvent.AD_SKIPPED,
+    IntegrationEvent.AD_TIME_UPDATE,
+    IntegrationEvent.AD_ERROR
+];
+/**
+ * Base class for analytics event mappers that handles:
+ * - Event subscription/unsubscription
+ * - Event queuing until SDK is ready
+ * - Common state management (stopped, inAd, contentStarted, hasContentImpression)
+ */
+export class BaseEventMapper {
+    integration;
+    onWarn;
+    #stopped = false;
+    #inAd = false;
+    #contentStarted = false;
+    #hasContentImpression = false;
+    #eventHandler;
+    #eventQueue = [];
+    #sdkReady = false;
+    constructor(integration, onWarn) {
+        this.integration = integration;
+        this.onWarn = onWarn;
+        this.#eventHandler = this.#handleEvent.bind(this);
+        for (const eventType of PLAYBACK_EVENTS) {
+            this.integration.addEventListener(eventType, this.#eventHandler);
+        }
+    }
+    /** Whether the event mapper has been stopped/destroyed */
+    get isStopped() {
+        return this.#stopped;
+    }
+    /** Whether we are currently in an ad */
+    get isInAd() {
+        return this.#inAd;
+    }
+    /** Whether onContentStart has been called */
+    get contentStarted() {
+        return this.#contentStarted;
+    }
+    /**
+     * Mark SDK as ready and flush any queued events.
+     */
+    markSdkReady() {
+        this.#sdkReady = true;
+        for (const fn of this.#eventQueue) {
+            fn();
+        }
+        this.#eventQueue = [];
+    }
+    #enqueue(fn) {
+        if (this.#sdkReady) {
+            fn();
+        }
+        else {
+            this.#eventQueue.push(fn);
+        }
+    }
+    #handleEvent(event) {
+        if (this.#stopped)
+            return;
+        const handler = this.#getHandler(event.type);
+        if (!handler)
+            return;
+        this.#enqueue(() => {
+            try {
+                handler();
+            }
+            catch (error) {
+                this.onWarn(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    #getHandler(type) {
+        switch (type) {
+            case IntegrationEvent.CONTENT_START:
+                return () => {
+                    this.#contentStarted = true;
+                    this.onContentStart();
+                };
+            case IntegrationEvent.CONTENT_IMPRESSION:
+                return () => {
+                    this.#hasContentImpression = true;
+                    this.onContentImpression();
+                };
+            case IntegrationEvent.CONTENT_PLAY:
+                return () => {
+                    // plays before impression are not interesting
+                    if (!this.#hasContentImpression)
+                        return;
+                    // If ad didn't end properly, end it now
+                    if (this.#inAd) {
+                        this.onAdEnd();
+                        this.#inAd = false;
+                    }
+                    this.onContentPlay();
+                };
+            case IntegrationEvent.CONTENT_PAUSE:
+                return () => {
+                    if (!this.#hasContentImpression)
+                        return;
+                    this.onContentPause();
+                };
+            case IntegrationEvent.CONTENT_SEEKING:
+                return () => {
+                    if (!this.#hasContentImpression)
+                        return;
+                    this.onContentSeeking();
+                };
+            case IntegrationEvent.CONTENT_SEEKED:
+                return () => {
+                    if (!this.#hasContentImpression)
+                        return;
+                    this.onContentSeeked();
+                };
+            case IntegrationEvent.CONTENT_BUFFERING_START:
+                return () => {
+                    if (!this.#hasContentImpression)
+                        return;
+                    this.onContentBufferingStart();
+                };
+            case IntegrationEvent.CONTENT_BUFFERING_END:
+                return () => {
+                    if (!this.#hasContentImpression)
+                        return;
+                    this.onContentBufferingEnd();
+                };
+            case IntegrationEvent.CONTENT_ENDED:
+                return () => {
+                    if (!this.#hasContentImpression)
+                        return;
+                    this.onContentEnded();
+                };
+            case IntegrationEvent.CONTENT_STOP:
+                return () => this.destroy();
+            case IntegrationEvent.CONTENT_TIME_UPDATE:
+                return () => {
+                    if (!this.#hasContentImpression)
+                        return;
+                    this.onContentTimeUpdate();
+                };
+            case IntegrationEvent.CONTENT_VOLUME_CHANGE:
+                return () => this.onVolumeChange();
+            case IntegrationEvent.PLAYER_SET_PRESENTATION_MODE:
+                return () => this.onPresentationModeChange();
+            case IntegrationEvent.AD_IMPRESSION:
+                return () => {
+                    // only allow linear ads into #inAd mode
+                    if (!this.#isLinearAd(this.integration.currentAd))
+                        return;
+                    this.#inAd = true;
+                    this.onAdImpression();
+                };
+            case IntegrationEvent.AD_PAUSED:
+                return () => {
+                    if (!this.#inAd)
+                        return;
+                    this.onAdPaused();
+                };
+            case IntegrationEvent.AD_RESUMED:
+                return () => {
+                    if (!this.#inAd)
+                        return;
+                    this.onAdResumed();
+                };
+            case IntegrationEvent.AD_BUFFERING_START:
+                return () => {
+                    if (!this.#inAd)
+                        return;
+                    this.onAdBufferingStart();
+                };
+            case IntegrationEvent.AD_BUFFERING_END:
+                return () => {
+                    if (!this.#inAd)
+                        return;
+                    this.onAdBufferingEnd();
+                };
+            case IntegrationEvent.AD_COMPLETE:
+            case IntegrationEvent.AD_SKIPPED:
+            case IntegrationEvent.AD_ERROR:
+                return () => {
+                    if (!this.#inAd)
+                        return;
+                    this.onAdEnd();
+                    this.#inAd = false;
+                };
+            case IntegrationEvent.AD_TIME_UPDATE:
+                return () => {
+                    if (!this.#inAd)
+                        return;
+                    this.onAdTimeUpdate();
+                };
+            default:
+                return undefined;
+        }
+    }
+    // Default no-op implementations - subclasses override what they need
+    onContentStart() {
+        // no-op
+    }
+    onContentImpression() {
+        // no-op
+    }
+    onContentPlay() {
+        // no-op
+    }
+    onContentPause() {
+        // no-op
+    }
+    onContentSeeking() {
+        // no-op
+    }
+    onContentSeeked() {
+        // no-op
+    }
+    onContentBufferingStart() {
+        // no-op
+    }
+    onContentBufferingEnd() {
+        // no-op
+    }
+    onContentEnded() {
+        // no-op
+    }
+    onContentTimeUpdate() {
+        // no-op
+    }
+    onVolumeChange() {
+        // no-op
+    }
+    onPresentationModeChange() {
+        // no-op
+    }
+    onAdImpression() {
+        // no-op
+    }
+    onAdPaused() {
+        // no-op
+    }
+    onAdResumed() {
+        // no-op
+    }
+    onAdBufferingStart() {
+        // no-op
+    }
+    onAdBufferingEnd() {
+        // no-op
+    }
+    onAdEnd() {
+        // no-op
+    }
+    onAdTimeUpdate() {
+        // no-op
+    }
+    /**
+     * Override to perform SDK-specific cleanup (e.g., send end/stop signal).
+     * Called once when destroy() is invoked.
+     */
+    onDestroy() {
+        // no-op
+    }
+    /**
+     * Check if the ad is a linear ad (preroll, midroll, postroll).
+     */
+    #isLinearAd(ad) {
+        if (!ad)
+            return false;
+        return LINEAR_AD_BREAKS.includes(ad.breakName);
+    }
+    /**
+     * Tears down the event mapper:
+     * 1. Marks as stopped (prevents further event processing)
+     * 2. Calls onDestroy() for SDK-specific cleanup
+     * 3. Removes all event listeners
+     *
+     * Safe to call multiple times - subsequent calls are no-ops.
+     */
+    destroy() {
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        this.onDestroy();
+        for (const eventType of PLAYBACK_EVENTS) {
+            this.integration.removeEventListener(eventType, this.#eventHandler);
+        }
+    }
+}

package/dist/comscore/comscore-event-mapper.d.ts

@@ -0,0 +1,26 @@
+import { type IntegrationElement } from '@glomex/integration-web-component';
+import { BaseEventMapper } from '../base-event-mapper.js';
+import type { Analytics, ContentMetadataInstance } from './comscore-types.js';
+export declare class ComscoreEventMapper extends BaseEventMapper {
+    #private;
+    constructor(integration: IntegrationElement, sdkReadyPromise: Promise<{
+        analytics: Analytics;
+        contentMetadata: ContentMetadataInstance;
+    } | undefined>, onWarn: (error: Error) => void);
+    protected onContentStart(): void;
+    protected onContentImpression(): void;
+    protected onContentPlay(): void;
+    protected onContentPause(): void;
+    protected onContentSeeking(): void;
+    protected onContentSeeked(): void;
+    protected onContentBufferingStart(): void;
+    protected onContentBufferingEnd(): void;
+    protected onContentEnded(): void;
+    protected onAdImpression(): void;
+    protected onAdPaused(): void;
+    protected onAdResumed(): void;
+    protected onAdBufferingStart(): void;
+    protected onAdBufferingEnd(): void;
+    protected onAdEnd(): void;
+    protected onDestroy(): void;
+}