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:**```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.47](https://github.com/Conviva/ConvivaAVFoundation/releases/tag/4.0.47), 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.29](https://github.com/Conviva/ConvivaBrightcove/releases/tag/4.0.29), if you do not serve advertisements with your apps.

                

                

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

                    1. Remove the following header files from your application:

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

    <div class="doc-callout doc-callout--note"><div class="doc-callout__body">If you are using an SDK that supports the Advertising Identifier, the application's plist file must have an entry for <code class="text">NSUserTrackingUsageDescription</code> key with appropriate message.</div></div>
    

Example usage:

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

    <div class="doc-callout doc-callout--note"><div class="doc-callout__body"><b>Application must be built with XCode 12 or above.</b></div></div>
    

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.

        1. 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.
  
        1. To refer to the Conviva classes from your source code, please add the following import statements:
  
  
    
  
    <div>
        
  
            - Swift
  
            - Objective C
  
        
  
        <div class="tab-content current" id="tab-1">
  

import ConvivaSDK

        </div>
        <div class="tab-content" id="tab-2">
            

@import ConvivaSDK;

        </div>
    </div>
    

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

    <table class="doc-table" cellspacing="9">
        <col />
        <col />
        <tbody>
            <tr>
                <th>
                    

For AVPlayer / AVQueuePlayer with Advertising Identifier support

                </th>
                <td>
                    

pod 'ConvivaAVFoundation', '4.0.46'

                </td>
            </tr>
            <tr>
                <th>For AVPlayer / AVQueuePlayer without Advertising Identifier support</th>
                <td>
                    

pod 'ConvivaAVFoundation', '4.0.47'

                </td>
            </tr>
            <tr>
                <th>For Brightcove with Advertising Identifier support</th>
                <td>
                    

pod 'ConvivaBrightcove', '4.0.28'

                </td>
            </tr>
            <tr>
                <th>For Brightcove without Advertising Identifier support</th>
                <td>
                    

pod 'ConvivaBrightcove', '4.0.29'

                </td>
            </tr>
        </tbody>
    </table>
    

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,
				<li>Add the Package Dependency repository URL as <a href="https://github.com/Conviva/conviva-ios-sdk-spm">https://github.com/Conviva/conviva-ios-sdk-spm</a>

• Select version as:
  • 4.0.40 if it's with Advertising Identifier Support.
  • 4.0.41 if it's without Advertising Identifier Support.

    <table  class="doc-table doc-table--full" cellspacing="9">
        <col />
        <col />
        <tbody>
            <tr>
                <th>
                    

Initialize the top level CISAnalytics object

                </th>
                <td>
                    

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

Sample code illustrating initialization with/without debug:

                    <div>
                        

                            - Swift

                            - Objective C

                        

                        <div class="tab-content current" id="tab-3">
                            

#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

                        </div>
                        <div class="tab-content" id="tab-4">
                            

#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

                        </div>
                    </div>
                    

IMPORTANT: No need to set CIS_SSDK_SETTINGS_GATEWAY_URL and CIS_SSDK_SETTINGS_LOG_LEVEL settings for your production release. The Conviva SDK provides the default values for production.

                </td>
            </tr>
            <tr>
                <th>
                    

Initialize the video object

                </th>
                <td>
                    

Create instance of CISVideoAnalytics object.

This object will be used throughout the entire application lifecycle to report video related events.

                    <div>
                        

                            - Swift

                            - Objective C

                        

                        <div class="tab-content current" id="tab-5">
                            

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

                        </div>
                        <div class="tab-content" id="tab-6">
                            

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

                        </div>
                    </div>
                </td>
            </tr>
            <tr>
                <th>
                    

Initialize the ad object

                </th>
                <td>
                    

This is only applicable if your application has ads.

Create CISAdAnalytics object.

This object will be used throughout the entire application lifecycle to report ad related events.

                    <div>
                        

                            - Swift

                            - Objective C

                        

                        <div class="tab-content current" id="tab-7">
                            

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

                        </div>
                        <div class="tab-content" id="tab-8">
                            

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

                        </div>
                    </div>
                    

This method requires videoAnalytics object created at the previous step passed as a parameter.

                </td>
            </tr>
        </tbody>
    </table>
    

2. Configure Metadata

Pre-defined Video Metadata

Constants for Pre-defined Video and Content Metadata

            <div class="doc-scroll-x">
                <table cellspacing="0" cellpadding="10"  class="doc-table doc-table--full">
                    <col />
                    <col />
                    <col />
                    <thead>
                        <tr>
                            <th>Key</th>
                            <th>Type</th>
                            <th>Implementation Note</th>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td>CIS_SSDK_METADATA_ASSET_NAME</td>
                            <td>string</td>
                            <td>For **video content **, use a unique name for each stream/video asset. Values are up to your choice, but a human-readable text prefixed with the unique video ID works best in most Conviva SDK's.** This provides for clarity in reports and makes most popular content easily identifiable.Pattern: [videoID] Video Title
						

The following are typical patterns for VOD (movies and episodic content) and Live streams: Movie Pattern: [{contentId}] {Movie Title} Sample Value: [12345] The ABC Movie Episode Pattern: [{contentId}] {Show Title} - S:{Season Number}:E{Episode Number} - {Episode Title} Sample Value: [67890] The XYZ Show - S3:E1 - The Pilot Episode Live Stream Pattern: [{channelNumber}] {Chanel Name} Sample Value: [10] PQRS Bay Area CIS_SSDK_METADATA_IS_LIVE NSNumber(Bool) Denotes whether the content is video on-demand or a live stream. Affects the computation and availability of the Conviva metrics.

NSNumber(value: true/false) CIS_SSDK_METADATA_PLAYER_NAME string A string value used to distinguish video players (applications). Simple values that are unique across all of your integrated platforms work best here. If the same player used across multiple platforms, e.g., Tizen, LG TV, WEB, give separate names for each application / platofrm: e.g., "JS Tizen", "JS LGTV", "JS WEB". Do not include the build or version number in this property. The intention is to have a simple way of differentiating data from different players / platforms. CIS_SSDK_METADATA_VIEWER_ID string Required for Viewers Module. A unique identifier to distinguish individual viewers or devices through Conviva's Viewers Module. The value shall be unique abstract user's identifier. If user is anonymous, do not set any value for this tag. CIS_SSDK_METADATA_STREAM_URL

The manifest URL of the video stream. The Conviva backend config server attempts to map a portion of StreamURL into a CDN name. For example: In the URL https://www.akamai.net/avengers.m3u8, akamai.net maps to the AKAMAI label. Conviva VSI users can then retrieve metrics based on the mapped CDN name (AKAMAI, in this case).

                                <div class="doc-callout doc-callout--note"><div class="doc-callout__body">The URL values reported in the streamURL are case insensitive. The streamURLs with either all capitals or all lower case are acceptable.</div></div>
                            </td>
                        </tr>
                        <tr>
                            <td>CIS_SSDK_METADATA_DEFAULT_RESOURCE</td>
                            <td>string</td>
                            <td>
                                

This value specifies the video server or CDN name from where the streaming resource is played. Set this field when the video server resource cannot be inferred from the STREAM_URL.

For example, if the streamURL is https://cbd12348.cdn.cms.somewebsitehostname.com/abc.txt, it is not possible to infer the AKAMAI name from the streamURL, and in such a case, it is necessary to report the DEFAULT_Resource as AKAMAI.

                                <div class="doc-callout doc-callout--note"><div class="doc-callout__body">The DEFAULT_Resource value is case sensitive. If the resource name is initially reported as AKAMAI (all caps) and subsequently modified in the app to akamai (small letters), it is necessary to inform Conviva about the change because both need to be mapped in the Conviva backend configuration server to ensure that both point to the same CDN name (AKAMAI).