Conviva DPI Sensor Integration for Roku
Conviva DPI Sensor Installation
Low-code integration of Conviva DPI sensor enables automatic and semantic-less data collection, and tracks application specific events and state changes. For more details to help get started with DPI integration, see DPI Integration FAQs.
Follow the instructions to add Conviva libraries and configure the dependencies.
Add Code SDK
Download and add the library explicitly: Conviva Roku SceneGraph library.
Add ConvivaClient.brs into the task component that initiates video playback and initialize the library.
Initialize Top-level Objects
Initialize the top level ConvivaClient object:
ConvivaClient(settings)
settings.customerKey: String to identify specific customer account. Different keys shall be used for development / debug versus production environment. Find your keys on the account info page in Pulse.
The allowed parameters are:
settings.gatewayUrl: When set to true, Conviva stops collecting video content errors. By default, this value is set to false and Conviva collects errors.
Sample code illustrating initialization with/without debug:
settings = {}
'Add the following line for Touchstone during development and test only.
settings.gatewayUrl = TOUCHSTONE_SERVICE_URL
'TEST_CUSTOMER_KEY is the key provided to you by Conviva.
settings.customerKey = TEST_CUSTOMER_KEY
conviva = ConvivaClient(settings)
'For production include PROD_CUSTOMER_KEY only, gatewayUrl is set by default.
settings.customerKey = PROD_CUSTOMER_KEY
'To initialize DPI sensor, by default the enableEco is set to false
settings.enableEco = true
settings.appId = "roku-eco"
conviva = ConvivaClient(settings)
gatewayUrl for your production release. The Conviva library provides the default values for production.APIs: Report Events to DPI Sensor
Set User ID (Viewer ID)
conviva.setUserId("<replace_with_userId>")
Report Application / Channel Load Time
channelInfo =
{
"channel_load_start": <load_start_epoch_timestamp_in_milliseconds>, ‘accepted timestamp types are string, float, integer
"channel_load_end": <load_end_epoch_timestamp_in_milliseconds> ‘accepted timestamp types are string, float, integer
}
conviva.setChannelInfo(channelInfo)
Report Screen View
To track in-app screen navigations.
screenEventDetails =
{
"name" : "Home Screen", ‘Name of the screen to uniquely identify
"screen_load_start": <load_start_epoch_timestamp_in_milliseconds>, ‘accepted timestamp types are string, float, integer
"screen_load_end": <load_end_epoch_timestamp_in_milliseconds> ‘accepted timestamp types are string, float, integer
}
conviva.trackScreenView (screenEventDetails)
Custom Event Tracking
To track application-specific events and state changes. Use trackCustomEvent() API to track all kinds of events. This API provides two fields to describe any tracked events.
name(Mandatory): Name of the custom event.data: Any type of data in {"key": "value"} pairs in roAssociativeArray format.
The following example shows the implementation of the 'Click/Select' event listener to any UI component.
customEvent =
{
"identifier1": "test",
"identifier2": 1,
"identifier3": true
}
conviva.trackCustomEvent(customEventName, customEvent)
Button Click Tracking
To track when user clicks on actionable buttons on channel.
clickEventDetails =
{
elementType: "testElementType",
elementId: "testElementId",
elementName: "testElementName",
elementClasses: "testElementClasses",
elementText: "testElementText",
elementValue: "testElementValue"
}
conviva.trackClick(clickEventDetails)
Error/Exception Tracking
To track when application encounters exceptions during runtime.
appErrorEventDetails =
{
message: "testMessage",
threadName: "testThreadName",
threadId: 4,
stackTrace: "testStackTrace",
causeStackTrace: "testCauseStackTrace",
lineNumber: 14,
className: "testClassName",
exceptionName: "testExceptionName",
isFatal: true,
lineColumn: 20,
fileName:"testFileName"
}
conviva.trackAppError(appErrorEventDetails)
Report Network Requests
networkRequestDetails =
{
"targetUrl":"https://<api.example.com/accounts.login>",
"method": "POST",
"queryParameters":"xyz",
"responseStatusCode":200,
"responseStatusText":"ok",
"rqh": { ‘ Request headers
"User-Agent": "MyApp/1.0",
"Authorization": "Bearer myToken123"
},
"rqb": { ‘Request Body
"field1": "value1",
"field2":
{
"loginMode": "nestedValueA",
"nestedFieldB": "nestedValueB"
}
},
"rsh": { ‘Response Headers
"Content-Type": "application/json",
"X-RateLimit-Remaining": "50"
},
"rsb": { ‘Response Body
"errorMessage": "Hello",
"apiVersion": "1.0.0",
"errorCode": 500,
"statusCode":200,
"fieldB": "dataA",
"fieldA": {
"nestedFieldX": "nestedDataX",
"nestedFieldY": "nestedDataY"
}
},
"requestTimestamp": 123456,
"responseTimestamp": 123457
}
conviva.trackNetworkRequest(networkRequestDetails)
Set/Unset Custom Tags
To report your application specific data.
Use setCustomTags() API to set all kinds of tags {"key":"value"} pairs. This API provides 1 argument that accepts data in JSON format to describe the tags.
The following example shows the implementation of setting custom tags. In this example we have 5 different tags test_id_1, id, id1, id2, and id3.
tags = {
"test1_id_1":"test_val_1",
"id":"val",
"id1":"val1",
"id2":"val2",
"id3":"val3"
}
conviva.setCustomTags(tags)
Use unsetCustomTags() API to unset or remove that were already set. This API provides one argument to describe an array of tag keys to unset.
The following example shows the implementation of unset or remove custom tags.
tag_keys = ["test1_id_1","id2"]
conviva.unsetCustomTags(tag_keys)
Conviva VSI Sensor Integration for Roku
Follow these instructions to complete the Conviva VSI Sensor integration on Roku players.
Step 1: Install Conviva Library
Developer Steps
Step 2: Configure Metadata
Developers Steps
Step 3: Report Events and Metadata
Developer Steps
Step 4: Report Events and MetadataIntegrate Video Players
Developer Steps
Step 5: Handle User ActionsUse Conviva methods to report custom events. Developer Steps
Step 6: Clean Up Session
Developer Steps
|
Prerequisites
Obtain your account's CUSTOMER_KEYs.**Conviva provides a test account and a production account for Test and Production environments, respectively. You can find your CUSTOMER_KEY here: Pulse - Account Info. Ask your Conviva representative for assistance if you have problems accessing it.
Pass the gatewayUrl parameter to init() method of Conviva SDK. The gatewayUrl is specific for your account and shall ONLY be used for tests, never for production deployment.
Sample gatewayUrl for Testing:
https://<*customer_key*>.ts-testonly.conviva.com
IMPORTANT: If there's any doubt on how to set the gateway URL, consult your Conviva representative - this is a critical parameter. For production, Conviva library uses the automatically-assigned gatewayUrl.
Use Touchstone 2.0 in Pulse to perform self-validation and debugging of video sensor integration
For Conviva JavaScript Sensor Integration, you can use any custom gateway URL with a proxy service setup. This is applicable for JavaScript version 4.7.13 onwards.
Plan your metadata
Conviva supports Pre-defined, Device, and Custom metadata. Work with your project team to determine the need to collect any custom metadata. It's also recommended to work with your Conviva representative to create your metadata plan prior to integration.
Integration Summary
Roku Scene Graph Integration
For API call details, refer to Roku Integration API List.
Integration Summary Steps
Install the library and add dependencies.
Initialize the
ConvivaClientobject using your CUSTOMER_KEY.Using an instance of
ConvivaClientas aconvivaobject to report video or ad related events.
Implement the metadata by following the instructions to use the pre-defined keys, as well as custom metadata if defined.
Conviva library autocollects Roku device metadata.
Implement the
conviva.monitorVideoNode(video, contentInfo)method to report playback attempt request along with metadata (content, workflow, audience, and other relevant metadata) and the VideoNode object.Use the
conviva.endMonitoring()method to report the of end playback.
Implement advanced metadata and events as prescribed by the corresponding specification.
Monitor ads for your ads player (if available), by passing the ad loader instance to Conviva. If following custom ad integration guidelines, implement ad metadata, events and metric reporting as prescribed by the corresponding specification.
Conviva library autocollects Roku Network Metrics.
- Clean Up
Call
conviva.endMonitoring()API to gracefully end the monitoring session associated with current video asset playback.
Test and Validate
After integration, perform a sanity check following the test cases in the Stream Sensor Sanity Test Plans spreadsheet. For the full validation test, use the test cases in the Stream Sensor Full Test Plans spreadsheet.
Use Touchstone in Pulse to perform self-validation and debugging of video sensor integration.
https://.ts-testonly.conviva.com
- Done! Analyse your data in Pulse and improve your viewer experience - let's make video experience better!
Sample Application
The sample application illustrating Conviva integration example can be found along with the library, in the same .zip file. Please refer to the next step below for details.
1. Install Conviva Library
Add Conviva Libraries and Configure Dependencies
|
Add core SDK |
Download and add the library explicitly: Conviva Roku SceneGraph library Add |
|---|---|
|
Add dependencies for Ad SDKs |
Refer to Integrate Ad Managers for the details of ad manager integration. |
|
Initialize the top level object |
Initialize the top level ConvivaClient object:
The allowed parameters are:- No need to set gatewayUrl settings for your production release explicitly. The Conviva sensor has the right default value.
- No need to set this parameter to false explicitly. The Conviva sensor has the right default value. Sample code illustrating initialization with/without debug: IMPORTANT: No need to set Expected Errors Due to Dual Stack IPv4/v6 Network SupportWhen the Conviva sensor is initialized with production settings, the SDK sends a single request to the endpoints below:
Sending both requests enables correlation of IPv4 and IPv6 addresses in dual-stack networks. If only IPv4 or IPv6 addressing is used (single-stack networking), it is expected that one request will fail. All the following requests will be sent to the endpoint below which supports both IPv4 and IPv6:
|
|---|
2. Configure Metadata
Metadata enables analysis of your data using different dimensions, for example, content, audience, device, workflow, player, and operating system.
Conviva categorizes metadata tags into three buckets (Predefined, Device, Custom).
Pre-defined Video and Content Metadata
Conviva defines the constants or fixed string keys for commonly used metadata. These metadata keys provide critical information about video and ad content, versioning, workflow. The full list of pre-defined metadata is provided further down the page.
IMPORTANT: Conviva library autocollects certain fields to simplify the integration. Please refer to the particular module specification for details.
The table below provides the pre-defined metadata fields.
IMPORTANT: To assign content category labels, such as Audio, Trailer, Tile Play, or Short Video, use the c3.cm.categoryType pre-defined content metadata constant.
| Key | Type | Implementation Note |
|---|---|---|
| assetName | roString | Autocollected. Asset Name is autocollected from the video node's contentNode parameter. For video content , use unique name for each stream/video asset. Values are up to your choice, but a human-readable text prefixed with the unique video ID works best in most Conviva sensors. This provides for clarity in reports and makes most popular content easily identifiable. Pattern: [videoID] Video Title
The following are typical patterns for VOD (movies and episodic content) and Live streams:
|
| isLive | roBoolean | Denotes whether the content is video on-demand or a live stream. Affects the computation and availability of the Conviva metrics.
|
| playerName | roString | A string value used to distinguish video players (applications). Simple values that are unique across all of your integrated platforms work best here. If the same player used across multiple platforms, e.g., Tizen, LG TV, WEB, give separate names for each application / platofrm: e.g., "JS Tizen", "JS LGTV", "JS WEB". Do not include the build or version number in this property. The intention is to have a simple way of differentiating data from different players / platforms. |
| viewerId | string | Required for Viewers Module. A unique identifier to distinguish individual viewers or devices through Conviva's Viewers Module. The value shall be unique abstract user's identifier. If user is anonymous, do not set any value for this tag. |
| streamUrl | roString |
Autocollected. The URL from which the video is initially loaded. The streamURL is the manifest URL of the video stream.
The Conviva backend config server attempts to map a portion of StreamURL into a CDN name. For example: In the URL The URL values reported in the streamURL are case insensitive. The streamURLs with either all capitals or all lower case are acceptable. |
| defaultReportingResource | roString |
This value specifies the video server or CDN name from where the streaming resource is played. Set this field when the video server resource cannot be inferred from the streamURL.
For example, if the streamURL is The DEFAULT_Resource value is case sensitive. If the resource name is initially reported as AKAMAI (uppercase) and subsequently modified in the app to akamai (lowercase), it is necessary to inform Conviva about the change because both need to be mapped in the Conviva backend configuration server to ensure that both point to the same CDN name (AKAMAI).
|
| contentLength | roInteger, roInt | Autocollected. The contentLength is set autocollected by the Conviva library using the Roku APIs. Duration of the video content, in seconds. |
| encodedFramerate | roInteger, roInt | Encoded frame rate of the video stream in frames per second. |
| streamFormat | roString | Autocollected. The Stream Format is autocollected, using the Stream Url field of the Roku streaminfo event. If you know the stream format before session creation, you can pass it as metadata. |
| customMetadata | roAssociativeArray | Refer to section custom metadata section for implementation details. |
| Player Framework Name | roString | Autocollected. |
| Player Framework Version | roString | Autocollected. |
| "c3.app.version" | roString | Autocollected. The application build version is auto collected from manifest as "major.minor.build" version. Shall have the same value for both video and ads. |
| "c3.cm.contentType" | string | Advanced content delivery methods along with Live and VOD. Acceptable values: "Live", "Live-Linear", "DVR", "Catchup", "VOD". |
| "c3.cm.channel" | string | The channel on which the content is consumed.
Example: "ABC". |
| "c3.cm.brand" | string | The name of the brand to which the content belongs.
Examples: "ABC X", "ABC Y". |
| "c3.cm.affiliate" | string | Affiliate or MVPD name for TV Everywhere authenticated services.
Examples: "Xfinity", "Comcast". |
| "c3.cm.categoryType" | string |
Content business categories of interest. Use this constant to assign content category labels, such as Audio, Trailer, Tile Play, or Short Video. Examples: "Episodic", "Movies", "News", "Sports", "Events", "Informercials", "Shorts", "Promos", "Audio", "Tile Play", "Short Videos", "Trailer". |
| "c3.cm.name" | string | Name of CMS Provider.
Examples: "CMS", "ROVI", "TMS". |
| "c3.cm.id" | string | Unique asset identifier to query CMS system to gather additional asset metadata information for a specific asset.
Example: "003b094d-fc5c-3d5a-8ed0-301bf848291e". |
| "c3.cm.seriesName" | string | The name of Series. Set the value only if the metadata cannot be gathered from CMS System. Null if not applicable.
Examples: "Friends", "Null". |
| "c3.cm.seasonNumber" | string | The Season number. Set the value only if the details cannot be inferred from Asset Provider Server. Null if not applicable.
Examples: "1", "Null". |
| "c3.cm.showTitle" | string | The name of the Episode or Show Title. Set the value only if the details cannot be inferred from Asset Provider Server. Null if not applicable.
Examples: "The One with All the Cheesecakes", "Null". |
| "c3.cm.episodeNumber" | string | The Episode number. Set the value only if the details cannot be inferred from Asset Provider Server. Null if not applicable.
Examples: "3", "Null". |
| "c3.cm.genre" | string | The Primary content genre. Set the value only if the details cannot be inferred from Asset Provider Server. Null if not applicable.
Examples: "Drama", "Null". |
| "c3.cm.genreList" | string | The list of the applicable content genre. Set the values in a comma separated list only if the details cannot be inferred from Asset Provider Server. Null if not applicable.
Examples: "Drama, Crime, Political, Violence", "Null" |
| "c3.cm.utmTrackingUrl" | string | Provide the UTM parameters in the URL to track the effectiveness of the online marketing campaign across traffic sources and publishing media. Conviva uses CONTAINS logic to parse the individual UTM parameters from the URL provided, so either the full URL or just the UTM parameters is acceptable.
Example values: This tag is only applicable for web and mobile devices. |
Custom Metadata
Refer to App Manager->Setup Metadata page for your account to find the custom tags which shall be implemented.
Set custom tags in a similar way for either video or ads, by adding the tags to the
contentInfo / adInfo objects, by using appropriate ConvivaContentInfo instances.
c3.cm format, for instance, c3.cm.MyCustomTag1. Conviva reserved the c3.cm naming convention for the pre-defined or required metadata. Update/Amend Metadata
To update or amend pre-defined and custom tags for video, use conviva.setOrUpdateContentInfo(videoNode, contentInfo):
videoNode: VideoNode is responsible for content playback. It has a ContentNode field that is used as metadata for playback.contentInfo: roAssociativeArray object with parameters containing metadata changes for video content.
Please refer to the below example of setting both pre-defined and custom data using this method:
contentInfo = {}
contentInfo.assetName = "new asset name"
contentInfo.streamUrl = "http://newstreamurl.conviva.com/"
contentInfo.encodedFramerate = 24
contentInfo.defaultReportingResource = "AKAMAI"
contentInfo.playerName = "Roku"
contentInfo.contentLength = 120
contentInfo.isLive = true
contentInfo.viewerId = "<NEW VIEWER_ID>"
convivaTags = { }
convivaTags.SetModeCaseSensitive()
convivaTags["tag1"] = "value1A"
convivaTags["tag2"] = "value2A"
contentInfo.customMetadata = convivaTags
'Update the current session with metadata changes:
conviva.setOrUpdateContentInfo(videoNode, contentInfo)
IMPORTANT: Once you call a metadata update with correct values, your - user defined - data will have precedence over Conviva auto-detected values.
IMPORTANT: Please note that different Conviva products, such as Conviva VSI and Conviva Viewer Insights may have different logic with respect to handling updated values. Conviva recommends to update the metadata only when it is available and do not set any default values before the metadata is available.
Set Custom Player Framework Name and Version Metadata
To report custom player framework name and version, built on top of Roku's SceneGraph player. Follow the approach to collect custom player framework name and version:
- ContentInfo-based aproach The following example shows collecting framework name and version using Conviva ContentInfo. :
' Set framework info as part of contentInfo
contentInfo = {}
contentInfo.assetName = "Sample Video"
contentInfo.streamUrl = "http://example.com/video.m3u8"
contentInfo.playerFrameworkName = "CustomPlayer"
contentInfo.playerFrameworkVersion = "3.0.1"
conviva.monitorVideoNode(videoNode, contentInfo)
' Or update later
contentInfo = {}
contentInfo.playerFrameworkName = "UpdatedPlayer"
contentInfo.playerFrameworkVersion = "3.0.2"
conviva.setOrUpdateContentInfo(videoNode, contentInfo)
If the Framework Name (fw) and Framework Version (fwv) are set through ContentInfo, sensor overrides the default framework Roku Scene Graph with custom-defined name and includes the framework version in the heartbeat. Sensor transmits both fields, Framework Name (fw) and Framework Version (fwv), separately to enable independent reporting and filtering abilities.
Ad Events and Metadata
Pause/Resume Monitoring
We recommend you pause the monitoring session in situations when main content metrics could be mixed with monitoring data unrelated to the main video session, for example, when you have ad sessions. While an ad break is playing, to avoid ad data in the main video metrics, pause the main content monitoring by marking the start and end of ads in the video stream.
Use the following API's to pause and resume video monitoring:
setContentPauseMonitoring: Detach the video player from the monitoring session. Use when the currently attached video player is no longer relevant to the current monitoring session.setContentResumeMonitoring: Attach the video player from the monitoring session. Use when the currently attached video player becomes relevant to the current monitoring session.
conviva.setContentPauseMonitoring (videoNode)
conviva.setContentResumeMonitoring (videoNode)
3. Report Events and Metadata
Report Video Play Start
For each play, report playback attempt requests |
The keys / constants and expected values of the required metadata tags are defined in the Implement Metadata section below. Passing the In certain scenarios, the
These APIs help in capturing of events or errors during playback preparation. IMPORTANT: It is critical to make this API call correctly to monitor video experience - monitoring session created from this moment, and key metrics are captured based on this event. For example, if this call done late (say, when video starts rather than user clicks "play"), the Video Startup Time will be under-reported, Video Start Failures will be missed, etc. Please note that each video should be monitored separately - call this method for each new video played.
|
|---|
Report Ad Breaks to Video Session
IMPORTANT:The SDK autodetects the reportAdBreakStarted() / reportAdBreakEnded() events when Conviva Ad Modules are used.
Report Ad Break |
To handle ads, inform ConvivaClient object that ad break is started:
and when the ad break is ended:
The ideal event for invoking this method is on main video pause to clear stage for Ad playback. If the same video player instance is used for ads as for the video, call it when application requests the ads. Refer to the below sample code for illustration of how the reporting is done in these scenarios: On ad break ended |
|---|
Report Video Play End
For each play end, report playback ended |
|
|---|
4. Integrate Video Players
Conviva library auto-detect events from the video player and the most commonly used Ad managers / SDKs.
Report playback metrics |
Metrics monitored by Conviva Roku SceneGraph library (if applicable):
|
||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Implement Metadata |
To implement the metadata, refer to the above sections of common pre-defined, pre-defined video and custom metadata definitions for implementation details. |
Integrate Ad Managers
Conviva sensor is universal and player agnostic, therefore it can be used to integrate any Ad SDK using the programming language it's written for.
For ease and speed of integration, Conviva also provides plug-in modules for the most common Ad SDKs.
The modules allow to auto-detect events from the particular player / Ad SDK.
If instructions for your Ad SDK are not shown below, please follow the instructions for "Custom Ad Manager" integration, or contact your Conviva representative.
Google DAI
The Conviva Client automatically collects metrics and metadata from Google DAI ads SDK. Conviva client needs to be updated about the SDK instance created before calling start() API of Google DAI SDK's streamManager.
Integrate with Google DAI |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Implement Ad Metadata |
Conviva defines the set of the metadata keys to be used for metadata implementation. The implementation can be extended by adding custom tags - refer to Custom Metadata section. The Conviva DAI module automatically collects the available values for some of the metadata tags from the DAI SDK. Some of the tags though still have to be explicitly implemented. Please refer to the table below for the metadata tag definitions and details of the implementation. No action is required if implementation note says "Autocollected".
Pre-defined Ad Metadata:
During application backgrounding while an ad is playing, we recommend pausing the ad until the application is moved to the foreground. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Update Ad Metadata |
To update or amend custom tags for ad, use
Please refer to the below example of setting both pre-defined and custom data using this method: |
Known Google DAI Metric Limitations
| Metric Name | Impact | Condition | Issue |
|---|---|---|---|
| All metrics | Not reported | Slates | There are no events that report Slates ads playback in a server stitched stream. |
| Not reported | Non-linear Ads |
The IMA DAI Roku SDK doesn't support non-linear ads (overlays). Hence, it doesn't report one or all ad events. Also, there is no API to determine the linear or non-linear ad type. |
YoSpace Ad Management SDK
The Conviva client needs to be updated with yoSpace session instance as soon as it is available for usage. Usually it is available on receiving "PlayBackUrl" event from yoSpace SDK.
Integrate with YoSpace Ad Management SDK |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Implement Ad Metadata |
Conviva defines the set of the metadata keys to be used for metadata implementation. The implementation can be extended by adding custom tags - refer to Custom Metadata section. The Conviva YoSpace module automatically collects the available values for some of the metadata tags from the YoSpace SDK. Some of the tags though still have to be explicitly implemented. Please refer to the table below for the metadata tag definitions and details of the implementation. No action is required if implementation note says "Autocollected". There are 2 major versions of YoSpace SDK: 1.x and 3.x. Conviva supports both versions and the below table describes the implementation details.
Pre-defined Ad Metadata:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Update Ad Metadata |
To update or amend custom tags for ad, use
Please refer to the below example of setting both pre-defined and custom data using this method: |
Known YoSpace Metric Limitations
| Metric Name | Impact | Condition | Issue |
|---|---|---|---|
| Average Complete | Under reported | For live content | The time duration between AdvertStart and AdvertEnd events is less than the actual duration. |
| All metrics | Not reported | VPAID ads | There are no events that report VPAID ads playback in a server stitched stream. |
| Metric Name | Impact | Condition | Issue |
|---|---|---|---|
| c3.ad.position | Incorrectly reported | Post-roll ads | Currently, the API only determines whether ads are pre-roll or not, so all the other ads are reported as mid-roll. |
RAFX SSAI Adapter
The Conviva client automatically collects metrics and metadata from RAFX SSAI Adapters. The Conviva client needs to be updated with adapterInstance created using RAFX_SSAI call.
Integrate with RAFX SSAI Adapters |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Implement Ad Metadata |
Conviva defines the set of the metadata keys to be used for metadata implementation. The implementation can be extended by adding custom tags - refer to Custom Metadata section. The Conviva RAFX monitor automatically collects the available values for some of the metadata tags from the RAFX SSAI Adapter instance. Some of the tags though still have to be explicitly implemented. Please refer to the table below for the metadata tag definitions and details of the implementation. No action is required if implementation note says "Autocollected".
Pre-defined Ad Metadata:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Update Ad Metadata |
To update or amend custom tags for ad, use
Please refer to the below example of setting both pre-defined and custom data using this method: |
Known RAFX SSAI Metric Limitations
| Metric Name | Impact | Condition | Issue |
|---|---|---|---|
| All metrics | Not reported | VPAID ads | There are no events that report VPAID ads playback in a server stitched stream. |
| All metrics | Not reported | Ad and content Slates | There are no events that report slate playback in a server stitched stream. |
RAF (CSAI)
Currently, the RAF Roku ads framework only supports CSAI. The Conviva Client automatically collects metrics and metadata from ads that use RAF to render. The Conviva client needs to be updated with RAF instance as soon as it is created.
Integrate with RAF |
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Implement Ad Metadata |
Conviva defines the set of the metadata keys to be used for metadata implementation. The implementation can be extended by adding custom tags - refer to Custom Metadata section. The Conviva RAF monitor automatically collects the available values for some of the metadata tags from the RAF instance. Some of the tags though still have to be explicitly implemented. Please refer to the table below for the metadata tag definitions and details of the implementation. No action is required if implementation note says "Autocollected".
Pre-defined Ad Metadata:
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Update Ad Metadata |
To update or amend custom tags for ad, use
Please refer to the below example of setting both pre-defined and custom data using this method: |
Known RAF CSAI Metric Limitations
| Metric Name | Impact | Condition | Issue |
|---|---|---|---|
| Ad Startup Time (AST) | Not reported | All | Ad startup time is always zero. RAF does not expose any event that fires on ad load. |
| Ad Start Failures (ASF) | Not reported | All | RAF does not expose any error event that fires on ad load. Only ad playback failures are reported. |
| Ad Average Bitrate | Not reported | All | Current playing bitrate is not available from RAF. |
| Ad Attempts | Under-reported | Post-roll ads | RAF does not fire any events to allow monitoring of post-roll ads, which affects ad metrics. |
| Ad Impressions | Under-reported | Post-roll ads | RAF does not fire any events to allow monitoring of post-roll ads, which affects ad metrics. |
| Ad Concurrent Plays | Under-reported | Post-roll ads | RAF does not fire any events to allow monitoring of post-roll ads, which affects ad metrics. |
Custom Ad Manager
|
Report Ad Lifecycle Events |
In case of Custom Ad integration, Conviva does not detect any ad metrics or events. Implement the following ad events from your application to Conviva:
In the above methods, the parameter Implement it with respect to the requirements prescribed in the next step. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Implement Ad States |
When the main content and the ad share the same video node, the Conviva library automatically detects ad player states. When the main content and the ad do not share the same video node, for eg: Client Side Ad Insertion (CSAI), you must report the player states to Conviva using following API: Report Ad-video states to The accepted ad session player states are:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Report Ad Bitrate |
The Conviva library automatically detects the ad bitrate. In scenarios when the bitrate is not reported correctly during validation and testing - and you know the encoded bitrate before the ad monitoring session creation - use |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Implement Ad Metadata |
In case of Custom Ad integration, Conviva does not automatically collect ad metadata, except a few fields for common metadata pulled from the video session automatically. Implement the pre-defined common and ad metadata specified in the table below. Pre-defined Common Metadata:
Pre-defined Ad Metadata:
Update Ad Metadata: To update or amend custom tags for ad, use
Please refer to the below example of setting both pre-defined and custom data using this method: |
API Diagrams for Custom Ad Integration
Click an image to view the API call sequence:
**CSAI**
|
**SSAI**
|
|
|
5. Handle User Actions
Report Network Metrics
The Conviva library automatically detects the network connection type (Ethernet, WiFi, OTHER). The Conviva library fetches raw values returned by the DeviceInfo GetConnectionInfo() API Roku data.
The Connection Type can be updated after session creation, before the first video frame is rendered. The raw values are referenced based on the following Conviva mapping:
| Raw Value | Mapping |
|---|---|
| WiFiConnection | WiFi |
| WiredConnection | Ethernet |
| "" (Empty String) | OTHER |
Data Collection and User Preferences
By default, Conviva collects a set of data for better user analytics. However, the appropriate legal agreement with Conviva is required in order for Conviva to begin collecting data that would be considered PII, personal information, personal data or the like under applicable data privacy laws such as the General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA). Further below in this document, there is a description of the user-preference APIs that control data collection, including opt-out and deletion of data, in compliance with data privacy laws. These APIs are in addition to existing, offline processes for opt-out and data deletion requests.
Use these APIs to set the unique user identifiers, however actual collection of identifiers are contingent upon the customer's legal department providing written instructions to Conviva to begin collection. At the discretion of the customer's legal department, some or all of these identifiers may be collected. Conviva provides this flexibility to allow the customer to determine the precise identifiers to be collected.
The following tag is used to collect data:
rida: Roku Identifier for Advertising
This is available from library versions 3.4.5 and above. The value changes only when the user resets the advertising identifier, or enables and subsequently disables the Limit Ad Tracking option in the device's privacy setting.
Control Data Collection and Delete Collected Data
Set the user preference to collect or stop collecting PII data by specifying the corresponding tag to true or false. By default, Conviva assumes no restriction in collecting data.
|
Control the data collection |
|
|---|
Set the user preference to delete and stop collecting specific data items by specifying the corresponding tag. By default, Conviva assumes no deletion of data.
|
Delete collected data |
|
|---|
Report Custom Events
Player Insight is an advanced feature which allows you to track custom events that are not related to video rendering, but rather specific to your player's functionality. These events and their attributes are then tabulated in the Player Insight dashboard at Conviva VSI (Pulse). Contact your Conviva representative to enable Player Insights in Pulse.
You may send a custom Player Insight event that can be associated with a video playback using the following methods:
Report video-related events by the method conviva.reportContentPlayerEvent(videoNode, eventType as string, eventDetail as object):
eventType: Mandatory argument of event type of the video player event ofstringtype.eventDetail: Optional argument of event details of the video player event ofobjecttype.
|
Report video-related events |
|
|---|
Report app-level events by the method conviva.reportAppEvent(eventType as string, eventDetail as object):
eventType: Mandatory argument of event type of the app event ofstringtype.eventDetail: Optional argument of event details of the app event ofobjecttype.
|
Report app-level events |
|
|---|
Identifiers for Persistent Memory
The following value is set on the player initialization. Any time this value is cleared during application handling, such viewer logout/logins and background/foreground changes, Conviva recommends storing the value in persistent memory. If this identifier is not kept persistence, the unique devices and active devices/users values may be inflated:
ConvivaPersistent
6. Cleanup
Each monitoring session should be ended once the video stream it is attached to is no longer used. Depending on how the app/player is set up, this step may occur for a variety of reasons:
at the end of playback
during player deallocation
before transitioning to a different stream
when playback is abruptly ended (viewer clicks the Back button on the Roku remote)
In all cases, the ConvivaClient cannot automatically detect the end of monitoring. We recommend calling the conviva.endMonitoring() API to gracefully end the monitoring session associated with current video asset playback. To re-use the same videoNode for other video assets, playback should follow the monitorVideoNode API call.
conviva.endMonitoring(videoNode)
Advanced Use Cases
You can use specific APIs in the Conviva sensor for various advanced use cases, such as:
- Reporting program changes during live or live linear streaming
- Reporting once when playback does not recover
- Reporting a warning when playback is not impacted
- Handling user actions, such as user dialogues
To learn more about these advanced use cases, see here.
Limitations
| Metric Name | Impact | Conditions | Issue |
|---|---|---|---|
| Average Bitrate | Delay in reporting | HLS, SS and DASH | Bitrate reporting is delayed when player enters PLAY state. Conviva relies on Roku's streamingsegment event for bitrate calculations, but that event is sent late.in case of SS and Dash streams, the Conviva library waits until both audio and video segment bitrates are detected before calculating bitrate. |
| Incorrectly reported | HLS Demuxed Stream | Reports audio bitrate as 224, irrespective of supported bitrate. | |
| Concurrent Plays | Over-reported | HOME button press | If user presses HOME button during video playback, the video stops but Roku doesn't report the event, so the related Conviva monitoring session doesn't cleanup gracefully. *Concurrent Plays* will be over reported until the Conviva session times out. |
| Connection Induced Rebuffering Ratio (CIRR) | Over-reported | Pause/Error/Seek during low bandwidth | If a user performs any action on the video while it is buffering, the player does not report that action. This is an issue with Roku SDK. |
| Over-reported | User Seek | When the user seeks the video, the Roku Framework reports the Under Run event (seek end) only after the player has started reporting BUFFERING state. | |
| Over-reported | Instant replay | When the user seeks back using the instant replay button on remote, the Roku framework does not report seek, but only reports buffering as seen by the user. As a result, it is not detected by the Conviva library. | |
| Exits Before Video Start (EBVS) | Over-reported | DASH (Live/VOD) with unreachable video/audio segments | When the manifest and initialization segment are downloaded but the video/audio chunks fail to download, the player does not report an error and remains in buffering state. |
| Rebuffering Ratio (RR) | Over-reported | Pause during low bandwidth | If user pauses the video while it is buffering, the player reports PAUSE only after downloading the current chunk. |
| Over-reported | Mid-roll in Client Side Ad Insertion (CSAI) | Application needs to get back to stored pht (play head time) location (when main content monitoring was paused due to Mid-roll) after Mid-roll ends. This causes extra seeks events after Mid-roll end. | |
| Video Restart Time (VRT) | Over-reported | Buffering due to user seek | If user pauses the video while it is buffering, the player reports PAUSE only after downloading the current chunk. |
| Under-reported | User Seek | When the user seeks the video, the Roku Framework reports the seek end event - Under Run (seek end) - only after the player has started reporting BUFFERING state. | |
| Under-reported | Instant replay | When the user seeks back using the instant replay button on remote, the Roku framework does not report seek, but only reports buffering as seen by the user. As a result, it is not detected by the Conviva library. | |
| Over-reported | Mid-roll in Client Side Ad Insertion (CSAI) | Application needs to get back to stored pht (play head time) location (when main content monitoring was paused due to Mid-roll) after Mid-roll ends. This causes extra seeks events after Mid-roll end. | |
| Video Start Failures (VSF) | Under-reported | DASH (Live/VOD) with unreachable video/audio segments | When the manifest and initialization segment are downloaded but the video/audio chunks fail to download, the player does not report an error and remains in buffering state. |
| Under-reported | Unreachable video/audio segments | When content is served from multiple CDNs, the Roku SDK constantly switches CDNs and tries to fetch video from the available CDNs. This error is not reported and therefore, Video Start Failure is not detected. | |
| Video Playback Failures (VPF) | Under-reported | Unreachable video/audio segments | When content is served from multiple CDNs, the Roku SDK constantly switches CDNs and tries to fetch video from the available CDNs. This error is not reported and therefore, Video Playback Failure is not detected. |
| Average Frame Rate (FPS) | Incorrectly reported | All | Frame rate is collected but it is sometimes not accurate. This is because frequency of receiving decoderStats event (frame related data) from Roku is less than expected. |
| Metadata Name | Impact | Conditions | Issue |
|---|---|---|---|
| Device Name | Unable to distinguish between Roku 2 and 3 models | Roku 2/3 devices using roDeviceInfo.getModel() API |
getModel() API is returning values 4200X and 4200x instead of 4210X and 4230X respectively. This is intended design from Roku, as the 42xx models are identical in terms of hardware and performance. |
Self Validation
Upon completion of your integration, and before submission to Conviva QA team, developers should complete a comprehensive self-validation test pass of each Device Application.
Perform self-validation of video sensor integration using Touchstone in Pulse.
Conviva provides sample test cases with detailed steps and expected results.
Developers should be checking for both metric and metadata accuracy. Based on our experience, comprehensive self-validation can reduce your QE cycles, saving your costly project time.
Type to search. Results appear as you type.