This article describes on how to integrate Conviva for Video Analytics and Ads Analytics offered as a connector with THEOplayer SDK.
Web SDK | Android SDK | iOS SDK | tvOS SDK | Android TV SDK | Chromecast SDK | Tizen | webOS |
---|---|---|---|---|---|---|---|
Yes | Yes | Yes | Unverified | Unverified | Unverified | Yes | Yes |
A THEOplayer build with a valid license is required. You can
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
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.
};
Using these configs you can create the Conviva connector with THEOplayer. Alternatives:
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>
<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.
player
) needs to be initialized before Conviva connector. convivaConfig
contains the details of the Conviva configuration and convivaMetadata
is used to add manually metadata associated to that content.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, you 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);
}
After setting up THEOplayer Unified Android SDK, in your module level build.gradle
file add THEOplayer Unified Android SDK Conviva Connector and the Conviva SDK:
implementation 'com.theoplayer.android-connector:conviva:+'
implementation 'com.conviva.sdk:conviva-core-sdk:4.0.23'
val theoplayerView: THEOplayerView
private fun setupConviva() {
val customerKey = "your_conviva_customer_key"
val gatewayUrl = "your_conviva_debug_gateway_url"
val settings = HashMap<String, Any>()
settings[ConvivaSdkConstants.GATEWAY_URL] = gatewayUrl
settings[ConvivaSdkConstants.LOG_LEVEL] = SystemSettings.LogLevel.DEBUG
convivaConnector = ConvivaConnector(applicationContext, theoplayerView.player, customerKey, settings)
convivaConnector?.setViewerId("viewer ID")
}
Whenever a new source is set on the player, follow it by setting the new asset name. For example:
theoplayerView.player.source = sourceDescription
convivaConnector?.setAssetName("BigBuckBunny with Google IMA ads")
To release listeners and resources, call destroy
whenever the Conviva Connector is no longer needed.
convivaConnector?.destroy()
After destroying a Conviva Connector instance, it can no longer be used. If needed, a new instance should be created.
https://github.com/THEOplayer/iOS-Connector
To support custom feature builds of THEOplayerSDK perform the following steps:
../../Helpers/TheoSPM/theoplayer-sdk-ios
in Finder and dragging it into the Project navigator of your Xcode project.THEOplayerSDK.xcframework
at ../../Helpers/TheoSPM/theoplayer-sdk-ios/THEOplayerSDK.xcframework
. (It is also possible to place your xcframework somewhere else. In that case make sure to update the Package.swift manifest inside your local override so that it points to your custom THEOplayer build)If Xcode complains about a missing xcframework
File
> Packages
> Reset Package Caches
from the menu bar. THEOplayerSDK.xcframework
inclusions that you manually installed before installing this THEOplayer-Connector-Conviva package.pod init
pod 'THEOplayer-Connector-Conviva'
pod install
, then open your .xcworkspace
file to see the project in Xcode.To support custom feature builds of THEOplayerSDK perform the following steps:
THEOplayerSDK-basic
pod by adding the following line to your projects Podfile: pod 'THEOplayerSDK-basic', :path => 'iOS-Connector/Helpers/TheoPod'
and make sure the path points to the TheoPod folder.Import the THEOplayerConnectorConviva
module
import THEOplayerConnectorConviva
Create a ConvivaConfiguration
that contains the info on how to connect to your Conviva endpoint:
let configuration = ConvivaConfiguration(
customerKey: "put your customer key here",
gatewayURL: " put your gateway URL here ",
logLevel: .LOGLEVEL_FUNC
)
Create a ConvivaConnector
that uses this configuration
and your THEOplayer
instance:
let connector = ConvivaConnector(
configuration: configuration,
player: yourTHEOplayer
)
Report the viewer's ID:
connector.report(viewerID: "John Doe")
For each asset that you play, set its name using:
connector.report(assetName: "Star Wars episode II")
Hold a reference to your connector. Once the connector is released from memory it will clean up itself and stop reporting to Conviva.