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 application specific information to Conviva.
Source specific metadata can be provided through the connector's setContentInfo
method.
This data does not carry over to the following sources and needs to be set after the sourcechange
event has been received.
player.source = exampleSource;
const onSourceChange = () => {
convivaIntegration.setContentInfo(exampleSourceMetadata);
}
player.addEventListener('sourcechange', onSourceChange);
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);
}