Analytics

PRESTOplay includes ready-to-use plugins for popular analytics platforms, so you can start reporting quality-of-experience data without building your own event pipeline.

PRESTOplay includes analytics plugins for Conviva, NPAW, Broadpeak, and Mux Data.

Conviva analytics

The Conviva Core SDK isn’t published on the public NPM registry — Conviva provides it directly to customers. Add it to your page with a <script> tag:

<script src="path/to/conviva-core-sdk.js"></script>

Note

The Conviva plugin depends on the Conviva Core SDK, so the core SDK must be added to the page before the plugin. The minimum supported version for this integration is 4.0.3.

Import the PRESTOplay Conviva plugin:

import "@castlabs/prestoplay/cl.conviva";

Provide the Conviva configuration as part of the player configuration:

const playerConfig = {
  ...
  conviva: {
    customerKey: 'YOUR_CONVIVA_CUSTOMER_KEY',
    serviceUrl: 'https://company.testonly.conviva.com',
    viewerId: 'YOUR_USER_ID',
    enableAdInsights: false
  }
};

The Conviva sample shows the complete setup, including the asset name reported through source.name.

NPAW analytics

To get started with NPAW analytics, install the NPAW SDK and NPAW adapters.

Note

The legacy Youbora v6 SDK integration is still available. To use it instead, configure the player with a youbora key instead of npaw. It uses a separate YouboraConfiguration — its options aren’t identical to npaw’s.

npm install npaw-plugin@7.3.21
npm install npaw-plugin-adapters@7.3.21

Alternatively, to install the ES5 version of the NPAW library, run:

npm install npaw-plugin-es5@7.3.21
npm install npaw-plugin-adapters-es5s@7.3.21

Import the PRESTOplay Youbora plugin and the NPAW SDK:

import {clpp} from "@castlabs/prestoplay";
import "@castlabs/prestoplay/cl.mse";
import "@castlabs/prestoplay/cl.dash";
import "@castlabs/prestoplay/cl.youbora";
import * as NpawPlugin from 'npaw-plugin';
import * as NpawPluginAdapters from 'npaw-plugin-adapters';
window.NpawPlugin = NpawPlugin;
window.NpawPluginAdapters = NpawPluginAdapters;

For custom NPAW configuration, see the example below. For full details, see the NPAW documentation.

const playerConfig = {
  ...
  npaw: {
    accountCode: '<YOUR ACCOUNT CODE>',
    // ... other NPAW options
  }
};

You can also pass additional NPAW options per source, in the npaw key of the Player.open configuration.

The NPAW sample shows the complete setup with the NPAW v7 SDK, a custom errorFilter, and buttons that trigger recoverable and fatal errors.

Custom error and events reporting

To report custom errors or events as described in the NPAW documentation, access the underlying NPAW adapter:

const adapter = player.getPlugin(clpp.npaw.NpawPlugin.Id)
  .getAdapter();

// The adapter may be null if there is no active session.
if (adapter) {
  adapter.fireError(code, message);

  // Report an error and send a /stop event to stop the current session.
  adapter.fireFatalError(code, message);

  // Fire a custom event.
  adapter.fireEvent('eventName', dimensions, values, topLevelDimensions);
}

NPAW App Analytics

To use NPAW App Analytics with PRESTOplay, pass your NPAW plugin instance to PRESTOplay via setNpawPlugin. For App Analytics configuration details, see the NPAW documentation.

Import packages:

import {clpp} from "@castlabs/prestoplay";
import "@castlabs/prestoplay/cl.mse";
import "@castlabs/prestoplay/cl.dash";
import "@castlabs/prestoplay/cl.youbora";
import * as NpawPlugin from 'npaw-plugin';
import * as NpawPluginAdapters from 'npaw-plugin-adapters';
window.NpawPlugin = NpawPlugin;
window.NpawPluginAdapters = NpawPluginAdapters;

Use the NPAW plugin:

const player = new clpp.Player('video', {
  license: '<your_license_key>',
  viewerId: '<user_id>',
  npaw: {
    accountCode: '<YOUR ACCOUNT CODE>'
    // ... other NPAW options
  }
});

const appAnalyticsPlugin = new NpawPlugin('<YOUR ACCOUNT CODE>');

player.getPlugin(clpp.npaw.NpawPlugin.Id)
  .setNpawPlugin(appAnalyticsPlugin);

// Now you can start playback.
player.open({
  source: 'http://example.com/Manifest.mpd',
});

// Start session logging.
sessionsPlugin.appAnalytics.newSession();
// Fire a session custom tracking event.
sessionsPlugin.appAnalytics.fireEvent(
  'search', // Name of the event
  { // Dimensions
    terms: 'searchedTerms'
  },
  { // Values
    foundItems: 25
  });

Custom error filter

Use the npaw.errorFilter config option to prevent specific errors from being reported to the NPAW service, or to modify an error’s code, message, severity, or add extra metadata.

const player = new clpp.Player('video', {
  license: '<your_license_key>',
  npaw: {
    accountCode: '<YOUR ACCOUNT CODE>',
    errorFilter: error => {
      // Prevent error 3003 from being reported by returning null.
      if (error.code === 3003) {
        return null;
      }

      return {
        code: `${error.code}`,
        message: error.message,
        severity: error.severity,
        // metadata: { ... }, // Must be a serializable object.
      };
    },
    // ... other NPAW options
  }
});

Broadpeak analytics

Broadpeak SmartLib integrates with PRESTOplay via NPM and script tag. See the Broadpeak project setup documentation for Broadpeak-specific setup details.

Install with NPM

The minimum SmartLib version supported by this integration is 5.4.4-808048b.

Add the Broadpeak NPM registry:

npm config set @broadpeak:registry https://delivery-platform.broadpeak.tv/js/

Install SmartLib:

npm install @broadpeak/smartlib@5.4.4-808048b
npm install @broadpeak/smartlib-analytics@5.4.4-808048b

For other installation methods, see the Broadpeak project setup documentation. If your project needs a pre-transpiled bundle, use @broadpeak/smartlib-all-compatibility instead.

Import the SmartLib files and the PRESTOplay Broadpeak plugin:

import { SmartLib } from '@broadpeak/smartlib';
import '@broadpeak/smartlib-analytics';

import { clpp } from '@castlabs/prestoplay';
import '@castlabs/prestoplay/cl.broadpeak';

window.SmartLib = SmartLib; // Required by the PRESTOplay Broadpeak plugin.

Configuration

Add the Broadpeak configuration to your player. Set broadpeakDomainNames to a comma-separated list of the CDN domains that serve content through Broadpeak:

const playerConfig = {
  ...
  broadpeak: {
    broadpeakDomainNames: 'cdn.broadpeak.example,cdn2.broadpeak.example',
  },
};

Two special values are also accepted: '*' if every URL the player loads is served through Broadpeak, or '' if none are.

See BroadpeakConfiguration for all available configuration options.

Session options

Pass session options via broadpeak.sessionOptions, using StreamingSessionOptions constants as keys:

const playerConfig = {
  ...
  broadpeak: {
    broadpeakDomainNames: '',
    sessionOptions: {
      [StreamingSessionOptions.GDPR_PREFERENCE]:
        StreamingSessionOptions.GDPR_CLEAR,
      [StreamingSessionOptions.SESSION_KEEPALIVE_FREQUENCY]: 5000,
      [StreamingSessionOptions.SESSION_PRECACHE]: false, // Defaults to false when omitted.
    },
  },
};

See the Broadpeak documentation on session options for more information.

Broadpeak SSAI ads

The Broadpeak plugin integrates server-side ad insertion (SSAI) tracking into PRESTOplay, automatically handling ad tracking and emitting client-side events.

To enable this feature, extend your Broadpeak analytics installation with the Broadpeak ads module:

npm install @broadpeak/smartlib-ad@5.4.4-808048b

Then enable ad tracking in the Broadpeak config with adTracking: true and, optionally, pass adParameters to enable ad personalization. See the Broadpeak documentation for details about supported ad parameters.

player.open({
  source: {
    url: 'https://stream.broadpeak.io/...',
    type: clpp.Type.DASH,
  },
  broadpeak: {
    broadpeakDomainNames: '...',
    analyticsAddress: '...',
    adTracking: true,
    adParameters: {
      deviceType: 'desktop',
      userId: 'user123',
      contentGenre: 'sports',
      // ... any additional targeting parameters
    },
  },
});

For ad click-through to work properly, the default HTML5 video controls (<video controls>) must be hidden. This is typically not an issue, since most players use custom UI controls.

Broadpeak ad events

Ad metadata is surfaced through the standard ad events described in Advertising.

For SSAI ads in live streams, duration and ad count may not be known, especially for ads appearing on the live edge. In that case, IAd returns -1. Handle this case gracefully when rendering UI.

ad.getDuration() // -1 (unknown)
ad.getSequenceLength() // -1 (unknown)

Mux Data analytics

To use the Mux Data plugin with PRESTOplay, include the Mux Data library in your project via NPM.

Note

The minimum Mux Data SDK version recommended by this integration is 4.30.0.

npm i mux-embed@4.30.0

Import the PRESTOplay Mux Data plugin:

import "@castlabs/prestoplay/cl.muxdata";

Provide the Mux Data configuration as part of the player configuration:

const playerConfig = {
  ...
  muxdata: {
    envKey: '<your_env_key>'
  }
};

If you use a module loader to import the Mux SDK into your project, pass the Mux SDK as part of the config:

import mux from 'mux-embed';
...

const playerConfig = {
  ...,
  muxdata: {
    muxLib: mux, // The Mux Data core SDK.
    envKey: '<your_env_key>'
  }
}

You can also override or extend the configuration passed to the Mux library by setting muxOptionsOverride to an object containing valid Mux SDK options.

const playerConfig = {
  ...,
  muxdata: {
    muxLib: mux, // The Mux Data core SDK.
    envKey: '<your_env_key>',
    muxOptionsOverride: { // Valid Mux Data SDK options.
      debug: false,
      data: {
        player_name: 'MyPlatform-Web-Player',
        player_version: '2.3.7',
        viewer_user_id: 'new_id',
        page_type: 'watchpage',
        sub_property_id: 'some-id',
        // ...
      },
      automaticErrorTracking: false,
      respectDoNotTrack: false,
    }
  }
}

The Mux Data sample shows the complete setup, including muxOptionsOverride and a custom event helper.

Custom events

To report a custom event that isn’t covered by the plugin, access the underlying Mux Data SDK emit() method:

const mux = player.getPlugin('mux')

// Emit a heartbeat event with a custom value according to the docs.
mux.emit('hb', {
  custom_value: 'custom_value'
})

All mandatory Mux playback events are covered by the plugin and shouldn’t be emitted manually.

Next topic: Migration guide

Previous topic: Advertising