conviva-connector-web

The Conviva connector provides a Conviva integration for THEOplayer.

Prerequisites

In order to use this connector, a THEOplayer build with a valid license is required. You can use your existing THEOplayer HTML5 SDK license or request yours via THEOportal.

For setting up a valid Conviva session, you must have access to a Conviva developer account with access to a debug or production key.

Installation

Install using your favorite package manager for Node (such as npm or yarn):

Install via npm

npm install @theoplayer/conviva-connector-web

Install via yarn

yarn add @theoplayer/conviva-connector-web

Usage

First you need to define the Conviva metadata and configuration:

    const convivaMetadata = {
        ['Conviva.assetName']: 'ASSET_NAME_GOES_HERE',
        ['Conviva.streamUrl']: 'CUSTOMER_STREAM_URL_GOES_HERE',
        ['Conviva.streamType']: 'STREAM_TYPE_GOES_HERE', // VOD or LIVE
        ['Conviva.applicationName']: 'APPLICATION_NAME_GOES_HERE',
        ['Conviva.viewerId']: 'VIEWER_ID_GOES_HERE'
    };

    const convivaConfig = {
        debug: false,
        gatewayUrl: 'CUSTOMER_GATEWAY_GOES_HERE',
        customerKey: 'CUSTOMER_KEY_GOES_HERE' // Can be a test or production key.
    };

Optionally, you can include device metadata in the ConvivaConfiguration object. Note that SCREEN_RESOLUTION_WIDTH, SCREEN_RESOLUTION_HEIGHT and SCREEN_RESOLUTION_SCALE_FACTOR are the only fields that Conviva will auto-collect on most web-based platforms.

const exampleDeviceMetadata: ConvivaDeviceMetadata = {
    [Constants.DeviceMetadata.BRAND]: "Samsung",
    [Constants.DeviceMetadata.MANUFACTURER]: "Samsung",
    [Constants.DeviceMetadata.MODEL]: "QE43Q64BAUXXN",
    [Constants.DeviceMetadata.TYPE]:  Constants.DeviceType.SMARTTV,
    [Constants.DeviceMetadata.VERSION]: "6.5.0",
    [Constants.DeviceMetadata.OS_NAME]: "Tizen",
    [Constants.DeviceMetadata.OS_VERSION]: "6.5.0",
    [Constants.DeviceMetadata.CATEGORY]: Constants.DeviceCategory.SAMSUNG_TV,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_WIDTH]: 3840,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_HEIGHT]: 2160,
    [Constants.DeviceMetadata.SCREEN_RESOLUTION_SCALE_FACTOR]: 1
}

convivaMetadata.deviceMetadata = exampleDeviceMetadata

Using these configs you can create the Conviva connector with THEOplayer.

• Add as a regular script:

<script type="text/javascript" src="path/to/conviva-connector.umd.js"></script>
<script type="text/javascript">
    const player = new THEOplayer.Player(element, configuration);
    const convivaIntegration = new THEOplayerConvivaConnector.ConvivaConnector(
            player,
            convivaMetadata,
            convivaConfig
    );
</script>

• Add as an ES2015 module:

<script type="module">
    import { ConvivaConnector } from "path/to/conviva-connector.esm.js";
    const player = new THEOplayer.Player(element, configuration);
    const convivaIntegration = new ConvivaConnector(player, convivaMetadata, convivaConfig);
</script>

The Conviva connector is now ready to start a session once THEOplayer starts playing a source.

Note that the convivaMetadata provided to the ConvivaConnector constructor is primarily used to pass on to the Conviva SDK's reportPlaybackRequested. If a source is set to the player after initializing the connector, you should always provide the corresponding metadata (again) through the connector's setContentInfo method.

player.source = exampleSource;
convivaIntegration.setContentInfo(exampleSourceMetadata);

Usage with Yospace connector

If you have a Yospace SSAI stream and want to also report ad related events to Conviva, you can use this connector in combination with the Yospace connector: @theoplayer/yospace-connector-web

After configuring the Yospace connector, can link it to the Conviva connector:

async function setupYospaceConnector(player) {
        const source = {
            sources: [
                {
                    src: "https://csm-e-sdk-validation.bln1.yospace.com/csm/extlive/yospace02,hlssample42.m3u8?yo.br=true&yo.av=4",
                    ssai: {
                        integration: "yospace"
                    }
                }
            ]
        };
        
        // Create the connectors.
        const yospace = new THEOplayerYospaceConnector.YospaceConnector(player);
        const conviva = new THEOplayerConvivaConnector.ConvivaConnector(player, convivaMetadata, convivaConfig);
    
        // Link ConvivaConnector with the YospaceConnector.
        conviva.connect(yospace);
        
        // Set the source.
        await yospace.setupYospaceSession(source);
    }