Conviva iOS/tvOS Sensor Integration

Conviva DPI Sensor Integration

Conviva Video Sensor Integration

Quick Integration

The quick integration page for iOS, tvOS, or visionOS contains the code snippets that you'll need at various stages of stream sensor integration and serves as a quick reference.

Follow these instructions to complete the Conviva Video Sensor integration on iOS players:

Prerequisites

Integration Summary

Click an image to view a summary of the API call sequence:**

iOS Custom Integration (SDK Only)	Conviva iOS Player Modules
Use for video players other than AVPlayer or Brightcove. Report all the playback metrics, such as bitrate, player states, seek, buffering, user actions, app backgrounding, and foregrounding. For API call details, refer to iOS Custom Integration API List.	Use for AVPlayer or Brightcove video players. Modules autocollect most playback metrics, such as bitrate, player states, seek, and buffering. For API call details, refer to iOS Module Integration API List.

Integration Summary

1. Install Conviva Library

• Install the library and add dependencies.

• Initialize the CISAnalytics object using your CUSTOMER_KEY.

• Create an instance of CISVideoAnalytics as a videoAnalytics object to report video related events.

• If your player has ads: Create an instance ofCISAdAnalytics as a adAnalytics object to report ad related events.

2. Configure Metadata **- Implement the metadata by following the instructions to use the pre-defined keys, as well as custom metadata, if applicable.

• Conviva sensor autocollects iOS/tvOS device metadata.

3. Report Events and Metadata **- Implement the videoAnalytics.reportPlaybackRequested(contentInfo) method to report playback attempt request along with metadata (content, workflow, audience, and other relevant metadata).

• Use the videoAnalytics.reportPlaybackEnded() method to report the of end playback.

4. Integrate Video Players

• Add Conviva module dependency for your video player (if available), and pass player instance to Conviva by calling videoAnalytics.setPlayer(playerInstance). If following custom integration guidelines, implement video events & metric reporting as prescribed by the corresponding specification.

• If following custom ad integration guidelines, implement ad metadata, events & metric reporting as prescribed by the corresponding specification.

5. Handle User Actions

• Conviva sensor autocollects iOS/tvOS Network Metrics.

• Manage Data Collection and User Preferences.

6. Clean Up Call 'release' methods to cleanup CISAnalytics, videoAnalytics, adAnalytics objects upon application exit.

Test and Validation

1. 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.

2. Use Touchstone 2.0 in Pulse to perform self-validation and debugging of video sensor integration.

3. Done! Analyse your data in Pulse and improve your viewer experience - let's make video experience better!

API Reference Documentation

The Conviva iOS SDK includes Reference Documentation for iOS SDK API. The documentation can be found here.

Sample Application

The sample application illustrating Conviva integration example can be found here.

1. Install Conviva Library

Add Conviva Libraries and Configure Dependencies

Migration instructions if upgrading from an older library version (pre 2.141.0)

Existing Customers can now upgrade to the latest release based on these options:

• With Advertising Identifier support.

• Without Advertising Identifier support.

Please upgrade to the latest release:

• Use ConvivaSDK 4.0.40, if you serve advertisements in your apps.

• Use ConvivaSDK 4.0.43, if you do not serve advertisements with your apps.

If you are migrating from an older library version (pre 2.141.0), please follow these steps:

1. Remove libiOSSdkCore.a from "Link Binary with Libraries" of Xcode.

2. Remove the following header files from your application:```javascript

#import "CISSystemInterfaceProtocol.h" #import "CISSystemFactoryProtocol.h" #import "CISSystemSettings.h" #import "CISClientSettingProtocol.h" #import "CISClientProtocol.h" #import "IOSSystemInterfaceFactory.h" #import "CISSystemFactoryCreator.h" #import "CISClientSettingCreator.h" #import "CISClientCreator.h" #import "CISPlayerStateManagerProtocol.h" #import "CISConstants.h" #import "CISPlayerStateManagerProtocol.h" #import "CISContentMetadata.h"

If using one of the players Conviva provides a module for, then follow these steps.


For AVPlayer/AVQueuePlayer:



- Use [ConvivaAVFoundation-4.0.46](https://github.com/Conviva/ConvivaAVFoundation/releases/tag/4.0.46), if you serve advertisements in your apps.

- Use [ConvivaAVFoundation-4.0.49](https://github.com/Conviva/ConvivaAVFoundation/releases/tag/4.0.49), if you do not serve advertisements with your apps.




For Brightcove:



- Use [ConvivaBrightcove-4.0.28](https://github.com/Conviva/ConvivaBrightcove/releases/tag/4.0.28), if you serve advertisements in your apps.

- Use [ConvivaBrightcove-4.0.31](https://github.com/Conviva/ConvivaBrightcove/releases/tag/4.0.31), if you do not serve advertisements with your apps.





1. Remove <code class="text">libLivepass3AV.a</code> from "Link Binary with Libraries" of xcode.

2. Remove the following header files from your application:

```javascript
#import "LivePass.h"
#import "ConvivaLightSession.h"
#import "ConvivaContentInfo.h"

Example usage:

<key>NSUserTrackingUsageDescription</key>
<string>App would like to access IDFA to uniquely identify the user.</string>

Cocoapods Installation: Please add the following line to your pod file and run pod install:

For Upgrade with Advertising Identifier support:

pod 'ConvivaSDK','4.0.40'

For Upgrade without Advertising Identifier support:

pod 'ConvivaSDK','4.0.47'

Or download and add the library explicitly from Conviva GitHub:

https://github.com/Conviva/ConvivaSDK

Manually adding the ConvivaSDK framework to your project

1. Unzip the package and add ConvivaSDK.xcframework to "Link Binary with Libraries" under build phase. The package contains the frameworks for iOS, tvOS, and visionOS.

2. Link the following system frameworks to "Link Binary with Libraries" section in xcode:- SystemConfiguration

• MobileCoreServices
• Security
• AdSupport
• CoreTelephony (iOS only)
• AVFoundation
• Network (weak)
• AppTrackingTransparency (weak) - Required only for Advertising Identifier supported library (Application must be built with XCode 12 or above).

3. Add "-ObjC" to "Other Linker Flags" of Xcode.

4. To refer to the Conviva classes from your source code, please add the following import statements:

import ConvivaSDK

@import ConvivaSDK;

If using one of the players Conviva provides a module for, add the corresponding dependency only.

pod 'ConvivaAVFoundation', '4.0.46'

pod 'ConvivaAVFoundation', '4.0.51'

pod 'ConvivaBrightcove', '4.0.28'

pod 'ConvivaBrightcove', '4.0.31'

Refer to Integrate Video Players for the details of player integration.

Refer to Integrate Ad Managers for the details of ad manager integration.

Swift Package Manager Installation:

• For SDK,

(CISAnalytics)createWithCustomerKey: (NSString *)customerKey settings: (NSDictionary *)settings:

#if DEBUG
let analytics = CISAnalyticsCreator.create(withCustomerKey: TEST_CUSTOMER_KEY , settings: [CIS_SSDK_SETTINGS_GATEWAY_URL: Touchstone Service URL, CIS_SSDK_SETTINGS_LOG_LEVEL:
LogLevel.LOGLEVEL_WARNING.rawValue])!
#else
let analytics = CISAnalyticsCreator.create(withCustomerKey: PRODUCTION_CUSTOMER_KEY)!
#endif

#if DEBUG
NSString *customerKey = TEST_CUSTOMER_KEY;
NSString *gatewayUrl =  Touchstone Service URL;

NSDictionary *settings = [[NSDictionary alloc] initWithObjectsAndKeys:
gatewayUrl, CIS_SSDK_SETTINGS_GATEWAY_URL,
@(LOGLEVEL_WARNING), CIS_SSDK_SETTINGS_LOG_LEVEL,
nil];

CISAnalytics analytics = [CISAnalyticsCreator createWithCustomerKey:customerKey settings:settings];
#else
NSString *customerKey = PRODUCTION_CUSTOMER_KEY;
CISAnalytics analytics = [CISAnalyticsCreator createWithCustomerKey:customerKey];
#endif

// videoAnalytics would be used throughout the integration.
let videoAnalytics = analytics.createVideoAnalytics()

// videoAnalytics would be used throughout the integration.
CISVideoAnalytics videoAnalytics = [analytics createVideoAnalytics];

// AdAnalytics would be used throughout the integration.

// Syntax of the API to instantiate Conviva Ad Analytics Component
func createAdAnalytics(withVideoAnalytics videoAnalytics: CISVideoAnalytics) -> CISAdAnalytics

func createAdAnalytics() -> CISAdAnalytics

// Sample code snippet to link the Video Analytics with Ad Analytics
let adAnalytics = analytics.createAdAnalytics(withVideoAnalytics: videoAnalytics)

//use videoAnalytics object from the iOS/tvOS SDK integration

// AdAnalytics would be used throughout the integration.
-(CISAdAnalytics) createAdAnalyticsWithVideoAnalytics: (CISVideoAnalytics) videoAnalytics;

// Syntax of the API to instantiate Conviva Ad Analytics Component
- (CISAdAnalytics) createAdAnalytics;

// Sample code snippet to link the Video Analytics with Ad Analytics
CISAdAnalytics adAnalytics = [analytics createAdAnalyticsWithVideoAnalytics: videoAnalytics];

//use videoAnalytics object from the iOS/tvOS SDK integration

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 Metadata

Conviva defines the constants or fixed string keys for commonly used metadata. These metadata keys provide critical for success information about video and ad content, versioning, workflow.

IMPORTANT: In case of Conviva modules used for video integration, Conviva 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: Conviva modules for video players are only capable of autocollecting DURATION. The rest of the metadata shall be set by your application.

The constants below are defined in the file CSSConstants.h.

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.

Constants for Pre-defined Video and Content Metadata

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 or adInfo objects, passed into corresponding methods of videoAnalytics / adAnalytics objects.

Update/Amend Metadata

To update or amend pre-defined and custom tags for video, use videoAnlaytics.setContentInfo(contentInfo: [AnyHashable : Any]):

• contentInfo: dictionary containing the key - value pairs of tags for video content.

Example usage:

// Sample code snippet
// Dictionary for Content Metadata
var contentInfo = [String: Any]()
contentInfo[CIS_SSDK_METADATA_ASSET_NAME] = "[channel_id] Live Channel Name"
// set the values for the other pre-defined keys as appropriate
contentInfo["c3.cm.contentType"] = "Live-Linear"
// set the values for custom tags as required per definition for your account
contentInfo["my_custom_tag_key"] = "my_custom_tag_value"

videoAnalytics.setContentInfo(contentInfo)

// Sample code snippet
// Dictionary for Content Metadata
NSMutableDictionary *contentInfo = [[NSMutableDictionary alloc] init];
[contentInfo setValue: @"[channel_id] Live Channel Name" forKey:CIS_SSDK_METADATA_ASSET_NAME];
// set the values for the other pre-defined keys as appropriate, refer to the tables below
[contentInfo setValue: @"Live-Linear" forKey:@"c3.cm.contentType"];
// set the values for custom tags as required per definition for your account
[contentInfo setValue: @"my_custom_tag_value" forKey:@"my_custom_tag_key"];

[videoAnalytics setContentInfo: contentInfo];

IMPORTANT: Please note that different Conviva products, such as Conviva 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.

3. Report Events and Metadata

Report Video Play Start

For each play, report playback attempt requests

videoAnalytics.reportPlaybackRequested(contentInfo: [AnyHashable : Any)?) contentInfo: map containing the key - value pairs of metadata tags for video content. The keys / constants and expected values of the required metadata tags are defined in the Implement Metadata section below. Refer to the below example illustrating usage of this API: Swift Objective C // Syntax of the API to report the request of playback initiating the viewers experience. func reportPlaybackRequested(contentInfo: [AnyHashable : Any)?) // So when user clicks on play, inside the play() function of the video player. videoAnalytics.reportPlaybackRequested(contentInfo) // With Content Info unavailable during playback videoAnalytics.reportPlaybackRequested(nil) IMPORTANT: It's 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. IMPORTANT: If some of the content metadata tags aren't available at start, they can be set later or amended by videoAnalytics.setContentInfo(contentInfo: [AnyHashable : Any]) API - refer here for details. Please note, in most cases that it's required to set content metadata before the player reports "play" for the first time, to accurately attribute metadata to the video asset. Invoke reportPlaybackRequested() On: Invoke reportPlaybackEnded() On: User clicks play button User stops the video User starts another video Video ends Video starts in autoplay mode User stops the video User starts another video Video ends User replays video again User stops the video User starts another video Video ends A new video starts in playlist Video item ends in playlist

Report Ad Breaks to Video Session

Report Ad Break

To handle ads, inform videoAnalytics object that ad break is started: videoAnalytics.reportAdBreakStarted(adPlayer: AdPlayer, adType: AdTechnology, adBreakInfo: [AnyHashable : Any]): adPlayer: informs Conviva sensor which player is used to play the ads - the same as main video content or separate instance. Depending on that, the videoAnalytics will apply corresponding logic to track it correctly. adType: specifies type of the ad (server side / client side) adBreakInfo: (optional) pod information can be passed The ideal event for invoking this method is on main video pause, to clear stage for Ad playback. If the same video player instance used for ads as for the video, call it when application requests the ads. Refer to the below sample code for illustration of how reporting shall be done in these scenarios: Swift Objective C // Ad Break Start for client side ad insertion with separate player instance for ads videoAnalytics.reportAdBreakStarted(AdPlayer.ADPLAYER_SEPARATE, adType: AdTechnology.CLIENT_SIDE, adBreakInfo: adAtrributes) // Ad Break Start for client side ad insertion with same player instance for ads videoAnalytics.reportAdBreakStarted(AdPlayer.ADPLAYER_CONTENT, adType: AdTechnology.CLIENT_SIDE, adBreakInfo: adAtrributes) // Server-side Ads // Server-side Ads are embedded within the main video content // Ad Break Start for server side ad insertion videoAnalytics.reportAdBreakStarted(AdPlayer.ADPLAYER_CONTENT, adType: AdTechnology.SERVER_SIDE, adBreakInfo: adAtrributes) On ad break ended Swift Objective C videoAnalytics.reportAdBreakEnded()

Report Video Play End

For each play end, report playback ended	Swift Objective C // Syntax of the API to report the end of playback. func reportPlaybackEnded() // So when user clicks on play, inside the play() function of the video player. videoAnalytics.reportPlaybackEnded()

4. Integrate Video Players

Conviva core SDK is universal and player agnostic, therefore it can be used to integrate any video player using the programming language it's written for.

For ease and speed of integration, Conviva also provides plug-in modules for the most commonly used video players, as well as Ad SDKs.

The modules allow to auto-detect events from the particular player / Ad SDK.

If instructions for your player are not shown below, please follow the instructions for "Custom Integration", or contact your Conviva representative.

AVPlayer/AVQueuePlayer

This documentation is for iOS/tvOS SDK 4.0.0 and above. If you are using the legacy SDK, we highly recommend you upgrade to the new SDK.

Conviva AVPlayer/AVQueuePlayer module auto-detects events emitted by AVPlayer/AVQueuePlayer. Therefore, it's not necessary to report these events explicitly by using reportPlaybackMetric() API. It's still required to report application events such as backgrounding, metadata, session close, ad-related events.

Add the Conviva AVPlayer or AVQueuePlayer module dependency	Application must be built with XCode 12 or above. Cocoapods Installation: Please add the following line to your pod file and run pod install: For Upgrade with Advertising Identifier support: pod 'ConvivaAVFoundation', '4.0.46' For Upgrade without Advertising Identifier support: pod 'ConvivaAVFoundation', '4.0.51' Swift Package Manager Installation: For AVPlayer / AVQueuePlayer, Add the Package Dependency repository URL as https://github.com/Conviva/conviva-ios-avfoundation-spm Select version as: 4.0.46 if it's with Advertising Identifier Support. - 4.0.51 if it's without Advertising Identifier Support. Or download and add the library explicitly using the links below: Always include the ConvivaSDK and ConvivaAVFoundation module with the same major version. iOS: Download the latest ConvivaSDK and ConvivaAVFoundation. Unzip the package and add ConvivaSDK.xcframework and ConvivaAVFoundation.xcframework to "Link Binary with Libraries" under build phase. The package contains iOS, tvOS, and visionOS frameworks. Add the following system frameworks to "Link Binary with Libraries" section in xcode: CoreMedia SystemConfiguration MobileCoreServices CoreTelephony (iOS only) Security Network (weak) AppTrackingTransparency (weak) - Required only for Advertising Identifier supported library (Application must be built with XCode 12 or above). Add "-ObjC" to "Other Linker Flags" of Xcode. Add the following import statements: Swift Objective C ```javascript import ConvivaSDK import ConvivaAVFoundation ```
Set player reference to Conviva videoAnalytics using this API	Swift Objective C //Once player is available videoAnalytics.setPlayer(AVPlayer) //For AVQueuePlayer videoAnalytics.setPlayer(AVQueuePlayer) Starting that moment, Conviva library will listen for all relevant events automatically. Metrics monitored by Conviva AVPlayer/AVQueuePlayer module (if applicable): : Key Description videoAnalytics.reportPlaybackError() (VSF/VPF) The module listens for the video errors fired by the player. To report application level errors impacting user experience, call videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: .ERROR_FATAL) explicitly. CIS_SSDK_PLAYBACK_METRIC_PLAYER_STATE Autocollected. All player state changes: Playing, Buffering, Paused. CIS_SSDK_PLAYBACK_METRIC_BITRATE Autocollected For the Average Peak Bitrate definition, refer to Average Peak Bitrate in Metric Dictionary. CIS_SSDK_PLAYBACK_METRIC_AVERAGE_BITRATE Autocollected. This value corresponds to the AVERAGE-BANDWIDTH value in the HLS Manifest file. The HLS Manifest file's AVERAGE-BANDWIDTH value must be lower than the BANDWIDTH value. If not, the player interprets it as an invalid value and doesn't auto collect. For the Avg. Average Bitrate definition, refer to Avg. Average Bitrate in Metric Dictionary. CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED Report the start of seeking or scrubbing by the user. Report seek position as the second argument. Click to view the reference implementation: Swift Objective C var seekToPosition = CMTimeGetSeconds(avPlayer.currentItem!.duration) seekToPosition = seekToPosition * Float64(seekBar.value) videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED, value: seekToPosition * 1000) avPlayer.seek(to:CMTimeMake(value: Int64(seekToPosition), timescale: 1), completionHandler: { (isFinished:Bool) in if isFinished == true { videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED, value: seekToPosition * 1000) } }) CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED Report the end of seeking or scrubbing by the user. Report seek position as the second argument. Click to view the reference implementation: Swift Objective C var seekToPosition = CMTimeGetSeconds(avPlayer.currentItem!.duration) seekToPosition = seekToPosition * Float64(seekBar.value) videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED, value: seekToPosition * 1000) avPlayer.seek(to:CMTimeMake(value: Int64(seekToPosition), timescale: 1), completionHandler: { (isFinished:Bool) in if isFinished == true { videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED, value: seekToPosition * 1000) } }) CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME Autocollected CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH Autocollected CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE Autocollected CIS_SSDK_PLAYBACK_METRIC_CDN_IP CDN IP address in string format. Can be autocollected Please contact Conviva Support to enable auto collection configuration. CIS_SSDK_PLAYBACK_METRIC_DROPPED_FRAMES_TOTAL Report cumulative dropped frames count. CIS_SSDK_PLAYBACK_METRIC_AUDIO_LANGUAGE Autocollected CIS_SSDK_PLAYBACK_METRIC_SUBTITLES_LANGUAGE Autocollected CIS_SSDK_PLAYBACK_METRIC_CLOSED_CAPTIONS_LANGUAGE Autocollected
Implement Metadata	Metadata monitored by Conviva AVPlayer/AVQueuePlayer module (if applicable): --> Key Description CIS_SSDK_METADATA_DURATION Autocollected for VOD contents. Report the scheduled programming duration for live or linear streams and update it on the program boundaries. Click to view the reference implementation: Swift Objective C ```javascript let contentInfo = [CIS_SSDK_METADATA_DURATION:NSNumber(126)]; videoAnalytics.setContentInfo(contentInfo); ``` CIS_SSDK_PLAYER_FRAMEWORK_NAME Autocollected To implement the metadata, refer to the above sections of common pre-defined, pre-defined video and custom metadata definitions for implementation details.

Known AVPlayer/AVQueuePlayer Limitations

Metric Name	Impact	Conditions	Issue
Connection Induced Rebuffering Ratio(CIRR)	Over-reported	User seek in PiP mode	On initiating seek in PiP mode, there are no reliable events to invoke the seek started and seek ended events. As a result, CIRR is over reported because seek-related buffering is also taken into account.
*Rebuffering Ratio (RR)*	Under-reported	HLS and low bandwidth	Under low bandwidth network conditions, HLS Live content freezes but we observe that the player still reports PLAY state.
	Under-reported	MP4 and user seek	On initiating a seek, if the player has enough cache to play, it continues to play from the current position while the seek is in progress. Once the seek is completed, the player resumes to play from the new position and no buffering is reported. This results in under-reporting of the Rebuffering Ratio Metric and Video Restart Time Metric.
	Under-reported	MP4 and iOS 9 with user-seek in low bandwidth	During low bandwidth user-seek, the player reports a PAUSE state until the user manually resumes playback after enough chunks are downloaded. No BUFFERING state is reported.
	Under-reported	HLS LIVE	The player displays the first frame momentarily but continues to prepare before it starts playing. For the user, it appears like playback starts after the first frame, but the player delays the actual playback.
	Under-reported	MP4 and tvOS AVPlayerViewController built-in seek bar	While using AVPlayerViewController built-in seek bar for Progressive Download (MP4), the player freezes after it has completed seeking the MP4 content, but we observe that the player still reports PAUSE state for sometime, followed by BUFFER state. This results in under-reporting of Rebuffering Ratio Metric and Video Restart Time if the user sends seek start using setSeekStart API.
	Under-reported	HLS and user seek	If player is paused when a user starts seek and resumes play on seek end, during the seek period the player does not report buffering. Buffering is reported only after the play resumes. Buffering is not reported during the seek period.
*Video Startup Time (VST)*	Under-reported	HLS LIVE	For HLS Live, the player delays after first frame is shown. For the user it appears like playback starts after the first frame, but actual playback is slightly delayed.
	Under-reported	MP4 and tvOS AVPlayerViewController built-in seek bar	The player freezes after it has completed seeking the MP4 content, but we observe it still reports PAUSE state for sometime, followed by BUFFER state. This results in under-reporting of Rebuffering Ratio Metric and Video Restart Time if the user sends seek start using setSeekStart API.
*Video Restart Time (VRT)*	Under-reported	MP4 and user seek	On initiating a seek, if the player has enough cache to play, it continues to play from the current position while the seek is in progress. Once the seek is completed, the player resumes to play from the new position and no buffering is reported. This results in under-reporting of the Rebuffering Ratio Metric and Video Restart Time Metric.
*Video Playback Failure (VPF)*	Not-reported	URL is unavailable during midstream. Progressive Download (MP4) Content	For MP4 content, if the URL becomes unavailable during midstream, the player does not report fatal errors. As a result, Video Playback Failures (VPF) is not reported.
	Not-reported	URL is forbidden (HTTP 403) during midstream (from iOS 14 onwards)	From iOS 14 onwards, if content URL is forbidden (HTTP 403) during streaming, playback ends without any error. Hence, session will be ended without reporting an error.

Metadata Name	Impact	Conditions	Issue
*Encoded Frame Rate*	Not-reported	HLS	The AVPlayer/AVQueuePlayer API does not provide a value for Encoded Frame Rate in HLS.
Connection Type	Not reported	VisionOS	For VisionOS, Connection Type change is not reported during the session.

Observations

tvOS 12 limitation on Foregrounding

During backgrounding events, we recommend cleaning up the old session and recreating a new one. In tvOS 12 if customers don't cleanup the old session, when the application moves to foreground, the network connection is briefly lost and tvOS 12 sends a "Connection abort error". This disrupts the Conviva data reporting and causes metric inconsistency. The affected metrics depend on the player state before backgrounding, and may include Rebuffering Ratio, Connection Induced Rebuffering Ratio, and Average % Complete.

AVPlayerViewController built-in seek bar

While using AVPlayerViewController built-in seek bar, during seek, the player reports PAUSE state until the user completes the seek.

Limitation for automaticallyWaitsToMinimizeStalling instance property

When automaticallyWaitsToMinimizeStalling property on AVPlayer instance is set to false, the Conviva AVPlayer/AVQueuePlayer module can not detect buffering state and is reported as pause state.

Custom Integration

Conviva sensor can be used to integrate video players using explicit metric reporting using the CISVideoAnalytics class methods. The major steps required are listed below.

Report playback failures	To report fatal playback error AND quit the session: videoAnalytics.reportPlaybackFailed(errorMessage, contentInfo: contentInfo): errorMessage: string is the message specifying the error. Report the reason of the failure, avoid including metadata. contentInfo: is optional. If not provided, Conviva sensor will use metadata previously reported by setContentInfo() or metadata passed along with reportPlaybackRequested() call. To report fatal playback error AND keep the session open (e.g., in case of player internal re-try or fallback logic): videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: .ERROR_FATAL): The argument errorMessage: has the same meaning as above. The argument errorSeverity: sets the severity of the error. Example usage: Swift Objective C // report error and cleanup immediately. The contentInfo provides metadata for the failed video. videoAnalytics.reportPlaybackFailed(errorMessage, contentInfo: contentInfo) // report the error but keep the session open videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: .ERROR_FATAL)
Report playback metrics	To report metric events: videoAnalytics.reportPlaybackMetric:(NSString*)key value:(id)value: key: The keys are pre-defined in the 'CSSConstants.h' file. value: It accepts multiple/zero values for the second argument. The values of the supported "key" argument are defined as Conviva constants (see the below table). Example usage: Swift Objective C // For the CIS_SSDK_PLAYBACK_METRIC_BITRATE key videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_BITRATE, value: NSNumber(value: 256)) // For the CIS_SSDK_PLAYBACK_METRIC_PLAYER_STATE key videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_PLAYER_STATE, value: NSNumber(value: PlayerState.CONVIVA_STOPPED)) The table below defines the events required to be implemented, with the corresponding parameters for each event key. Key Parameters/Units Description CIS_SSDK_PLAYBACK_METRIC_PLAYER_STATE *PlayerState.* Report any player state changes such as Playing, Buffering, Paused. CIS_SSDK_PLAYBACK_METRIC_BITRATE *NSNumber (kbps)* Report new peak bitrate value on change event (video + audio, or video only if audio isn't available). For the Average Peak Bitrate definition, refer to Average Peak Bitrate in Metric Dictionary. CIS_SSDK_PLAYBACK_METRIC_AVERAGE_BITRATE *NSNumber (kbps)* Report new average bitrate value on change event (video + audio, or video only if audio isn't available). For the Avg. Average Bitrate definition, refer to Avg. Average Bitrate in Metric Dictionary. CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED *Optional: NSNumber (ms)* Report start of seeking or scrubbing by user. If seek position is known, report as the method argument. CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED Optional: NSNumber (ms) Report end of seeking or scrubbing by user. CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME *long (ms)* Report current playback position. CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH *NSNumber (ms)* Report current Buffer length of the player. CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE *NSNumber (fps)* Report rendered framerate in fps. CIS_SSDK_PLAYBACK_METRIC_CDN_IP string (IP address) Report CDN IP address in string format. CIS_SSDK_PLAYBACK_METRICDROPPED_FRAMES_TOTAL NSNumber Report cumulative dropped frames count. CIS_SSDK_PLAYBACK_METRIC_AUDIO_LANGUAGE String ** Report the audio language code and name in the [langCode]:langName format, for example, [en]:English. When only one of them is available, report it as such, for example,**en or English. CIS_SSDK_PLAYBACK_METRIC_SUBTITLES_LANGUAGE String Report the subtitles language code and name in the [langCode]:langName format, for example, [en]:English. When only one of them is available, report it as such, for example, en or English. CIS_SSDK_PLAYBACK_METRIC_CLOSED_CAPTIONS_LANGUAGE String Report the closed captions language code and name in the [langCode]:langName format, for example, [en]:English. When only one of them is available, report it as such, for example, en or English. IMPORTANT: At any given time, a player can report the language of either the subtitles or the closed captions. When it reports one of them, the other language is set to off if it has already been reported.Report these languages (if they're available) on session start as well as when the user changes them on the current playback. Example: Swift Objective C // report closed_captions_language = "[en]:English" (language code and name are available) videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_CLOSED_CAPTIONS_LANGUAGE, value: "[en]:English"); // report the subtitles_language = "fr" (consider only language code is available) // reporting the subtitles will set the previously-reported closed_captions_language = "off" videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SUBTITLES_LANGUAGE, value: "fr"); If the audio, subtitle, or closed captions language option was initially enabled but later disabled, ensure to report the most recent language option value as off. Example: Swift Objective C videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SUBTITLES_LANGUAGE, value: "off");
Implement Callback function for polled metrics	There are certain metrics which do not have events, hence SDK provides a callback to update these values at a certain frequency. Once player has been initialized, implement the setUpdateHandler interface for the player so that the SDK can get continuous measures of the player such as, play head time, buffer length and rendered framerate. Since this API callback is called every 1 sec, it is recommended that no other metrics than the one specified be updated. Swift Objective C // Syntax of the API to register the setUpdateHandler interface used to invoke for every 1 sec by Conviva func setUpdateHandler(updateHandler :UpdateHandler); // Sample code snippet videoAnalytics.setUpdateHandler { videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH, value: NSNumber(value: 30000)) videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME, value: NSNumber(value: 10000)) videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE, value: NSNumber(value: 20)) }
Implement Metadata	For Custom Integration, Conviva sensor does not capture any metadata automatically. Refer to the above sections of common pre-defined, pre-defined video and custom metadata definitions for implementation details.

Brightcove

This documentation is for iOS/tvOS SDK 4.0.0 and above. If you are using the legacy SDK, we highly recommend you upgrade to the new SDK.

Conviva Brightcove module auto-detects events emitted by Brightcove player. Therefore, it's not necessary to report these events explicitly by using reportPlaybackMetric() API. It's still required to report application events such as backgrounding, metadata, session close, ad-related events.

Add the Conviva Brightcove module dependency	Application must be built with XCode 12 or above. Cocoapods Installation: Please add the following line to your pod file and run pod install: For Upgrade with Advertising Identifier support: pod 'ConvivaBrightcove', '4.0.28' For Upgrade without Advertising Identifier support: pod 'ConvivaBrightcove', '4.0.31' Swift Package Manager Installation: For Brightcove, Add the Package Dependency repository URL as https://github.com/Conviva/conviva-ios-bcove-spm Select version as: 4.0.28 if it's with Advertising Identifier Support. - 4.0.31 if it's without Advertising Identifier Support. Or download and add the library explicitly using the links below: Always include the ConvivaSDK and Conviva Brightcove module with the same major version. iOS: Download the latest ConvivaSDK and ConvivaBrightcove. Unzip the package and add ConvivaSDK.xcframework and ConvivaBrightcove.xcframework to "Link Binary with Libraries" under build phase.The package contains both iOS and tvOS frameworks. Add the following system frameworks to "Link Binary with Libraries" section in xcode: CoreMedia SystemConfiguration MobileCoreServices CoreTelephony (iOS only) Security Network (weak) AppTrackingTransparency (weak) - Required only for Advertising supported library (Application must be built with XCode 12 or above). Add "-ObjC" to "Other Linker Flags" of Xcode. Add the following import statements: Swift Objective C import ConvivaSDK import ConvivaBrightcove
Set player reference to Conviva videoAnalytics	Swift Objective C //Set BCOVPlaybackController instance on Proxy and attach with video analytics object let streamer = CISBCoveProxy.createBCoveProxy(bCovePlaybackController) videoAnalytics.setPlayer(streamer) Starting that moment, Conviva library listens to all relevant events automatically. If your application is using BCOVPlaybackController, then please note that the built-in seek bar in BCOVPlaybackController, which handles the video seek, does not send seek-start and seek-end events to your application. We recommend you use a custom seek bar in order to have full control over seek events. You could use an AVPlayer instance to achieve this. Your application can implement the following BCOVPlaybackController delegate methods to retrieve the AVPlayer instance (having a BCOVPlaybackSession). Swift Objective C func playbackController(_ controller: BCOVPlaybackController!, playbackSession session: BCOVPlaybackSession!, didReceive lifecycleEvent: BCOVPlaybackSessionLifecycleEvent!){ if(avPlayer == nil) { // Extract AVPlayer instance from BCOVPlaybackSession instance. avPlayer = session.player; } } func playbackController(_ controller: BCOVPlaybackController!, playbackSession session: BCOVPlaybackSession!, didProgressTo progress: TimeInterval){ if(avPlayer == nil) { // Extract AVPlayer instance from BCOVPlaybackSession instance. avPlayer = session.player; } } Metrics monitored by Conviva Brightcove module (if applicable): Key Description videoAnalytics.reportPlaybackError() (VSF/VPF) The module listens for the video errors fired by the player. To report application level errors impacting user experience, call videoAnalytics.reportPlaybackError(string message) explicitly. CIS_SSDK_PLAYBACK_METRIC_PLAYER_STATE Autocollected. All player state changes: Playing, Buffering, Paused. CIS_SSDK_PLAYBACK_METRIC_BITRATE Autocollected For the Average Peak Bitrate definition, refer to Average Peak Bitrate in Metric Dictionary. CIS_SSDK_PLAYBACK_METRIC_AVERAGE_BITRATE Autocollected. This value corresponds to the AVERAGE-BANDWIDTH value in the HLS Manifest file. The HLS Manifest file's AVERAGE-BANDWIDTH value must be lower than the BANDWIDTH value. If not, the player interprets it as an invalid value and doesn't auto collect. For the Avg. Average Bitrate definition, refer to Avg. Average Bitrate in Metric Dictionary. CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED Report the start of seeking or scrubbing by the user. Report seek position as the second argument. Click to view the reference implementation: Swift Objective C var seekToPosition = CMTimeGetSeconds(bcovPlayer.currentItem!.duration) seekToPosition = seekToPosition * Float64(seekBar.value) videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED, value: seekToPosition * 1000) bcovPlayer.seek(to:CMTimeMake(value: Int64(seekToPosition), timescale: 1), completionHandler: { (isFinished:Bool) in if isFinished == true { videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED, value: seekToPosition * 1000) } }) CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED Report the end of seeking or scrubbing by the user. Report seek position as the second argument. Click to view the reference implementation: Swift Objective C var seekToPosition = CMTimeGetSeconds(bcovPlayer.currentItem!.duration) seekToPosition = seekToPosition * Float64(seekBar.value) videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED, value: seekToPosition * 1000) bcovPlayer.seek(to:CMTimeMake(value: Int64(seekToPosition), timescale: 1), completionHandler: { (isFinished:Bool) in if isFinished == true { videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED, value: seekToPosition * 1000) } }) CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME Autocollected CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH Autocollected CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE Autocollected CIS_SSDK_PLAYBACK_METRIC_CDN_IP CDN IP address in string format. Can be autocollected Please contact Conviva Support to enable auto collection configuration. CIS_SSDK_PLAYBACK_METRIC_DROPPED_FRAMES_TOTAL Report cumulative dropped frames count. CIS_SSDK_PLAYBACK_METRIC_AUDIO_LANGUAGE Autocollected CIS_SSDK_PLAYBACK_METRIC_SUBTITLES_LANGUAGE Autocollected CIS_SSDK_PLAYBACK_METRIC_CLOSED_CAPTIONS_LANGUAGE Autocollected
Implement Metadata	Metadata monitored by Conviva Brightcove module (if applicable): Key Description CIS_SSDK_METADATA_DURATION Autocollected for VOD contents. Report the scheduled programming duration for live or linear streams and update it on the program boundaries. Click to view the reference implementation: Swift Objective C let contentInfo = [CIS_SSDK_METADATA_DURATION:NSNumber(126)]; videoAnalytics.setContentInfo(contentInfo); CIS_SSDK_PLAYER_FRAMEWORK_NAME Autocollected CIS_SSDK_PLAYER_FRAMEWORK_VERSION Refer to the existing limitations. To implement the metadata, refer to the above sections of common pre-defined, pre-defined video and custom metadata definitions for implementation details.

Known Brightcove Player Limitations

Metric Name	Impact	Conditions	Issue
*Video Playback Failures (VPF)*	Not-reported	URL is unavailable during midstream. Progressive Download (MP4) Content	For MP4 content, if the URL becomes unavailable during midstream, the player does not report fatal errors. As a result, Video Playback Failures (VPF) is not reported.
	Not reported	URL is forbidden (HTTP 403) during midstream (from iOS 14 onwards)	From iOS 14 onwards, if content URL is forbidden (HTTP 403) during streaming, playback ends without any error. Hence, session will be ended without reporting an error.
*Average Bitrate*	Incorrectly-reported	Playing chunk file bitrate	The player does not report the bitrate of the chunk file that is playing, but instead reports the bitrate of the chunk file getting downloaded. When bandwidth changes, this behavior results in incorrect reporting of average bitrate metric.

Metadata Name	Impact	Conditions	Issue
*Framework Version*	Not-reported	All	The framework version is not reported.

After integrating the video player, review advanced use cases such as live program and playlist changes, fatal errors, and foreground and background actions that can be applicable for specific goals.

Integrate Ad Managers

Conviva core SDK is universal and player agnostic, therefore it can be used to integrate any Ad SDK using the programming language it's written for.

Google IMA

Conviva provides the module to auto-detect ad events emitted by the Google IMA SDK. Therefore, it is not necessary to report these events explicitly by using core SDK APIs. It is still required to report application events such as backgrounding.

The iOS IMA module supports only Client Side ad technologies at this moment.

Add the Conviva IMA module dependency	pod 'ConvivaIMASDK', '4.0.7' Or download and add the library explicitly: https://github.com/Conviva/conviva-ios-imasdk
Set Ad Listener to AdAnalytics	To enable Ad metric & metadata auto-detection, pass the adsLoader instance of the IMA SDK to Conviva adAnalytics: Swift Objective C var info = [String: Any]() //if adTagurl is known prior info[CIS_SSDK_METADATA_AD_TAG_URL] = "adTagUrl"; //Below code is applicable only if you are using client side ads. //The second argument can be AdPlayer.ADPLAYER_CONTENT or AdPlayer.ADPLAYER_SEPARATE // Pass "ADPLAYER_CONTENT" if ads and main video use the same player, and "ADPLAYER_SEPARATE" otherwise. info[CIS_SSDK_AD_BREAK_AD_PLAYER] = AdPlayer.ADPLAYER_SEPARATE; // This API is used to initialise the IMA module and registers listeners for ad playback let proxy = CISIMAProxy.createIMAProxy(adsLoader); adAnalytics.setAdListener(proxy, andInfo:info); //info is optional here. Starting that moment, Conviva IMA module will listen for all relevant events automatically. The constants below are defined in the class CSSConstants.h. Metrics monitored by Conviva Google IMA module (if applicable): Key Implementation Note adAnalytics.reportAdError() (ASF/APF) The module listens for the ad errors fired by the player. To report application level errors impacting user experience, call adAnalytics.reportAdError(/* string */ message) explicitly. CIS_SSDK_PLAYBACK_METRIC_PLAYER_STATE Autocollected CIS_SSDK_PLAYBACK_METRIC_BITRATE Autocollected CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED Report if the application implementation supports detecting start of seeking or scrubbing by user, as Google IMA doesn't support seek during ads by default. If seek position is known, report as the method argument. Click to view the reference implementation Swift Objective C adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED, 10000); CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED Report if the application implementation supports detecting end of seeking or scrubbing by user, as Google IMA doesn't support seek during ads by default. Click to view the reference implementation Swift Objective C adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED); CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME Report if the application implementation supports collecting play head time, as Google IMA doesn't support API for fetching play head time by default. Click to view the reference implementation Swift Objective C adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME, 10000); CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH Report if the application implementation supports collecting buffer length, as Google IMA doesn't support API for fetching buffer length by default. Click to view the reference implementation Swift Objective C adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH, 10000); CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE Report if the application implementation supports collecting rendered framerate, as Google IMA doesn't support API for fetching rendered framerate by default. Click to view the reference implementation Swift Objective C adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE, 20); CIS_SSDK_PLAYBACK_METRIC_CDN_IP Report CDN IP address in string format. CIS_SSDK_PLAYBACK_METRIC_DROPPED_FRAMES_TOTAL Report periodic dropped frames count for a specific time interval.
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 IMA module automatically collects the available values for some of the metadata tags from the IMA 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 required if implementation note says "Autocollected". Key Type Implementation note CIS_SSDK_METADATA_STREAM_URL string Report the value using CIS_SSDK_METADATA_AD_TAG_URL of adAnalytics.setAdListener(). If not specified, autocollected as the same value from videoAnalytics. CIS_SSDK_METADATA_ASSET_NAME string Autocollected using ad.adTitle. CIS_SSDK_METADATA_IS_LIVE NSNumber(Bool) Autocollected as the same value from videoAnalytics. CIS_SSDK_METADATA_PLAYER_NAME string Autocollected as the same value from videoAnalytics. CIS_SSDK_METADATA_VIEWER_ID string Autocollected as the same value from videoAnalytics. CIS_SSDK_METADATA_DURATION integer Autocollected using ad.duration. CIS_SSDK_METADATA_ENCODED_FRAMERATE integer Report if the application implementation supports collecting encoded framerate, as Google IMA doesn't support reporting of the rendered framerate by default. CIS_SSDK_PLAYER_FRAMEWORK_NAME string Autocollected as "Google IMA SDK". CIS_SSDK_PLAYER_FRAMEWORK_VERSION string Autocollected using IMAAdsLoader.sdkVersion(). "c3.app.version" string Autocollected as the same value from videoAnalytics - no need to set explicitly for adAnalytics. Pre-defined Ad Metadata: Key Implementation note "c3.ad.technology" Autocollected as "Client Side". "c3.ad.id" Autocollected using ad.adId. "c3.ad.system" Autocollected using ad.adSystem. "c3.ad.position" Autocollected using ad.adPodInfo.podIndex. Set to "Pre-roll" for preroll ads, "Mid-roll" for midroll and "Post-roll" for postroll ads. "c3.ad.isSlate" Not applicable for CSAI. "c3.ad.mediaFileApiFramework" Not applicable. "c3.ad.adStitcher" Not applicable for CSAI. "c3.ad.firstAdSystem" Autocollected using ad.wrapperSystems[len-1] when there is wrapper response, else from ad.adSystem. "c3.ad.firstAdId" Autocollected using ad.wrapperAdIds[len-1] when there is wrapper response, else from ad.adId. "c3.ad.firstCreativeId" Autocollected using ad.wrapperCreativeIds[len-1] when there is wrapper response, else from ad.creativeID. "c3.ad.creativeId" Autocollected using ad.creativeID.

Known IMA Limitations:

Metadata Name	Impact	Issue
*Ad Start Failures (ASF)*	Under reported	ASF, AST, and EBAS are not autocollected by IMA SDK module and these metrics are under-reported.
*Ad Startup Time (AST)*	Under reported	ASF, AST, and EBAS are not autocollected by IMA SDK module and these metrics are under-reported.
*Exits Before Ad Start (EBAS)*	Under reported	ASF, AST, and EBAS are not autocollected by IMA SDK module and these metrics are under-reported.
*Ad Minutes*	Over reported	From iOS 13 onwards, during a phone call interruption, the player pauses ad playback but it continues reporting PLAYING state. No PAUSE state is reported. Under low bandwidth network conditions, the player delays playback after the first frame is shown. It appears like the playback starts after the first frame, but actual playback is delayed. It is observed that the player still reports PLAY state instead of BUFFERING state.

During application backgrounding while an ad is playing, we recommend pausing the ad until the application is moved to the foreground.

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: adAnalytics.reportAdLoaded(adInfo) // invoke on ad load complete adAnalytics.reportAdStarted(adInfo) // invoke on ad playback start adAnalytics.reportAdFailed(errorMessage, adInfo:adInfo) // invoke when ad fails to load/play adAnalytics.reportAdSkipped() // user skipped the ad adAnalytics.reportAdEnded() // ad playback completed In the above methods, the parameter adInfo is a dictionary containing the key - value pairs of metadata tags for ad content. Implement it with respect to the requirements prescribed in the next step.
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 videoAnalytics object automatically. Implement the pre-defined common and ad metadata specified in the table below. The constants below are defined in the class CSSConstants.h. Pre-defined Common Metadata Key Type Implementation note CIS_SSDK_METADATA_STREAM_URL string Report the manifest URL of the ad stream. CIS_SSDK_METADATA_ASSET_NAME string Report "ad title" or "[ad_id] ad_title". CIS_SSDK_METADATA_IS_LIVE NSNumber(Bool) Report the same value as for videoAnalytics. CIS_SSDK_METADATA_PLAYER_NAME string Autocollected from videoAnalytics object - no need to pass for adAnalytics. CIS_SSDK_METADATA_VIEWER_ID string Autocollected from videoAnalytics object - no need to pass for adAnalytics. CIS_SSDK_METADATA_DEFAULT_RESOURCE string Report Ad server resource the stream is played from. Set this field when the video server resource cannot be inferred from the STREAM_URL. CIS_SSDK_METADATA_DURATION integer Report the duration of the single ad clip, in seconds. For example, in a block of 3 ads each 30 seconds long, report 30 sec for each corresponding ad. CIS_SSDK_METADATA_ENCODED_FRAMERATE integer Report encoded frame rate of the ad stream in frames per second. CIS_SSDK_PLAYER_FRAMEWORK_NAME string Ad Player Framework Name. Report using videoAnalytics.setPlayerInfo(Map): Swift Objective C ```javascript // Syntax of the API to set the Player Metadata func setAdPlayerInfo(_ adPlayerInfo: [AnyHashable : Any]) // sample Code snippet var adPlayerInfo = [String: String]() // FRAMEWORK NAME CAN BE SET TO EXOPLAYER OR GOOGLE IMA OR ANY OTHER adPlayerInfo[CIS_SSDK_PLAYER_FRAMEWORK_NAME] = "Google IMA SDK" adAnalytics.setAdPlayerInfo(adPlayerInfo) ``` CIS_SSDK_PLAYER_FRAMEWORK_VERSION string Ad Player Framework Version. Report using videoAnalytics.setPlayerInfo(Map): Swift Objective C ```javascript // Syntax of the API to set the Player Metadata func setAdPlayerInfo(_ adPlayerInfo: [AnyHashable : Any]) // sample Code snippet var adPlayerInfo = [String: String]() adPlayerInfo[CIS_SSDK_PLAYER_FRAMEWORK_VERSION] = "3.11.2" adAnalytics.setAdPlayerInfo(adPlayerInfo) ``` "c3.app.version" string Report the application build version. Shall have the same value as for the videoAnalytics. Pre-defined Ad Metadata Key Type Description "c3.ad.technology" string Set the value to indicate if this is a server-side ad or a client-side ad: "Server Side" or "Client Side. "c3.ad.id" string The Ad ID extracted from the Ad Server that actually has the ad creative. For wrapper ads, this is the last Ad ID at the end of the wrapper chain. Example: "411687224". "c3.ad.system" string The name of the Ad System (i.e. the Ad Server). This Ad System represents the Ad Server that actually has the ad creative. For wrapper ads, this is the last Ad System at the end of the wrapper chain. Set to "NA" if not available. Examples: "Freewheel", "Innovid", "Extreme IO", "NA". "c3.ad.position" enum The position of the ad. Only allows ADPOSITION_PREROLL/ADPOSITION_MIDROLL/ADPOSITION_POSTROLL values which are string constants of “Pre-roll”, “Mid-roll” and “Post-roll”. "c3.ad.isSlate" string A Boolean value that indicates whether this ad is a Slate or not. Set to "true" for Slate and "false" for a regular ad. By default, set to "false". "c3.ad.mediaFileApiFramework" string The name of the creative media framework. Generally used for VPAID ads. Set to "NA" for non-VPAID ads. Examples: "VPAID", "NA". "c3.ad.adStitcher" string The name of the Ad Stitcher. If not using an Ad Stitcher, set to "NA". Examples: "Uplynk", "Google DAI", "Google Anvato", "YoSpace", "NA". "c3.ad.firstAdSystem" string Only valid for wrapper VAST responses. This tag must capture the "first" Ad System in the wrapper chain when a Linear creative is available or there is an error at the end of the wrapper chain. Set to "NA" if not available. If there is no wrapper VAST response then the Ad System and First Ad System should be the same. Examples: "GDFP", "NA". "c3.ad.firstAdId" string Only valid for wrapper VAST responses. This tag must capture the "first" Ad Id in the wrapper chain when a Linear creative is available or there is an error at the end of the wrapper chain. Set to "NA" if not available. If there is no wrapper VAST response then the Ad Id and First Ad Id should be the same. Examples: "709684096", "NA". "c3.ad.firstCreativeId" string Only valid for wrapper VAST responses. This tag must capture the "first" Creative Id in the wrapper chain when a Linear creative is available or there is an error at the end of the wrapper chain. Set to "NA" if not available. If there is no wrapper VAST response then the Ad Creative Id and First Ad Creative Id should be the same. Examples: "57861167296", "NA". "c3.ad.creativeId" string The creative id of the ad. This creative id is from the Ad Server that actually has the ad creative. For wrapper ads, this is the last creative id at the end of the wrapper chain. Set to "NA" if not available. Examples: "57861167296", "NA".
Report Ad Metrics	Report Ad-video metrics to adAnalytics by using: adAnalytics.reportAdMetric(String, value: Any?) // report metric as per the below specs. Example code illustrating how to set the metric: Swift Objective C // For PlaybackMetric adAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_PLAYER_STATE, value: NSNumber(value: PlayerState.CONVIVA_STOPPED)) // For AdMetric adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_BITRATE, value: NSNumber(value: 256)) Refer to the list of metric keys to be implememted in the table below: Key Parameters/Units Description CIS_SSDK_PLAYBACK_METRIC_PLAYER_STATE *PlayerState.* Report any player state changes such as Playing, Buffering, Paused. CIS_SSDK_PLAYBACK_METRIC_BITRATE *NSNumber (kbps)* Report new bitrate value on change event (video + audio, or video only if audio isn't available) CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED *Optional: NSNumber (ms)* Report start of seeking or scrubbing by user. If seek position is known, report as the method argument. CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED Optional: NSNumber (ms) Report end of seeking or scrubbing by user. CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME *long (ms)* Report current playback position. CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH *NSNumber (ms)* Report current Buffer length of the player. CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE *NSNumber (fps)* Report rendered framerate in fps. CIS_SSDK_PLAYBACK_METRIC_CDN_IP string (IP address) Report CDN IP address in string format. CIS_SSDK_PLAYBACK_METRIC_DROPPED_FRAMES_TOTAL NSNumber Report cumulative dropped frames count.

API Diagrams for Custom Ad Integration

Click an image to view the API call sequence:

**CSAI**

**SSAI**

NM* - During the Non-monitoring state, while the ad plays, the main video is not tracked. However, the ad metrics are tracked in Ad Experience and reported in Pulse Ad Metrics. Ad Session is Ad Attempt to Ad End. Ad Actual Play Time is Ad Play to Ad End. Total Ad Duration is Ad Start to Ad End. Reporting Ad Pod/Break Start and Ad Pod/Break End can provide additional insights about ad pods in the Conviva VSI Overview dashboard Improvement Opportunities data.

Stitched ad events are included in the video stream tracking. Ad session is from Ad Start to Ad End. Ad Actual Play Time is from Ad Play to Ad End. For SSAI because AST is short, Ad Duration typically equals Ad Actual Play Time. Ad errors are reported in both video sessions and Ad sessions. Reporting Ad Pod/Break Start and Ad Pod/Break End can provide additional insights in the Conviva VSI Overview dashboard Improvement Opportunities data. Ad metrics are also tracked in Ad Experience and reported in Pulse ad metrics.

Conviva Ad modules autocollect most of the metrics and metadata. For more details, contact your Conviva representative.

5. Handle User Actions

Handle specific user actions such as:

• App backgrounding or foregrounding

• Dialogues

• Pin popups

• Startover dialogues

• Video slates, and so on

Use the corresponding API as prescribed on the corresponding pages.

User Actions: Backgrounding

Handle backgrounding event (e.g., "home"/"power off" buttons)	Swift Objective C analytics.reportAppBackgrounded()
On foregrounding	Swift Objective C analytics.reportAppForegrounded()

User Actions: User Dialogue

User Dialogues such as:

• Pin popup

• Accepting strong language / violence

• Confirming age

• Startover / resume dialogue

Use this API on dialogue shown	Swift Objective C videoAnalytics.reportPlaybackEvent(CISConstants.getEventsStringValue(Events.USER_WAIT_STARTED), withAttributes: nil)
Use this API on dialogue dismiss	Swift Objective C videoAnalytics.reportPlaybackEvent(CISConstants.getEventsStringValue(Events.USER_WAIT_ENDED), withAttributes: nil)

Report Network Metrics

• The iOS Conviva library automatically detects the following network connection types: WiFi, 2G, 3G, 4G, OTHER. The iOS library does not support wired (Ethernet) network connection.

• The tvOS Conviva library automatically detects only wireless (WiFi) connection type.

• From tvOS 12 onwards, the tvOS Conviva library automatically detects wired (Ethernet) connection type.

The Conviva library supports the core telephony framework and fetches the raw values returned by the framework. You can reference these raw values based on the following Conviva mapping:

Raw Value	Mapping
WiFi	WiFi
CTRadioAccessTechnologyGPRS	2G
CTRadioAccessTechnologyEdge	2G
CTRadioAccessTechnologyWCDMA	2G
CTRadioAccessTechnologyHSDPA	3G
CTRadioAccessTechnologyHSUPA	3G
CTRadioAccessTechnologyCDMA1x	3G
CTRadioAccessTechnologyCDMAEVDORev0	3G
CTRadioAccessTechnologyCDMAEVDORevA	3G
CTRadioAccessTechnologyCDMAEVDORevB	3G
CTRadioAccessTechnologyeHRPD	3G
CTRadioAccessTechnologyLTE	4G
CTRadioAccessTechnologyNRNSA	5G
CTRadioAccessTechnologyNR	5G

For iOS/tvOS, to manually report or update the network connection type, use reportPlaybackMetric API:

Swift Objective C

videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_CONN_TYPE, value: "Ethernet")

The table below shows the representation string values for CIS_SSDK_PLAYBACK_METRIC_CONN_TYPE.

Internet Connection Type	Representation String
Wireless	WiFi
Wired	Ethernet
Cellular 2G	2G
Cellular 3G	3G
Cellular 4G	4G
Cellular 5G	5G
Other	OTHER

If you can fetch wireless connection sub-type, such as "802.11 a", "802.11b", "802.11n", "802.11g", then pass the sub-type instead of "WiFi".

The Network Connection Type can be updated after session creation, but only before the first video frame is rendered.

Report Signal Strength

The library cannot automatically detect signal strength of a cellular network or Wifi. However, the video application developer can report signal strength as shown in the following example:

Swift Objective C

videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_SIGNAL_STRENGTH, value: NSNumber(value:0.2))

The application developer can make use of Apple's Network Extension Frameworks NEHotspotHelper class to fetch the WiFi signal strength. The application developer needs HotspotHelper entitlements from Apple to use NEHotspotHelper. For further details, refer to NEHotspotHelper and NEHotspotNetwork Apple documentation.

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.

This document describes the identifiers that the libraries are capable of collecting, however actual collection of identifiers is 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.

Following tags are used to collect data:

• idfa: Advertising Identifier (Apple provided). This is available only on Advertising Identifier supported library. 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.

• idfv: Vendor Identifier (Apple provided). The value in this property remains the same when the app (or another app from the same vendor) is installed on the iOS device. The value changes only when the user deletes all the apps (from the same vendor) from the device and subsequently reinstall one or more of them.

The API shown below is used to control the data collection. Use it to set user preferences to opt-out of data collection by specifying the corresponding tag to true/false. By default, Conviva assumes no restriction in collecting data.

Control Data Collection and Delete Collected Data

The API shown below is used to control the data collection. Use it to set user preferences to opt-out of data collection by specifying the corresponding tag to true/false. By default, Conviva assumes no restriction in collecting data.

Control the data collection	Swift Objective C // Set true to collect data for associated tag. // Set false to stop collecting data for associated tag. analytics.setUserPreferenceForDataCollection(["idfa": NSNumber(value: true), "idfv": NSNumber(value: true)])

The API shown below is used to delete the collected data. Use it to delete previously collected data and opt-out of data collection by specifying the corresponding tag. By default, Conviva assumes no deletion of data.

Delete collected data	Swift Objective C // Set Yes to opt out of data collection and delete previously collected data for associated tag. // Set No won't delete any data. analytics.setUserPreferenceForDataDeletion(["idfa": NSNumber(value: false), "idfv": NSNumber(value: false)])

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 method:

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 Video (Pulse). Contact your Conviva representative to enable Player Insights in Pulse.

Report video-related events

videoAnalytics.reportPlaybackEvent(eventName: String, withAttributes: [AnyHashable : Any]): eventName: Mandatory argument of event name of the video player event of string type. withAttributes: Argument of event attributes of the video player event of [AnyHashable : Any] type. Swift Objective C // Syntax of the API to report the player insight event func reportPlaybackEvent(eventName: String, withAttributes: [AnyHashable : Any]) // Sample code snippet of event TestEvent with two attributes var attr = [String: Any]() attr["attr1"] = "sample value" videoAnalytics.reportPlaybackEvent("eventType", withAttributes: attr) // Syntax of the API to report the player insight event - (void) reportPlaybackEvent:(NSString*)eventName withAttributes:(nullable NSDictionary*)attributes; // Sample code snippet of event TestEvent with two attributes NSDictionary *attr = [[NSDictionary alloc] initWithObjectsAndKeys: @"sample value", @"attr1", nil]; [videoAnalytics reportPlaybackEvent: @"eventType" withAttributes: attr];

Report app-level events

analytics.reportAppEvent(eventType: String, details: [AnyHashable : Any]): eventType: Mandatory argument of event type of the app event of string type. details: Argument of event details of the app event of [AnyHashable : Any] type. Swift Objective C ```javascript // Sample code snippet let eventType = "share-click" var attr = [String: Any]() attr["Toolbar"] = "location" attr["Facebook"] = "shareService" analytics.reportAppEvent(eventType, details: attr) ``` ```objectivec // Sample code snippet NSString *eventType = @"share-click"; NSMutableDictionary *attr = [[NSMutableDictionary alloc] init]; [attr setValue:@"location" forKey:@"Toolbar"]; [attr setValue:@"shareService" forKey:@"Facebook"]; [analytics reportAppEvent: eventType details: attr]; ```

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: clientId.

NS UserDefaults to exclude from clearing: instanceId, sdkConfig, and clId.

6. Cleanup

At video playback end, call	Swift Objective C videoAnalytics.reportPlaybackEnded()
For Ad content, call	Swift Objective C adAnalytics.reportAdEnded() // Only applicable for custom ad integration, don't call for modules
On application exit, or when the Conviva object is destroyed, release the objects	Swift Objective C adAnalytics.cleanup() // if initialized videoAnalytics.cleanup() analytics.cleanup()

Advanced Use Cases

You can use specific APIs in the Conviva sensor for various advanced use cases, such as:

• Live or live linear streaming program changes

• Video changes in the playlist

• Playback does not recover from error and is reported once only

• Multiple errors due to retry when playback does not recover

• Playback recovers from a fatal error by switching to a different asset URL or CDN

• A warning occurs when there's no impact on the playback

• Handling user actions, such as user dialogues, backgrounding, and foregrounding

To learn more about these advanced use cases, see here.

Privacy Manifest Support

Privacy Manifest support is added to SDK’s(which does not collect IDFA) as mandated by Apple. Below is the snapshot of the privacy report generated by Xcode.

Identifiers		Tracking	Linked
Device ID	ConvivaSDK.framework AdvancedExampletvOS.app/Frameworks/ConvivaSDK.framework/PrivacyInfo.ecprivacy -Analytics	No	Yes
Usage Data		Tracking	Linked
Advertising Data	ConvivaSDK.framework AdvancedExampletvOS.app/Frameworks/ConvivaSDK.framework/PrivacyInfo.ecprivacy -Analytics	No	Yes
Other Usage Data	ConvivaIMASDK.framework AdvancedExampletvOS.app/Frameworks/ConvivaIMASDK.framework/PrivacyInfo.ecprivacy -Analytics	No	Yes
	ConvivaSDK.framework AdvancedExampletvOS.app/Frameworks/ConvivaSDK.framework/PrivacyInfo.ecprivacy -Analytics	No	Yes
	ConvivaBrightcove.framework AdvancedExampletvOS.app/Frameworks/ConvivaBrightcove.framework/PrivacyInfo.ecprivacy -Analytics	No	Yes
	ConvivaAVFoundation.framework AdvancedExampletvOS.app/Frameworks/ConvivaAVFoundation.framework/PrivacyInfo.ecprivacy -Analytics	No	Yes

The table below describes each identifier in the privacy report and the corresponding field SDK’s collect and reason for the collection.

Data Type	What the SDK Collects	Reason
Device ID	SDK collects IDFV which comes under Device ID category.	IDFA is collected to improve the accuracy of unique user identification.
Advertising Data	If customer supports ads and reports Conviva for ad playbacks, SDK collects all the information about ads.	To monitor ad sessions.
Other Usage Data	SDK collects information about video playbacks, failures, device metata data, and other information about the content passed by the application.	To monitor video sessions across devices.

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 2.0 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.

For more information about self-validating the builds, downloading the test cases, and viewing sample validation videos, refer to the Self-Validation page.