This is an open-source project to enable the use of a third-party component (Conviva) with the Bitmovin Player iOS SDK.
This project is not part of a regular maintenance or update schedule and is updated once yearly to conform with the latest product versions. For additional update requests, please take a look at the guidance further below.
As an open-source project, we are pleased to accept any and all changes, updates and fixes from the community wishing to use this project. Please see CONTRIBUTING.md for more details on how to contribute.
If you come across a bug related to the player, please raise this through your support ticketing system.
Should you want some help updating this project (update, modify, fix or otherwise) and cant contribute for any reason, please raise your request to your bitmovin account team, who can discuss your request.
As an open-source project and not a core product offering, any request, issue or query related to this project is excluded from any SLA and Support terms that a customer might have with either Bitmovin or another third-party service provider or Company contributing to this project. Any and all updates are purely at the contributor's discretion.
Thank you for your contributions!
BitmovinConvivaAnalytics is available through CocoaPods. We depend on cocoapods version >= 1.9.0
To install it, simply add the following line to your Podfile:
pod 'BitmovinConvivaAnalytics', git: 'https://github.com/bitmovin/bitmovin-player-ios-analytics-conviva.git', tag: '3.5.0'
Then, in your command line run:
pod repo update
pod install
The 2.x and higher versions of the Conviva Analytics Integration depends on BitmovinPlayer
version >= 3.0.0
.
Note: BitmovinPlayer
version 2.x.x
is not supported anymore. Please upgrade to BitmovinPlayer
version 3.x.x
.
The following example shows how to setup the BitmovinConvivaAnalytics
:
do {
convivaAnalytics = try ConvivaAnalytics(player: bitmovinPlayer,
customerKey: "YOUR-CONVIVA-CUSTOMER-KEY")
} catch {
NSLog("[ Example ] ConvivaAnalytics initialization failed with error: \(error)")
}
At the end of the application's lifecycle, release the integration with:
convivaAnalytics.release()
Details about usage of BitmovinPlayer
can be found here.
If you want to override some content metadata attributes or track additional custom or standard tags you can do so by adding the following:
var metadata = BitmovinConvivaAnalytics.Metadata()
metadata.applicationName = "Bitmovin iOS Conviva integration example app"
metadata.viewerId = "awesomeViewerId"
metadata.additionalStandardTags = ["c3.cm.contentType": "VOD"]
metadata.custom = ["custom_tag": "value"]
metadata.additionalStandardTags = ["c3.cm.contentType": "VOD"]
metadata.imaSdkVerison = IMAAdsLoader.sdkVersion()
// …
// Initialize ConvivaAnalytics
// …
convivaAnalytics.updateContentMetadata(metadataOverrides: metadata)
Those values will be cleaned up after the session is closed.
In order to track server side ads you can use the methods provided in SsaiApi
which can be accessed via ConvivaAnalytics.ssai
.
The following example shows basic server side ad tracking:
convivaAnalytics.ssai.reportAdBreakStarted()
let adInfo = SsaiAdInfo(
title: "My ad title",
position: .preroll,
duration: 30
)
convivaAnalytics.ssai.reportAdStarted(adInfo)
...
convivaAnalytics.ssai.reportAdFinished()
convivaAnalytics.ssai.reportAdBreakFinished()
In addition to the metadata provided in the SsaiAdInfo
object at ad start, the following metadata will be auto collected from the main content metadata:
- CIS_SSDK_METADATA_STREAM_URL
- CIS_SSDK_METADATA_ASSET_NAME
- CIS_SSDK_METADATA_IS_LIVE
- CIS_SSDK_METADATA_DEFAULT_RESOURCE
- CIS_SSDK_METADATA_ENCODED_FRAMERATE
- streamType
- integrationVersion
- CIS_SSDK_METADATA_VIEWER_ID
- CIS_SSDK_METADATA_PLAYER_NAME
Metadata in the SsaiAdInfo
overwrites all auto collected metadata.
If your app stops playback when entering background conviva suggests to end the active session. Since the integration can't know if you app supports playback in background this can't be done automatically.
To end a session use:
convivaAnalytics.endSession()
Since the BitmovinPlayer
automatically pauses the video if no background playback is supported the session creation after
the app is in foreground again is handled automatically.
If you want to track UI related events such as full-screen state changes add the following after initializing the BMPBitmovinPlayerView
:
convivaAnalytics.playerView = bitmovinPlayerView
If you want to use the same player instance for multiple playback, just load a new source with player.load(…)
. The integration will close the active session.
player.load(…);
If your app needs additional setup steps which should be included in VST tracking, such as DRM token generation, before the Player
instance can be initialized,
the ConvivaAnalytics
can be initialized without a Player
instance. Once the Player
instance is created it can be attached.
- Create the
ConvivaAnalytics
instance with yourcustomerKey
and configuration.
do {
convivaAnalytics = try ConvivaAnalytics(
customerKey: "YOUR-CONVIVA-CUSTOMER-KEY"
)
} catch {
NSLog("[ Example ] ConvivaAnalytics initialization failed with error: \(error)")
}
- Conviva requires that the
assetName
is set at session initialization. Therefore ensure that you provide using theMetadataOverrides
before initializing the tracking session.
var metadata = MetadataOverrides()
metadata.assetName = "Your Asset Name"
convivaAnalytics.updateContentMetadata(
metadataOverrides: metadata
)
// Initialize tracking session
try convivaAnalytics.initializeSession()
- Once your
Player
instance is ready attach it to theConvivaAnalytics
instance.
// ... Additional setup steps
let player = PlayerFactory.createPlayer(...)
convivaAnalytics.attach(player: player)
- Tracking multiple sources within a Playlist, and related use cases, introduced in Player iOS SDK version
v3
are not supported.