Conviva iOS/tvOS Quick Integration

This page serves as a quick reference for your integration, containing mostly code snippets that you'll need at various stages of integration. For more information or if you need any help, refer to the details on Conviva iOS/tvOS Sensor Integration page.

This documentation is for iOS SDK 4.0.0 and above. If you are using the legacy SDK, we highly recommend you upgrade to the new SDK below. To migrate from the legacy SDK to the new SDK, refer to the migration API mapping document here and a summary of the migration benefits here.

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.

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.41, 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:

#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, if you serve advertisements in your apps.

• Use ConvivaAVFoundation-4.0.47, if you do not serve advertisements with your apps.

For Brightcove:

• Use ConvivaBrightcove-4.0.28, if you serve advertisements in your apps.

• Use ConvivaBrightcove-4.0.29, if you do not serve advertisements with your apps.

1. Remove libLivepass3AV.a from "Link Binary with Libraries" of xcode.

2. Remove the following header files from your application:

#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.41'

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 both iOS and tvOS.

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

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

2. 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.47'

pod 'ConvivaBrightcove', '4.0.28'

pod 'ConvivaBrightcove', '4.0.29'

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

Pre-defined Video Metadata

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]):

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];

3. Report Events and Metadata

videoAnalytics.reportPlaybackRequested(contentInfo: [AnyHashable : Any)?)

// 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)

// Syntax of the API to report the request of playback initiating the viewers experience.
-(void)reportPlaybackRequested:(nullable NSDictionary*) contentInfo

// 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];

//Client-side Ads
// 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)

// Sample code snippet for Ad Breaks
//Client-side Ads
// Ad Break Start for client side ad insertion with separate player instance for ads
[videoAnalytics reportAdBreakStarted: ADPLAYER_SEPARATE adType:CLIENT_SIDE adBreakInfo:adAttributes];

// Ad Break Start for client side ad insertion with same player instance for ads
[videoAnalytics reportAdBreakStarted: ADPLAYER_CONTENT adType:CLIENT_SIDE adBreakInfo:adAttributes];

//Server-side Ads
//Server-side ads are embedded within the main video content
// Ad Break Start for server side ad insertion
[videoAnalytics reportAdBreakStarted: ADPLAYER_CONTENT adType:SERVER_SIDE adBreakInfo:adAttributes];

videoAnalytics.reportAdBreakEnded()

[videoAnalytics reportAdBreakEnded];

// 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()

// Syntax of the API to report the end of playback.
-(void)reportPlaybackEnded;

// So when user clicks on play, inside the play() function of the video player.
[videoAnalytics reportPlaybackEnded];

4. Integrate Video Players

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

AVPlayer/AVQueuePlayer

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.

pod 'ConvivaAVFoundation', '4.0.46'

pod 'ConvivaAVFoundation', '4.0.47'

//Once player is available
videoAnalytics.setPlayer(AVPlayer)
//For AVQueuePlayer
videoAnalytics.setPlayer(AVQueuePlayer)

//Once player is available
[videoAnalytics setPlayer: AVPlayer];
//For AVQueuePlayer
[videoAnalytics setPlayer: AVQueuePlayer];

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)
}
})

CMTime seekToPosition = avPlayer.currentItem.duration;
seekToPosition = CMTimeMakeWithSeconds(CMTimeGetSeconds(seekToPosition) + (Float64)seekBar.value, seekToPosition.timescale);
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED value: @(CMTimeGetSeconds(seekToPosition) * 1000)];
[avPlayer seekToTime:seekToPosition completionHandler:^(BOOL finished) {
  if(TRUE == finished){
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED value: @(CMTimeGetSeconds(seekToPosition) * 1000)];
  }
}];

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)
}
})

CMTime seekToPosition = avPlayer.currentItem.duration;
seekToPosition = CMTimeMakeWithSeconds(CMTimeGetSeconds(seekToPosition) + (Float64)seekBar.value, seekToPosition.timescale);
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED value: @(CMTimeGetSeconds(seekToPosition) * 1000)];
[avPlayer seekToTime:seekToPosition completionHandler:^(BOOL finished) {
  if(TRUE == finished){
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED value: @(CMTimeGetSeconds(seekToPosition) * 1000)];
  }
}];

Custom Integration

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

// 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 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];

// integer parameter in kbps for this key CIS_SSDK_PLAYBACK_METRIC_BITRATE
videoAnalytics.reportPlaybackMetric(CIS_SSDK_PLAYBACK_METRIC_BITRATE, value: NSNumber(value: 256))

// integer parameter in kbps for this key CIS_SSDK_PLAYBACK_METRIC_BITRATE
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_BITRATE value: [NSNumber numberWithInt:256]];

// 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");

// 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"];

// 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))
 }

// Syntax of the API to register the setUpdateHandler interface used to invoke for every 1 sec by Conviva
 - (void) setUpdateHandler:(UpdateHandler)updateHandler;

 // Sample code snippet
 __weak CISVideoAnalytics weakvideoAnalytics = videoAnalytics;
 [videoAnalytics setUpdateHandler:^{
   [weakvideoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH value: [NSNumber numberWithLong : 30000]];
   [weakvideoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME value: [NSNumber numberWithLong: 10000]];
   [weakvideoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE value:[ NSNumber numberWithLong: 20]];
 }];

Brightcove

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.

pod 'ConvivaBrightcove', '4.0.28'

pod 'ConvivaBrightcove', '4.0.29'

import ConvivaSDK
import ConvivaBrightcove

@import ConvivaSDK;
@import ConvivaBrightcove;

//Set BCOVPlaybackController instance on Proxy and attach with video analytics object
let streamer = CISBCoveProxy.createBCoveProxy(bCovePlaybackController)
videoAnalytics.setPlayer(streamer)

//Set BCOVPlaybackController instance on Proxy and attach with video analytics object
id streamer = [CISBCoveProxy createBCoveProxy: bCovePlaybackController];
[videoAnalytics setPlayer: streamer];

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;
	}
}

(void)playbackController:(id**)controller
playbackSession:(id<BCOVPlaybackSession>)session
 didReceiveLifecycleEvent:(BCOVPlaybackSessionLifecycleEvent *)lifecycleEvent{
  if(nil == avPlayer ) {
// Extract AVPlayer instance from BCOVPlaybackSession instance.
self.avPlayer = session.player;
  }
}
(void)playbackController:(id<BCOVPlaybackController>)controller
playbackSession:(id<BCOVPlaybackSession>)session
didProgressTo:(NSTimeInterval)progress {
  if(nil == avPlayer) {
// Extract AVPlayer instance from BCOVPlaybackSession instance.
self.avPlayer = session.player;
  }
}

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)
}
})

CMTime seekToPosition = bcovPlayer.currentItem.duration;
seekToPosition = CMTimeMakeWithSeconds(CMTimeGetSeconds(seekToPosition) + (Float64)seekBar.value, seekToPosition.timescale);
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED value: @(CMTimeGetSeconds(seekToPosition) * 1000)];
[bcovPlayer seekToTime:seekToPosition completionHandler:^(BOOL finished) {
  if(TRUE == finished){
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED value: @(CMTimeGetSeconds(seekToPosition) * 1000)];
  }
}];

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)
}
})

CMTime seekToPosition = bcovPlayer.currentItem.duration;
seekToPosition = CMTimeMakeWithSeconds(CMTimeGetSeconds(seekToPosition) + (Float64)seekBar.value, seekToPosition.timescale);
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED value: @(CMTimeGetSeconds(seekToPosition) * 1000)];
[bcovPlayer seekToTime:seekToPosition completionHandler:^(BOOL finished) {
  if(TRUE == finished){
[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED value: @(CMTimeGetSeconds(seekToPosition) * 1000)];
  }
}];

let contentInfo = [CIS_SSDK_METADATA_DURATION:NSNumber(126)];
videoAnalytics.setContentInfo(contentInfo);

NSMutableDictionary *contentInfo = [[NSMutableDictionary alloc] init];
[contentInfo setValue: @(126) forKey:CIS_SSDK_METADATA_DURATION];
[videoAnalytics setContentInfo: contentInfo];

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

pod 'ConvivaIMASDK', '4.0.4'

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.

NSMutableDictionary *info = [[NSMutableDictionary alloc] init];
//if adTagurl is known prior
[info setValue:@"adTagUrl"  forKey:CIS_SSDK_METADATA_AD_TAG_URL];

//Below code is applicable only if you are using client side ads.
//The second argument can be ADPLAYER_CONTENT or ADPLAYER_SEPARATE
// Pass "ADPLAYER_CONTENT" if ads and main video use the same player, and "ADPLAYER_SEPARATE" otherwise.
[info setValue:@(ADPLAYER_SEPARATE) forKey:CIS_SSDK_AD_BREAK_AD_PLAYER];

// This API is used to initialise the IMA module and registers listeners for ad playback
CISIMAProxy *proxy = [CISIMAProxy createIMAProxy:adsLoader];
[adAnalytics setAdListener:proxy andInfo:info]; //info is optional here.

adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED, 10000);

[self.adAnalytics reportAdMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_STARTED value:@(10000)];

adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED);

[self.adAnalytics reportAdMetric:CIS_SSDK_PLAYBACK_METRIC_SEEK_ENDED value:@(20000)];

adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME, 10000);

[self.adAnalytics reportAdMetric:CIS_SSDK_PLAYBACK_METRIC_PLAY_HEAD_TIME value:@(10000)];

adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH, 10000);

[self.adAnalytics reportAdMetric:CIS_SSDK_PLAYBACK_METRIC_BUFFER_LENGTH value:@(10000)];

adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE, 20);

[self.adAnalytics reportAdMetric:CIS_SSDK_PLAYBACK_METRIC_RENDERED_FRAMERATE value:@(20)];

Custom Ad Manager

adAnalytics.reportAdMetric(CIS_SSDK_PLAYBACK_METRIC_BITRATE, value: NSNumber(value: 256))

[adAnalytics reportAdMetric:CIS_SSDK_PLAYBACK_METRIC_BITRATE  value:[NSNumber numberWithInt:256]];

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.

6. Handle User Actions

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.

// 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)])

// Set Yes to collect data for associated tag.
// Set No to stop collecting data for associated tag.

[analytics setUserPreferenceForDataCollection: [NSDictionary dictionaryWithObjectsAndKeys: @YES, @"idfa", @YES, @"idfv", nil]];

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.

// 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)])

// 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: [NSDictionary dictionaryWithObjectsAndKeys: @NO, @"idfa", @NO, @"idfv", nil]];

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

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

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

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

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

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:

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

[videoAnalytics reportPlaybackMetric:CIS_SSDK_PLAYBACK_METRIC_SIGNAL_STRENGTH value:[NSNumber numberWithDouble: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.

8. 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 Video (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.

videoAnalytics.reportPlaybackEvent(eventName: String, withAttributes: [AnyHashable : Any]):

// 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];

analytics.reportAppEvent(eventType: String, details: [AnyHashable : Any]):

// Sample code snippet
let eventType = "share-click"
var attr = [String: Any]()
attr["Toolbar"] = "location"
attr["Facebook"] = "shareService"
analytics.reportAppEvent(eventType, details: attr)

// 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];

9. Cleanup

videoAnalytics.reportPlaybackEnded()

[videoAnalytics reportPlaybackEnded];

adAnalytics.reportAdEnded() // Only applicable for custom ad integration, don't call for modules

[adAnalytics reportAdEnded]; // Only applicable for custom ad integration, don't call for modules

adAnalytics.cleanup() // if initialized
videoAnalytics.cleanup()
analytics.cleanup()

[adAnalytics cleanup]; // if initialized
[videoAnalytics cleanup];
[analytics cleanup];

To know about the advanced use cases and the self-validation process, refer to the Conviva iOS/tvOS Sensor Integration page.