@glomex/integration-analytics 1.1480.0 → 1.1481.0

package/dist/comscore/comscore-event-mapper.js

@@ -0,0 +1,218 @@
+import { PlaybackMode } from '@glomex/integration-web-component';
+import { BaseEventMapper } from '../base-event-mapper.js';
+export class ComscoreEventMapper extends BaseEventMapper {
+    #analytics;
+    #streamingAnalytics;
+    #contentMetadata;
+    #wasInAd = false;
+    constructor(integration, sdkReadyPromise, onWarn) {
+        super(integration, onWarn);
+        sdkReadyPromise.then((result) => {
+            if (this.isStopped)
+                return;
+            if (!result)
+                return;
+            this.#analytics = result.analytics;
+            this.#contentMetadata = result.contentMetadata;
+            const mediaType = this.#determineContentMediaType();
+            this.#contentMetadata.setMediaType(mediaType);
+            this.markSdkReady();
+        });
+    }
+    onContentStart() {
+        if (!this.#analytics)
+            return;
+        this.#streamingAnalytics = new this.#analytics.StreamingAnalytics();
+        this.#streamingAnalytics.createPlaybackSession();
+        this.#streamingAnalytics.setMediaPlayerName('turbo-player');
+        this.#streamingAnalytics.setMediaPlayerVersion(this.integration.version);
+        if (this.#contentMetadata) {
+            this.#streamingAnalytics.setMetadata(this.#contentMetadata);
+        }
+    }
+    onContentImpression() {
+        if (!this.#analytics || !this.#streamingAnalytics)
+            return;
+        // After preroll ends, we need to restore content metadata
+        if (this.#wasInAd) {
+            if (this.#contentMetadata) {
+                this.#streamingAnalytics.setMetadata(this.#contentMetadata);
+            }
+            this.#wasInAd = false;
+        }
+        this.#updatePlaybackPosition();
+        this.#streamingAnalytics.notifyPlay();
+    }
+    onContentPlay() {
+        if (!this.#analytics || !this.#streamingAnalytics)
+            return;
+        if (this.integration.seeking)
+            return;
+        // After ad ends, we need to restore content metadata
+        if (this.#wasInAd) {
+            if (this.#contentMetadata) {
+                this.#streamingAnalytics.setMetadata(this.#contentMetadata);
+            }
+            this.#updatePlaybackPosition();
+            this.#wasInAd = false;
+        }
+        this.#streamingAnalytics.notifyPlay();
+    }
+    onContentPause() {
+        if (!this.#streamingAnalytics)
+            return;
+        if (this.integration.seeking)
+            return;
+        this.#streamingAnalytics.notifyPause();
+    }
+    onContentSeeking() {
+        if (!this.#streamingAnalytics)
+            return;
+        this.#streamingAnalytics.notifySeekStart();
+    }
+    onContentSeeked() {
+        if (!this.#streamingAnalytics)
+            return;
+        this.#updatePlaybackPosition();
+        if (!this.integration.paused) {
+            this.#streamingAnalytics.notifyPlay();
+        }
+    }
+    onContentBufferingStart() {
+        if (!this.#streamingAnalytics)
+            return;
+        if (this.integration.seeking)
+            return;
+        this.#streamingAnalytics.notifyBufferStart();
+    }
+    onContentBufferingEnd() {
+        if (!this.#streamingAnalytics)
+            return;
+        if (this.integration.seeking)
+            return;
+        this.#streamingAnalytics.notifyBufferStop();
+    }
+    onContentEnded() {
+        if (!this.#streamingAnalytics)
+            return;
+        this.#streamingAnalytics.notifyEnd();
+    }
+    onAdImpression() {
+        if (!this.#analytics || !this.#streamingAnalytics)
+            return;
+        const ad = this.integration.currentAd;
+        if (!ad)
+            return;
+        const mediaType = this.#determineAdMediaType(ad.breakName);
+        const adMetadata = new this.#analytics.StreamingAnalytics.AdvertisementMetadata();
+        const adId = ad.universalAdIds?.[0]?.id || ad.id;
+        if (adId) {
+            adMetadata.setUniqueId(adId);
+        }
+        if (ad.duration) {
+            adMetadata.setLength(ad.duration);
+        }
+        adMetadata.setMediaType(mediaType);
+        if (this.#contentMetadata) {
+            adMetadata.setRelatedContentMetadata(this.#contentMetadata);
+        }
+        this.#streamingAnalytics.setMetadata(adMetadata);
+        this.#streamingAnalytics.notifyPlay();
+    }
+    onAdPaused() {
+        if (!this.#streamingAnalytics || !this.isInAd)
+            return;
+        this.#streamingAnalytics.notifyPause();
+    }
+    onAdResumed() {
+        if (!this.#streamingAnalytics || !this.isInAd)
+            return;
+        this.#streamingAnalytics.notifyPlay();
+    }
+    onAdBufferingStart() {
+        if (!this.#streamingAnalytics || !this.isInAd)
+            return;
+        this.#streamingAnalytics.notifyBufferStart();
+    }
+    onAdBufferingEnd() {
+        if (!this.#streamingAnalytics || !this.isInAd)
+            return;
+        this.#streamingAnalytics.notifyBufferStop();
+    }
+    onAdEnd() {
+        if (!this.#streamingAnalytics)
+            return;
+        this.#streamingAnalytics.notifyEnd();
+        this.#wasInAd = true;
+    }
+    #updatePlaybackPosition() {
+        if (!this.#streamingAnalytics)
+            return;
+        if (this.#isLive) {
+            this.#updateDvrWindow();
+        }
+        else {
+            this.#streamingAnalytics.startFromPosition(this.#currentTimeInMilliseconds);
+        }
+    }
+    #updateDvrWindow() {
+        if (!this.#streamingAnalytics)
+            return;
+        const { start, end } = this.integration.seekRange;
+        if (start === undefined || end === undefined)
+            return;
+        const dvrWindowLengthMs = (end - start) * 1000;
+        const currentTime = this.integration.currentTime;
+        const dvrWindowOffsetMs = (end - currentTime) * 1000;
+        this.#streamingAnalytics.setDvrWindowLength(dvrWindowLengthMs);
+        this.#streamingAnalytics.startFromDvrWindowOffset(dvrWindowOffsetMs);
+    }
+    get #isLive() {
+        return this.integration.source?.playbackMode === PlaybackMode.LIVE;
+    }
+    get #content() {
+        return this.integration.content;
+    }
+    get #duration() {
+        const content = this.#content;
+        return Math.floor(content?.duration === undefined ? this.integration.duration * 1000 : content.duration * 1000);
+    }
+    get #currentTimeInMilliseconds() {
+        if (this.#isLive) {
+            return this.integration.wallClockTime * 1000;
+        }
+        return this.integration.currentTime * 1000;
+    }
+    #determineContentMediaType() {
+        // biome-ignore lint/style/noNonNullAssertion: #analytics is guaranteed to exist when this method is called
+        const ContentType = this.#analytics.StreamingAnalytics.ContentMetadata.ContentType;
+        if (this.#isLive) {
+            return ContentType.LIVE;
+        }
+        // Content is longer than 600000 ms => 600 seconds => 10 minutes
+        if (this.#duration >= 600000) {
+            return ContentType.LONG_FORM_ON_DEMAND;
+        }
+        return ContentType.SHORT_FORM_ON_DEMAND;
+    }
+    #determineAdMediaType(adBreakName) {
+        const AdvertisementType = 
+        // biome-ignore lint/style/noNonNullAssertion: #analytics is guaranteed to exist when this method is called
+        this.#analytics.StreamingAnalytics.AdvertisementMetadata.AdvertisementType;
+        if (this.#isLive) {
+            return AdvertisementType.LIVE;
+        }
+        if (adBreakName === 'preroll') {
+            return AdvertisementType.ON_DEMAND_PRE_ROLL;
+        }
+        if (adBreakName === 'postroll') {
+            return AdvertisementType.ON_DEMAND_POST_ROLL;
+        }
+        return AdvertisementType.ON_DEMAND_MID_ROLL;
+    }
+    onDestroy() {
+        if (this.#streamingAnalytics && this.contentStarted) {
+            this.#streamingAnalytics.notifyEnd();
+        }
+    }
+}

package/dist/comscore/comscore-metadata.d.ts

@@ -0,0 +1,15 @@
+import { type IntegrationElement } from '@glomex/integration-web-component';
+import type { Analytics, ContentMetadataInstance } from './comscore-types.js';
+export interface ContentMetadataConfig {
+    integration: IntegrationElement;
+    publisherName: string;
+}
+/**
+ * Build Comscore content metadata from integration data.
+ * Sets up all the standard metadata fields based on the content and source information.
+ *
+ * @param analytics - The Comscore Analytics instance
+ * @param config - Configuration containing the integration element
+ * @returns The configured ContentMetadata instance
+ */
+export declare function buildContentMetadata(analytics: Analytics, config: ContentMetadataConfig): ContentMetadataInstance;

package/dist/comscore/comscore-metadata.js

@@ -0,0 +1,58 @@
+import { PlaybackMode } from '@glomex/integration-web-component';
+/**
+ * Build Comscore content metadata from integration data.
+ * Sets up all the standard metadata fields based on the content and source information.
+ *
+ * @param analytics - The Comscore Analytics instance
+ * @param config - Configuration containing the integration element
+ * @returns The configured ContentMetadata instance
+ */
+export function buildContentMetadata(analytics, config) {
+    const { integration } = config;
+    const contentMetadata = new analytics.StreamingAnalytics.ContentMetadata();
+    const content = integration.content;
+    const source = integration.source;
+    const isLive = source?.playbackMode === PlaybackMode.LIVE;
+    const contentId = content?.additionalIds?.originId || content?.id || '';
+    const mediaId = isLive ? contentId : source?.id || contentId;
+    const livestreamId = isLive ? contentId : content?.liveOnDemandChannel?.id;
+    const programId = content?.show?.id ||
+        content?.competition?.id ||
+        content?.compilation?.id ||
+        content?.additionalIds?.originId ||
+        content?.id;
+    const programTitle = content?.show?.name ||
+        content?.competition?.name ||
+        content?.compilation?.name ||
+        content?.title;
+    const duration = Math.floor(content?.duration === undefined ? integration.duration * 1000 : content.duration * 1000);
+    contentMetadata.setUniqueId(isLive ? livestreamId || mediaId : mediaId);
+    contentMetadata.setLength(isLive ? 0 : duration);
+    if (!isLive && programTitle) {
+        contentMetadata.setProgramTitle(programTitle);
+    }
+    if (isLive) {
+        contentMetadata.setProgramId('1');
+    }
+    else if (programId) {
+        contentMetadata.setProgramId(programId);
+    }
+    if (!isLive && content?.title) {
+        contentMetadata.setEpisodeTitle(content.title);
+    }
+    if (!isLive && content?.show?.seasonNumber) {
+        contentMetadata.setEpisodeSeasonNumber(String(content.show.seasonNumber));
+    }
+    if (!isLive && content?.show?.episodeNumber) {
+        contentMetadata.setEpisodeNumber(String(content.show.episodeNumber));
+    }
+    if (!isLive && content?.additionalIds?.externalId) {
+        contentMetadata.setEpisodeId(content.additionalIds.externalId);
+    }
+    if (content?.channel?.name) {
+        contentMetadata.setStationTitle(content.channel.name);
+    }
+    contentMetadata.setPublisherName(config.publisherName);
+    contentMetadata.classifyAsCompleteEpisode(!isLive);
+    return contentMetadata;
+}

package/dist/comscore/comscore-sdk-loader.d.ts

@@ -0,0 +1,12 @@
+import type { Analytics } from './comscore-types.js';
+export interface InitializeComscoreOptions {
+    publisherId: string;
+    debug?: boolean;
+}
+/**
+ * Initialize Comscore analytics SDK.
+ * Dynamically imports the SDK and configures it with the provided publisher ID.
+ *
+ * @returns The Comscore Analytics instance, or undefined if initialization failed
+ */
+export declare function initializeComscore(options: InitializeComscoreOptions): Promise<Analytics | undefined>;

package/dist/comscore/comscore-sdk-loader.js

@@ -0,0 +1,35 @@
+/**
+ * Get the Comscore namespace from globalThis
+ */
+function getComscoreNamespace() {
+    return globalThis.ns_;
+}
+/**
+ * Initialize Comscore analytics SDK.
+ * Dynamically imports the SDK and configures it with the provided publisher ID.
+ *
+ * @returns The Comscore Analytics instance, or undefined if initialization failed
+ */
+export async function initializeComscore(options) {
+    const { publisherId, debug } = options;
+    // Dynamic import - bundler will handle code splitting
+    const importedAnalytics = (await import('@comscore/analytics'));
+    const ns = getComscoreNamespace();
+    const analytics = importedAnalytics || ns?.analytics;
+    if (!analytics) {
+        throw new Error('Comscore analytics not available after dynamic import');
+    }
+    // Ensure to reuse existing partner configuration
+    if (analytics.configuration.getPartnerConfigurations().length === 0) {
+        analytics.PlatformApi.setPlatformApi(analytics.PlatformApi.PlatformApis.WebBrowser);
+        const publisherConfig = new analytics.configuration.PublisherConfiguration({
+            publisherId
+        });
+        analytics.configuration.addClient(publisherConfig);
+        if (debug) {
+            analytics.configuration.enableImplementationValidationMode();
+        }
+        analytics.start();
+    }
+    return analytics;
+}

package/dist/comscore/comscore-types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Comscore Streaming Analytics TypeScript Definitions
+ * Types imported from @comscore/analytics package
+ * @see https://www.npmjs.com/package/@comscore/analytics
+ */
+export type Analytics = typeof import('@comscore/analytics')['default'];
+export type StreamingAnalyticsInstance = InstanceType<Analytics['StreamingAnalytics']>;
+export type ContentMetadataInstance = InstanceType<Analytics['StreamingAnalytics']['ContentMetadata']>;
+export interface ComscoreNamespace {
+    analytics: Analytics;
+}

package/dist/comscore/comscore-types.js

@@ -0,0 +1,6 @@
+/**
+ * Comscore Streaming Analytics TypeScript Definitions
+ * Types imported from @comscore/analytics package
+ * @see https://www.npmjs.com/package/@comscore/analytics
+ */
+export {};

package/dist/comscore/index.d.ts

@@ -0,0 +1,72 @@
+import { type IntegrationElement } from '@glomex/integration-web-component';
+import type { ContentMetadataInstance } from './comscore-types.js';
+/**
+ * Configuration options for Comscore analytics integration
+ */
+export interface ComscoreOptions {
+    /**
+     * Comscore publisher ID
+     * @example 'abc123'
+     */
+    publisherId: string;
+    /**
+     * Publisher name (e.g. Joyn)
+     * @example 'Joyn'
+     */
+    publisherName: string;
+    /**
+     * Enable debug mode for implementation validation
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Optional callback for warning messages. If not provided, warnings are logged to console.
+     */
+    warnCallback?: (error: Error) => void;
+    /**
+     * Configure content metadata before tracking.
+     * Called once per content when playback starts.
+     * Use `integration.content` to access content data.
+     *
+     * @param metadata - The pre-configured Comscore content metadata instance with default values
+     * @returns The metadata instance to use for tracking, or `null`/`undefined` to skip tracking this content
+     *
+     * @example
+     * ```ts
+     * configureContentMetadata: (metadata) => {
+     *   metadata.setGenreName('Drama');
+     *   return metadata;
+     * }
+     * ```
+     */
+    configureContentMetadata?: (metadata: ContentMetadataInstance) => ContentMetadataInstance | null | undefined;
+}
+/**
+ * Connects Comscore Streaming Analytics to a turbo player integration.
+ *
+ * This function sets up automatic tracking of playback events including:
+ * - Content playback (play, pause, seek, buffer, end)
+ * - Advertisement playback (pre-roll, mid-roll, post-roll)
+ * - DVR window tracking for live content
+ *
+ * Tracking only occurs when the user has given consent (IAB TCF purpose 1 and vendor 77).
+ *
+ * @param integration - The turbo player integration element
+ * @param options - Comscore configuration options
+ * @returns A cleanup function to disconnect the analytics integration
+ *
+ * @example
+ * ```ts
+ * import { connectToComscore } from '@glomex/integration-analytics/comscore';
+ *
+ * const disconnect = connectToComscore(integration, {
+ *   publisherId: 'your-publisher-id',
+ *   publisherName: 'Your Publisher Name',
+ *   debug: true
+ * });
+ *
+ * // When done, call disconnect to clean up
+ * disconnect();
+ * ```
+ */
+export declare const connectToComscore: (integration: IntegrationElement, options: ComscoreOptions) => (() => void);

package/dist/comscore/index.js

@@ -0,0 +1,101 @@
+import { IntegrationEvent } from '@glomex/integration-web-component';
+import { ComscoreEventMapper } from './comscore-event-mapper.js';
+import { buildContentMetadata } from './comscore-metadata.js';
+import { initializeComscore } from './comscore-sdk-loader.js';
+/** IAB TCF vendor ID for Comscore */
+const IAB_VENDOR_COMSCORE = '77';
+/**
+ * Connects Comscore Streaming Analytics to a turbo player integration.
+ *
+ * This function sets up automatic tracking of playback events including:
+ * - Content playback (play, pause, seek, buffer, end)
+ * - Advertisement playback (pre-roll, mid-roll, post-roll)
+ * - DVR window tracking for live content
+ *
+ * Tracking only occurs when the user has given consent (IAB TCF purpose 1 and vendor 77).
+ *
+ * @param integration - The turbo player integration element
+ * @param options - Comscore configuration options
+ * @returns A cleanup function to disconnect the analytics integration
+ *
+ * @example
+ * ```ts
+ * import { connectToComscore } from '@glomex/integration-analytics/comscore';
+ *
+ * const disconnect = connectToComscore(integration, {
+ *   publisherId: 'your-publisher-id',
+ *   publisherName: 'Your Publisher Name',
+ *   debug: true
+ * });
+ *
+ * // When done, call disconnect to clean up
+ * disconnect();
+ * ```
+ */
+export const connectToComscore = (integration, options) => {
+    const { publisherId, debug, warnCallback, configureContentMetadata } = options;
+    let initializationPromise;
+    let currentMapper;
+    const onWarn = (error) => {
+        if (warnCallback) {
+            warnCallback(error);
+        }
+        else {
+            setTimeout(() => {
+                // biome-ignore lint: suspicious/noConsole
+                console.error(error);
+            }, 0);
+        }
+    };
+    const initializeComscoreSdk = () => {
+        if (initializationPromise)
+            return initializationPromise;
+        initializationPromise = initializeComscore({ publisherId, debug }).catch((error) => {
+            onWarn(error instanceof Error ? error : new Error(String(error)));
+            return undefined;
+        });
+        return initializationPromise;
+    };
+    const hasConsent = () => {
+        const hasPurpose1Consent = Boolean(integration.consent?.purposeConsents?.['1']);
+        const hasVendorConsent = Boolean(integration.consent?.vendorConsents?.[IAB_VENDOR_COMSCORE]);
+        return hasPurpose1Consent && hasVendorConsent;
+    };
+    const onContentSelect = () => {
+        if (currentMapper) {
+            currentMapper.destroy();
+            currentMapper = undefined;
+        }
+        if (!hasConsent())
+            return;
+        const { content } = integration;
+        if (!content)
+            return;
+        // Start initialization if not already done, but don't await - events will be queued
+        const sdkReadyPromise = initializeComscoreSdk();
+        currentMapper = new ComscoreEventMapper(integration, sdkReadyPromise.then((analytics) => {
+            if (!analytics)
+                return undefined;
+            let contentMetadata = buildContentMetadata(analytics, {
+                integration,
+                publisherName: options.publisherName
+            });
+            if (configureContentMetadata) {
+                contentMetadata = configureContentMetadata(contentMetadata);
+            }
+            if (contentMetadata == null) {
+                return undefined;
+            }
+            return {
+                analytics,
+                contentMetadata
+            };
+        }), onWarn);
+    };
+    integration.addEventListener(IntegrationEvent.CONTENT_SELECT, onContentSelect);
+    return () => {
+        integration.removeEventListener(IntegrationEvent.CONTENT_SELECT, onContentSelect);
+        currentMapper?.destroy();
+        currentMapper = undefined;
+    };
+};

package/dist/nielsen/index.d.ts

@@ -0,0 +1,70 @@
+import { type IntegrationElement } from '@glomex/integration-web-component';
+export type { NielsenAdMetadata, NielsenAdMetadataBase, NielsenAdMetadataDE, NielsenContentMetadata, NielsenContentMetadataBase, NielsenContentMetadataDE } from './nielsen-types.js';
+import type { NielsenAdMetadata, NielsenAdMetadataBase, NielsenContentMetadata, NielsenContentMetadataBase } from './nielsen-types.js';
+/**
+ * Options for Nielsen provider
+ */
+export interface NielsenOptions {
+    /** Nielsen App ID */
+    appId: string;
+    /**
+     * Two-letter country code for loading the appropriate Nielsen data mapping.
+     * Country-specific metadata builders are used automatically.
+     * @example 'de' - Germany (uses AGF-specific custom variables)
+     */
+    country: string;
+    /** Enable Nielsen SDK debug mode */
+    debug?: boolean;
+    /** Optional callback for warning messages */
+    warnCallback?: (error: Error) => void;
+    /**
+     * Callback to extend or modify content metadata before tracking.
+     * Called once per content when playback starts.
+     * Use `integration.content` to access additional content data if needed.
+     *
+     * When `country` is specified, receives country-specific metadata as input.
+     * When `country` is not specified, receives base metadata.
+     *
+     * @param baseMetadata - Base metadata built from integration data containing `assetid`, `type`, `program`, `title`, and `length`
+     * @returns Extended metadata object with additional Nielsen-required fields, or `null`/`undefined` to skip tracking this content
+     *
+     * @example
+     * ```ts
+     * configureContentMetadata: (baseMetadata) => ({
+     *   ...baseMetadata,
+     *   program: 'My Program',
+     *   segB: 'category',
+     *   segC: 'subcategory'
+     * })
+     * ```
+     */
+    configureContentMetadata?: (baseMetadata: NielsenContentMetadataBase) => NielsenContentMetadata | null | undefined;
+    /**
+     * Callback to extend or modify ad metadata before tracking.
+     * Called on each linear ad impression (preroll, midroll, postroll).
+     * Use `integration.currentAd` to access additional ad data if needed.
+     *
+     * When `country` is specified, receives country-specific metadata as input.
+     * When `country` is not specified, receives base metadata.
+     *
+     * @param baseMetadata - Base metadata built from integration data containing `assetid` and `type` (preroll/midroll/postroll)
+     * @returns Extended metadata object with additional Nielsen-required fields
+     *
+     * @example
+     * ```ts
+     * configureAdMetadata: (baseMetadata) => ({
+     *   ...baseMetadata,
+     *   title: 'Ad Title'
+     * })
+     * ```
+     */
+    configureAdMetadata?: (baseMetadata: NielsenAdMetadataBase) => NielsenAdMetadata;
+}
+/**
+ * Connect to Nielsen tracking.
+ * Returns a cleanup function that should be called when tracking is no longer needed.
+ *
+ * Nielsen does not require consent checks and uses a synchronous stub pattern,
+ * so events can be sent immediately and are queued until the SDK loads.
+ */
+export declare const connectToNielsen: (integration: IntegrationElement, options: NielsenOptions) => (() => void);