NAV
     

Anvato iOS SDK

This guide explains how to use the Anvato Player SDK in your iOS Application.

Features

Anvato iOS SDK is a collection of video related components that allows your application to have the following functionalities.

Package

The Anvato iOS SDK is provided as a zipped package. It contains the following files.

Filename Description
libANVSDK.a static library file for Anvato iOS SDK.
headers folder that contains .h files for the classes defined in the SDK
anv-images.bundle folder that contains the images
dependecies folder that contains the third party libraries. (Optional)

Along with the SDK package, you will two string values, the AppKey and the SecKey. If you do not have these values, please contact Anvato.

Features

Analytics

Anvato IOS SDK provides several types of plugins for data tracking and analytics purposes. Following plugins are currently provided:

Monetization

Overview

Anvato iOS SDK provides two types of monitization options using digital ads.

As Anvato, we strongly suggest server side ad-stitching over client side ads for the following reasons.

Client-Side Ads

Getting client side ads using DFP is suported by the Anvato iOS SDK. The application needs to provide an adTagURL which will be used by the SDK to fetch ads and make appropriate pings. The SDK supports rendering of client side ads both natively as well as through Google IMA SDK. Application can set DFP settings before using load to play video by using the APIs in the dfp.client namespace of the AnvatoConfig instance. Anvato iOS SDK will use these settings to generate the url and make the request. The ad tag URL might have macros which need replacing at run time such as a correlator value. This is also supported by the SDK.

Server-Side Ads

Application can set Freewheel or DFP parameters before the load video API is called. This can be done by accessing the freewheel.server / dfp.server namespace on AnvatoConfig instance. Anvato iOS SDK will forward these parameters to the Anvato backend services and Anvato stitchers will use this information to insert into the configured ad tag URL to fetch ads. In this case the ad is part of the content and ad blockers will not be able to block the ads from being rendered.

Entitlement

Overview

The Anvato Entitlement services allows for entitlement checks to be conducted before or during media playback based on different metrics like user's max rating, location and authorization to watch the content . The application can use the accessConfig object of the Anvato Config to set the SDK to do an automatic entitlement check before loading the video or on program boundaries. The following outlines the different checks we can configure for checking if user is entitled to watch a video.

Successful authentication results in the SDK sending a ANV_DATA_EVENT_ADOBEPASS_AUTHZ_SUCCESS data event. If the authentication is unsuccessful, the SDK prompts with a ANV_DATA_EVENT_ADOBEPASS_AUTHZ_FAILURE data event which indicates the user is not allowed to watch the content.

Anvato also provides TV Everywhere check. This can be set using the onStartTVE and onTuneTVE config parameters of the accessConfig object. The TVE check allows the Anvato backend to analyze the users geolocation, home station and mvpd to determine if the user is allowed to watch th requested stream. On successful check, the SDK returns a ANV_DATA_EVENT_TVE_CHECK_SUCCESS data event and ANV_DATA_EVENT_TVE_CHECK_FAILURE on a failed TVE check. If the application is handling adobepass on its own, the application needs to provide the MVPD ID and location to the SDK. This can be done via the userInfo object of the AnvatoConfig. More information regarding how to configure the SDK to enable or disable these checks can be found on a later section dealing with Configuring the SDK.

Reliable Streaming

This section describes the fallbacks in case there is a network error.

Large Screen Support

This section describes large screen support.

AirPlay

Using an Apple TV (2nd generation) or later, the Anvato SDK can airplay the current playing content to the airplay device. The SDK sends ANV_VIDEO_EVENT_AIRPLAY_START and ANV_VIDEO_EVENT_AIRPLAY_END data events that signal the beginning and end of airplaying content on external devices.

More information regarding connecting and disconnecting to airplay devices is covered in the Plugins-Airplay section

Chromecast

Chromecast is a small dongle, that is capable of playing audio/video content on a high-definition television or home audio system by directly streaming it via Wi-Fi from the Internet or a local network. The Anvato iOS SDK has support for casting the currently selected video onto a chromecast compatible device. The SDK establishes a connection between the iOS device and chromecast receiver application. Moreover, the SDK handles events related with playback on chromecast so that application side will be notified.

The application uses the same video API to start, stop, pause or resume the content. Moreover, the same video events will be fired regarding ad experience such as ad points. Basically, once the SDK establishes a secure connection, the details of the implementation for video functionalities are completely hidden from the application.

Specific details on providing Chromecast support to the application via the SDK can be acquired from the Plugins - Chromecast section.

Development Guide

This section describes all the mandatory steps to integrate Anvato iOS SDK into your application.

  1. Importing the SDK to your workspace
  2. Handling dependencies
  3. Adding Anvato UI Components
  4. Code Integration
  5. Load a sample video

Importing The SDK

Integrate the SDK, please download the latest copy using the developer portal. After unpacking the package, you can simply drag the folder into the XCode's Project Navigation window. A dialog will appear asking you to verify the operation. Check "copy if needed" option select OK. You are done! Now, your application can use the SDK objects simply by including the appropriate header file in the source code.

Dependencies

The application needs to include a list of frameworks libraries. The minimum requirement is listed below.

Frameworks

Libraries

Depending on your application requirements there may be additional libraries that you have to include. The SDK is weak linked to those libraries, meaning that your application will compile even without those libraries however you will not experience the desired behavior if the appropriate third party dependencies are not included.

Project Settings

Enabling Airplay and Picture in Picture using Background Modes

In order to support Airplay and Picture in Picture in your application, you need to configure the capabilities settings of the project so that these services can run in background mode. Go to Capabilities tab under project settings and set Background Modes to ON. In the list of services that can run in background mode, select Audio, Airplay and Picture in Picture. Also make sure that there exists an entry in the application's info.plist with the key corresponding to Required Background modes and value set to App plays audio or streams audio/video using AirPlay.

Enabling Airplay and Background Modes

UI Components

Next step is to add a View component to your application. The SDK will use the view to render the video frames. You can use .storyboard editor to add a new view. Simply select from the Object Library and drag a View component onto your application canvas. The view component should be imported into the application code by dragging it to the ViewController using the right mouse button. Once this is completed, you are ready to create an instance of the Anvato iOS SDK.

Implementation

Once all the required binaries are added, the implementation of the SDK can be done in 4 easy steps.

Step 1: Importing Headers

Step 1 Importing Headers

// =================
// ViewController.h
// =================
#import "ANVError.h"
#import "ANVGlobals.h"
#import "ANVSDK.h"
#import "ANVConfig.h"

You can start the integration by importing header files in your source code. You will need at least three header files initially and depending on your application requirements, it may require additional headers.

Step 2: The Video and Data Protocols

Step 2 The Video and Data Protocols

// =================
// ViewController.h
// =================

@interface ViewController : UIViewController <ANVDataEventListener, ANVVideoEventListener>

@end
// =================
// ViewController.m
// =================

// Video event callback
- (void) onVideoEvent:(ANVVideoEvent)event bundle:(ANVEventBundle *)bundle {
    switch ( event ) {
        case ANV_VIDEO_EVENT_AD_STARTED:
            NSLog(@"Advertisement has started.");
            break;
        default:
            break;
    }
}

// Data event callback
- (void) onDataEvent:(ANVDataEvent)event bundle:(ANVEventBundle *)bundle {
    switch ( event ) {
        case ANV_DATA_EVENT_ADOBEPASS_INIT_SUCCESS:
            NSLog(@"Adobe Pass Initialization successful.");
            break;
        default:
            break;
    }
}

Anvato iOS SDK, communicates with the application using two callback methods defined in ANVVideoEventListener and ANVDataEventListener protocols. For notifying video events such as Video Started, Video Paused, Video Resumed, the SDK fires the onVideoEvent method defined in ANVVideoEventListener. The SDK specifies the type of the event and provides ANVEventBundle object that provides additional details about the event. For example, if an AdBreak is detected, the bundle contains information such as the number of ads and their individual lengths. Similarly, for events that occur entitlement checks and program changes in live stream, SDK fires onDataEvet method defined in ANVDataEventListener. Therefore, you application needs to implement these two delegate functions.

Step 3: Initialize ANVConfig and ANVSDK objects

ANVConfig provides an interface for the application developer to configure the Anvato Player SDK. It is a singleton object so only one instance (the lastest one) will be recognised by the SDK. In order to create an instance, the application should provide anvack and seckey pairs. Using these parameters, Anvato SDK identify your application and initialize the configuration default values. Afterwards, the application can override the values and finalize the SDK configuration. Once the SDK configuration is done, the application should create an instance of the Anvato Player SDK.

In order to construct the Anvato Player SDK, the application should have an object that implements the ANVVideoEventListener and ANVDataEventListeners protocols defined in ANVGlobals.h.

Creating an instance of the Anvato iOS SDK is simple as the initializer function ( [ANVSDK initWithDataEventListener:withVideoEventListener] ) needs the reference for the event listener object.

The SDK will inform the application that it is ready to play video by firing SDK_READY event on the data channel.

Step 3

// =================
// ViewController.m
// =================

-(BOOL) createANVSDK {
    NSString *appKey = @"YourAppKey";
    NSString *secKey = @"YourSecKey";

    // First create an instance of the ANVConfig object. Using this object, you can set your parameters before creating an instance of the SDK      
    [[ANVConfig alloc] initWithAppKey:appKey secKey:secKey];
    if ( ![ANVConfig sharedInstance] ) {
        NSLog(@"ERROR: Unable to init ANVConfig. Problem with key pair?");
        return NO;
    }
    self.anvSDK = [[ANVSDK alloc] initWithDataEventListener:self withVideoEventListener:self];
    if (!self.anvSDK) {
        NSLog(@"ERROR: Unable to init ANVPlayerSDK. Config not properly initialized?");
        return NO;
    }

    [self.anvSDK initPlayerUI:self.playerView];
    return self.anvSDK != nil;
}
- (IBAction)onPlayButtonClicked:(id)sender
{
    NSString *videoID = @"YourMCPVideoID";
    if (!self.anvSDK)
    {
        NSLog(@"ERROR: Unable to play content. SDK is not initialized?");
        return;
    }
    [self.anvSDK.video load:videoID withType:ANV_VIDEO_TYPE_MCP];
}

Configuring the SDK

ANVConfig

// Accessing to singleton instance of the Anvato Configuration Object
[ANVConfig sharedInstance]

ANVConfig object provides an interface for the appplication for multiple purposes including

Access Control

Access control allow the application to activate or disable the entitlements that are enforced while the video is being loaded and also during playback.

[ANVConfig sharedInstance].accessConfig.geoLocation = NO;
[ANVConfig sharedInstance].accessConfig.onTuneAuthZ = YES;
[ANVConfig sharedInstance].accessConfig.onStartRating = NO;
[ANVConfig sharedInstance].accessConfig.onStartTVE = YES;
[ANVConfig sharedInstance].accessConfig.onTuneAuthZ = YES;
[ANVConfig sharedInstance].accessConfig.onTuneTVE = YES;
[ANVConfig sharedInstance].accessConfig.onTuneRating;
     Parameter     Type Description
geoLocation BOOL If YES, the SDK will attempt to resolve the location information of the user if it is not already defined in ANVConfig.userinfo.
onStartAuthZ BOOL If YES, the SDK will perform authorizaiton check using AdobePass plug'in while starting the video.
onStartTVE BOOL If YES, the SDK will perform Anvato TVE check while starting the video.
onStartRating BOOL If YES, the SDK will perform Anvato Parental Control check while starting the video.
onTuneAuthZ BOOL If YES, the SDK will perform authorizaiton check using AdobePass plug'in once the current program is resolved.
onTuneTVE BOOL If YES, the SDK will perform Anvato TVE check once the current program is resolved.
onTuneRating BOOL If YES, the SDK will perform Anvato Parental Control check once the current program is resolved.

AdobePass

The AdobePass plug'in allows users to login to their TV provider and access to content. Using AdobePass plug'in the SDK can perform authentication and authorization checks. The SDK can also determine service zip information which indicates location of the subscription.

     Parameter             Type                    Description
isActive (BOOL) If YES, the AdobePass plug'in is activated and the SDK can perform authorizaiton checks.
password (NSString *) The password to connect to AdobePass server. This is the base64 encoded version of the p12 file, provided by your AdobePass representative.
credential (NSString *) The credential to connect to AdobePass server. Provided by your AdobePass representative.
requestor (NSString *) The identity of the party that wants to connect to AdobePass server. Provided by your AdobePass representative.
resource_id (NSString *) The resource for which the authorization check will be applied e.g., your channel ID.
resourceRating (NSString *) The TV rating of the resource for which the authorization check will be applied. Authorization check may fail due to rating restrictions.
server_url (NSString *) The url of the server for which the SDK will attempt to connect.
temp_pass_long (NSString *) The MVPD ID that is to be used for long temppass MVPD.
temp_pass_short (NSString *) The MVPD ID that is to be used for short temppass MVPD.

UI

[ANVConfig sharedInstance].ui.controlbar.visible = YES; 

(BOOL)visible property is used to enable or disable control bar. If the Application implementing the SDK prefers to have its own UI, the control bar can be permanently hidden by setting the visible property to NO.

[ANVConfig sharedInstance].ui.controlbar.interval = 30; 

(NSTimeInterval)interval property is used to set cooling down interval of control bar. After this time period, the control bar disappears.

UserInfo

[ANVConfig sharedInstance].userinfo.encryptedHomezip = @"ENCRYPTED_ZIP"; 

(NSString *)encryptedHomezip property is used to set and get the encryptedHomezip of UserInfo.

[ANVConfig sharedInstance].userinfo.homezip = @"94043"; 

(NSString *)homezip property is used to set and get the homezip of UserInfo.

[ANVConfig sharedInstance].userinfo.homeStation = @"HOME_STATION"; 

(NSString *)homeStation property is used to set and get the homeStation of UserInfo.

[ANVConfig sharedInstance].userinfo.geozip = @"94043"; 

(NSString *)geozip property is used to set and get the geozip of UserInfo.

[ANVConfig sharedInstance].userinfo.geoStation = @"GEO_STATION"; 

(NSString *)geoStation property is used to set and get the geoStation of UserInfo.

// Ratings value include TV-Y, TV-G, TV-14, TV-PG, TV-MA
[ANVConfig sharedInstance].userinfo.maxrating = @"TV-MA"; 

(NSString *)maxrating property is used to set and get the maximum rating appropriate to the user.

[ANVConfig sharedInstance].userinfo.mvpdID = @"MVPD_ID"; 

(NSString *)mvpdID property is used to set and get the mvpdID of UserInfo.

[ANVConfig sharedInstance].userinfo.mvpdToken = @"TOKEN"; 

(NSString *)mvpdToken property is used to set and get the mvpdToken of UserInfo.

ANVPlaybackOptions

Plugins

This section describes all the available plugins that can be configured and initialized using the Anvato iOS SDK.

AdobePass

Overview

AdobePass is a plugin that allows users to access restricted content from their mobile devices using their subscription to TV providers such as AT&T, Comcast Xfinity, Optimum, etc. Anvato iOS SDK, provides simple methods and fire events to fully facilitate AdobePass functionalities that are listed below.

  1. Initializing AccessEnabler
  2. Checking if user is authenticated
  3. Logging into an MVPD or using Temppass that provides temporary access
  4. Logging out
  5. Performing authorization checks

Initialization

The initialization is fully automated using the backend configuration. All you need to do is to pass the following information to the Anvato representative.

Parameter Name Description
Password Password that provided by your AdobePass representative.
Requestor The name of the entity that uses AdobePass services. (Username)
Server URL The URL of the AdodbePass server that the SDK will connect.
Resource The id of the resource (content) for which the SDK will perform authorization checks.
P12 File The P12 file used to decrypt the incoming secure payload.

If AdobePass is configured, the SDK will notify the application about the initialization of the AdobePass plugin using onDataEvent method. In case the initialization is successful, A​NV_DATA_EVENT_ADOBEPASS_INIT_SUCCESS event will be fired. In case initialization fails, this will be notified using A​NV_DATA_EVENT_ADOBEPASS_INIT_FAILED event.

Checking Authentication

The application can check if the user is authenticated or not simply by calling the [sdk.adobepass checkAuthN] method. If the user is in authenticated, the method triggers A​NV_DATA_EVENT_ADOBEPASS_USER_AUTHENTICATED e​vent on data channel. Otherwise, it fires ANV_DATA_EVENT_ADOBEPASS_USER_NOT_AUTHENTICATED​ event. If the user is authenticated, then the SDK also fires ​ANV_DATA_EVENT_ADOBEPASS_AUTHN_MVPDID and provide additional authentication information in the bundle.

Bundle content for ​ANV_DATA_EVENT_ADOBEPASS_AUTHN_MVPDID

Key Description
ID The ID of the MVPD, which the user is using.
Sample value "Comcast_SSO"
displayName Friedly name of the MVPD.
Sample value "Xfinity Comcast"
logoURL URL for which the SDK can use to render the logo of the MVPD.
Sample value "http://idp.optimum.net/idp.optimum.net/Optimum_color1_3.png"

Loging into an MVPD

Starting login sequence

[self.anvatoSDK.adobepass login];

Handling the picker and login view

// Headers file that contains MVPD class from AdobePass library
#import "MVPD.h"

- (void) onDataEvent:(ANVDataEvent)event bundle:(ANVEventBundle *)bundle {
{
    if ( event == ANV_DATA_EVENT_ADOBEPASS_MVPD_PICKER_NEEDED )
    {
        NSArray *mvpds = [bundle getO:@"mvpds"];
        for (MVPD *mvpd in mvpds)
        {
            NSString *mvpdID = [mvpd ID];
            NSString *displayName = [mvpd displayName];
            NSString *logoURL = [mvpd logoURL];
        }

        // present the picker and then call ​[self​.anvatoSDK.adobepass setSelectedProvider:[SELECTED_MVPD_ID]];
    }
    else if ( event == ANV_DATA_EVENT_ADOBEPASS_LOGIN_VIEW_NEEDED )
    {
        NSURL *url = (NSURL *)[bundle getO:@"url"];
        self.loginVC = [[ANVRefAppLoginViewController alloc] init];
        self.loginVC.url = url;
        self.loginVC.modalPresentationStyle = UIModalPresentationCurrentContext;
        [self presentViewController:self.loginVC animated:YES completion:nil];
    }
} 

If the user is not logged in, the application may initiate the login flow simply by calling the login method on the SDK. This triggers the start of the login process. The SDK communication with the AdobePass server and fires ANV_DATA_EVENT_ADOBEPASS_MVPD_PICKER_NEEDED event. The bundle that is provided along with the event contains the list of mvpds in mvpds key which points to an NSArray of type MVPD. At this point, the application should present a picker view from which the user can choose an MVPD. Once this is done, the application should call [sdk.adobepass setSelectedProvider:] method to pass the mvpd ID that the user has selected. If the users dismisses the picker, the application should n​il value to the same method to explicitly indicate the login sequence has been interrupted.

Once, the selected MVPD is passed to the SDK, it fires another data event to notify the application about the address of the web page from which the user can login. The bundle that comes long with ANV_DATA_EVENT_ADOBEPASS_LOGIN_VIEW_NEEDED event contains a NSURL object that points the web page. The application can render a custom login screen simply by subclassing the ANVAbstractLoginViewController.

Logging in using Temppass

In order to login with a temp­pass, the application simply call the [sdk.adobepass setSelectedProvider] using either short or long tempPass MVPD ID. This will still fire ANV_DATA_EVENT_ADOBEPASS_LOGIN_VIEW_NEEDED event but the URL will simply lead to a web page that closes automatically.

Logging in using Temppass

[​self​.anvatoSDK.adobepass setSelectedProvider:@"TempPass­LongTTL"];

Logging Out

[self.anvatoSDK.adobepass logout];

The application can simply call [sdk.adobepass logout] method to initiate the logout process. The application is notified with ANV_DATA_EVENT_ADOBEPASS_USER_LOGGED_OUTevent when the operation is complete.

Performing authorization checks

The SDK authomatically performs authorization checks based on the configuration of [ANVConfig sharedInstance].accessConfig. The result is notified to the application using the data channel. If the authorization is successful then A​NV_DATA_EVENT_ADOBEPASS_AUTHZ_SUCCESS event is fired. In case of failure, the application receives A​NV_DATA_EVENT_ADOBEPASS_AUTHZ_FAILURE​ event.

Disclaimer

Adobe Pass Plugin functionality is controlled by Adobe, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Airplay

Description

The Anvato iOS SDK supports airplay. This involves the playback of current video on an airplay device such as an apple TV or airplay server. No additional implementation is required in the application to enable airplay. In presence of airplay devices in the vicinity, the airplay icon will pop up in the control bar and the user can choose to airplay the content. In this case, the advertisements are tracked by the Anvato backend and hence they cannot be observed using a proxy tool such as Charles. The playback may suffer synchronization issues if the playback on the airplay device is controlled via an external remote instead of the Application. The user may opt out of the airplay at any time by simply clicking on the airplay icon again and choosing to play on the device.

Enabling Airplay in Background Mode

In order to support Airplay in your application, we need to configure the capabilities settings of the project so that these services can run in background mode. Navigate to Capabilities tab under project settings and set Background Modes to ON. In the list of services that can run in background mode, select Audio, Airplay and Picture in Picture. Also make sure that there exists an entry in the application’s info.plist with the key corresponding to Required Background modes and value set to App plays audio or streams audio/video using AirPlay. Select Background Modes

Airplay Device Detection and Events

On clicking on the airplay icon, the user is prompted with the option to airplay to different airplay compatible devices in the vicinity. The icon is as shown below: Airplay select Clicking on the airplay device will start airplaying the content onto the device. At this point the SDK fires the ANV_VIDEO_EVENT_AIRPLAY_START event. When the user wants to quit airplay, they can press on the icon in the control bar again and select to play the content on their device. This will fire the ANV_VIDEO_EVENT_AIRPLAY_END video event.

Event Name Description
ANV_VIDEO_EVENT_AIRPLAY_START This video event is fired when the user initiates airplaying the content on a airplay device.
ANV_VIDEO_EVENT_AIRPLAY_END This video event is fired when the user quits airplay.

Akamai QoS

Description

The Anvato iOS SDK implements the Akamai QoS plugin which enables it to get configuration details from the Akamai Server set in the configURL and send analytics data to the akamai server when this plugin is enabled. The following section describes how the akamai qos plugin can be enabled and how the application can pass data to the SDK to be inserted in the akamai calls.

Configuration Parameters

//Enables/Disables the AkamaiQoS plugin 
[ANVConfig sharedInstance].akamaiQoS.isActive = YES;

//Sets the Akamai QoS config URL and the viewer ID. Viewer ID is optional.
[ANVConfig sharedInstance].akamaiQoS.configUrl = @"http://ma99-r.analytics.edgesuite.net/config/sample.xml";
[ANVConfig sharedInstance].akamaiQoS.viewerId = @"Optional Viewer ID";
Parameter Name Type Description
isActive BOOL Indicates if AkamaiQoS plugin is enabled or not.
configUrl NSString* This property is used to set or get the akamaiQoS server URL.
viewerId NSString* This property is used to set or get the Akamai QoS viewer ID.

Application Parameters

// Sending additional data with Akamai calls
ANVPlaybackOptions *options = [ANVPlaybackOptions new];
options.userData.mUserDataBundle = @{
@"akamai":@{
@"mvpdNameMvpdName":@"cablevision",
@"appName":@"Your_Application_Name"
}
};
// Load video with playback options
[self.anvatoSDK.video load:"videoMCPID" withType:ANV_VIDEO_TYPE_MCP withOptions:options];

From the application, to start akamai plugin, besides configuring the AnvatoConfig Akamai plugin on the SDK, the application needs to include the libAKAMMediaExtensions-AV.a library since akamai library is weakly linked in the AnvatoSDK. The Application can also send custom metadata in AkamaiQoS calls using the userData playback options of the ANVSDK. This is demonstrated in the code alongside. These values will only show up in the pings if they are configured in the akamai plugin configuration using the same Key that is provided to the SDK. For eg, if the appName key mentioned has been configured to be sent as part of the play calls, then all play pings will have the appName key set to the given value in user data bundle.

Expected behavior

Once the video starts playing, the SDK will start sending relevant akamai QoS calls for corresponding video events. To make sure akamai QoS plugin is working, we can filter for ANVAkamaiQoSManager in the device logs. We should see logs indicating whether the SDK was able to initialize akamai QoS library and make the relevant calls. Akamai calls will show up in a proxy tool such as Charles as shown in scheenshot below:

Disclaimer

AkamaiQoS Plugin functionality is controlled by Akamai, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Chromecast

Description

Chromecast is a media player dongle developed by Google. When connected through an HDMI port and configured for network connectivity, any mobile device can cast a video onto a large screen. Having Chromecast support in your application has a significant impact as it allows users to cast the high quality video onto their large screens, significantly enhancing the use experence. Moreover, multiple users can join the same session and alter the "playlist" as they like. This is a new way of enjoying video sharing with friends.

Chromecast requires two components, a sender application and a receiver application. Using Anvato player SDKs, you can easily turn your mobile application to a fully functional sender application. Anvato also provides Anvato Chromecast Receiver Framework (ACRF) using which you can easily create a receiver application customize the look and feel. When both Anvato Player SDK and ACRF are used together, they establish a secure channel that allows only your users to join the video session. Moreover, using the secure channel, sender and receiver application exchanges additional information. This allows you to monitor and monitize your content while users enjoy the large screen experience.

Configuration Parameters

The required configuration for enabling the Chromecast support is minimal.

Parameter Name Type Description
isActive BOOL Indicates if the SDK should listen for Chromecast activity.
enabledInControlBar BOOL When this field is turned on, the control bar will have a Chromecast button that lists the currently available devices and users use it to connect a Chromecast device *
applicationID NSString The ID of the receiver application

Detecting Available Chromecast Receivers

Once created, the SDK fires ANV_VIDEO_EVENT_CAST_DEVICE_LIST event to notify the application about the list of currently available devices using their user friendly name. This event is fired again if the list of devices is updated. The application is responsible for consuming this information and populating a list UI from which the user can choose the desired device.

Event Name Description
ANV_VIDEO_EVENT_CAST_DEVICE_LIST Lists the available devices.

Device Detection

Connecting to a Device

The application can call connect method under ccast namespace and specify the device name. The SDK notifies the application about the connection status using the following events.

NSString *deviceName = @"[SELECTED_DEVICE_NAME]";
[self.anvatoSDK.ccast connect:deviceName];
Event Name Description
ANV_VIDEO_EVENT_CAST_DEVICE_CONNECTING Start of connection attempt.
ANV_VIDEO_EVENT_CAST_DEVICE_CONNECTED_DEVICE Connected to device
ANV_VIDEO_EVENT_CAST_DEVICE_CONNECTED_APP Connected to the application
ANV_VIDEO_EVENT_CAST_DEVICE_SESSION_ESTABLISHED Connected to the ACRF
ANV_VIDEO_EVENT_CAST_DEVICE_ERROR_CONNECT_APP Unable to connect to application.
ANV_VIDEO_EVENT_CAST_DEVICE_ERROR_CONNECT_DEVICE Unable to connect to device.
ANV_VIDEO_EVENT_CAST_DEVICE_SESSION_FAILED Unable to connect to the ACRF

Video Playback

The application uses the same video API to start, stop, pause or resume the content. Moreover, the same video events will be fired regarding ad experience such as ad points. Basically, once the SDK establishes a secure connection, the details of the implementation for video functionalities are completely hidden from the application.

Joining to an Ongoing Session

If the Chromecast is currently being used by another device at the time the SDK connect to Chromecast, the SDK fires ANV_VIDEO_EVENT_CAST_METADATA_LOADED event. This event contains all the available information that would allow the application update its local UI accordingly.

Event Name Description
ANV_VIDEO_EVENT_CAST_METADATA_LOADED Provides information about the current asset being played.

Disconnecting

The application uses the disconnect method to break the connection with the ACRF.

NSString *deviceName = @"[SELECTED_DEVICE_NAME]";
[self.anvatoSDK.ccast disconnect];
Event Name Description
ANV_VIDEO_EVENT_CAST_DEVICE_DISCONNECT_REQUEST Start of disconnect process
ANV_VIDEO_EVENT_CAST_DEVICE_DISCONNECTED Completion of disconnect operation

Expected Behavior

A simple way to test the Chromecast functionality is the following.

  1. Enable Chromecast button on the control bar.
  2. Power a Chromecast device and configure it to be on the same network with the mobile device and connect it to a large screen.
  3. Observe that the Chromecast friendly name is populated in the list.
  4. Tap on the device to connect, observe that the icon changes color when the connection is established.
  5. Start a video and observe that the video starts to play on the screen.

Google Cloud Video Analytics

Description

The Anvato iOS SDK implements the Google Cloud Video Analytics plugin which enables it to get configuration details from the Google Cloud Video Analytics Server set in the configURL and send analytics data to the Google Cloud Video Analytics server when this plugin is enabled. The following section describes how the Google Cloud Video Analytics plugin can be enabled and how the application can pass data to the SDK to be inserted in the Google Cloud Video Analytics calls.

Configuration Parameters

//Enables/Disables the Google Cloud Video Analytics plugin 
[ANVConfig sharedInstance].cloudVideoAnalytics.isActive = YES;

//Sets the Google Cloud Video Analytics config URL and the viewer ID. Viewer ID is Mandatory.
[ANVConfig sharedInstance].cloudVideoAnalytics.configUrl = @"https://tracking/server";
[ANVConfig sharedInstance].cloudVideoAnalytics.trackerId = @"Mandatory Tracker ID";
Parameter Name Type Description
isActive BOOL Indicates if Google Cloud Video Analytics plugin is enabled or not. (Mandatory.)
configUrl NSString* This property is used to set or get the Google Cloud Video Analytics server URL. (Mandatory.)
trackerId NSString* This property is used to set or get the Google Cloud Video Analytics tracker ID. (Mandatory.)
enableGeoLocation BOOL Indicates if Google Cloud Video Analytics plugin geolocation data collector is enabled or not. (By default disabled.)
userAgent NSString* Customized userAgent for outgoing pings.
logLevel int Set logging levels: 0(Info), 1(Debug), 2(Warning), 3(Error, Default Level), 4(Fatal), 5(Off)

From the application, to start Google Cloud Video Analytics plugin, besides configuring the AnvatoConfig Google Cloud Video Analytics plugin on the SDK, the application needs to include the libGoogleCloudMediaAnalyticsServices.a library since Google Cloud Video Analytics library is weakly linked in the AnvatoSDK.

Expected behavior

Once the video starts playing, the SDK will start sending relevant Google Cloud Video Analytics calls for corresponding video events. To make sure Google Cloud Video Analytics plugin is working, we can filter for [CVA] in the device logs. We should see logs indicating whether the SDK was able to initialize Google Cloud Video Analytics library and make the relevant calls. Google Cloud Video Analytics calls will show up in a proxy tool such as Charles

Notice statement

Google Cloud Video Analytics Plugin functionality is controlled by Google, LLC. You must both have an account with the Google Cloud Video Analytics Service and enter into a license agreement with the Google Cloud to use this plugin.

Comscore

Description

The Anvato iOS SDK implements the comScore library which enables it to send analytics data to the comScore server when this plugin is enabled. The SDK also allows the application to send custom metadata in these calls. The following sections describe how the comscore plugin can be enabled and how the application can pass data to the SDK to be inserted in the comScore calls.

Configuration Parameters

//Enables/Disables the comScore plugin 
[ANVConfig sharedInstance].comscore.isActive = YES;

//Sets the Comscore parameters
[ANVConfig sharedInstance].comscore.C2 = @"YOUR_C2_VALUE";
[ANVConfig sharedInstance].comscore.publisher_secret = @"YOUR_PUBLISHER_SECRET_VALUE";

//Optional metadata to be sent with Comscore calls
[ANVConfig sharedInstance].comscore.mapping = @{
                                                @"c3": @"YOUR_C3_VALUE",
                                                @"c4": @"YOUR_C4_VALUE",
                                                @"ns_st_cl": @"{{COMSCORE_CLIP_LENGTH}}",
                                                };
Parameter Name Type Description
isActive BOOL Indicates if comScore plugin is enabled or not.
C2 NSString* This property is used to set or get the comScore C2 parameter.
publisher_secret NSString* This property is used to set or get the publisher secret for comscore.
mapping NSDictionary* This property is used to set optional metadata.

Application Parameters

SCORPublisherConfiguration *publisherConfiguration = [SCORPublisherConfiguration publisherConfigurationWithBuilderBlock:^(SCORPublisherConfigurationBuilder *builder) {
    builder.publisherId = @"YOUR_PUBLISHER_ID_VALUE";
    builder.publisherSecret = @"YOUR_PUBLISHER_SECRET_VALUE";
}];

[[SCORAnalytics configuration] addClientWithConfiguration:publisherConfiguration];
[SCORAnalytics start];

From the application, to start comscore plugin, besides configuring the AnvatoConfig Comscore plugin on the SDK, the application needs to do the following:

  1. Include ComScore.framework and import <ComScore/ComScore.h> header
  2. Configure CSComscore with customerC2, publisherSecret and mapping values (mandatory)
  3. Configure optional parameters like setAppName.
  4. Call publisherConfigurationWithBuilderBlock, addClientWithConfiguration and start methods of CSComscore

Expected behavior

Once the video starts playing, the SDK will start sending relevant comscore calls for corresponding video events. To make sure comScore is working, we can filter for ANVComScoreManager in the device logs. We should see logs indicating whether the SDK was able to initialize comScore library and make the relevant calls. Comscore calls will show up in a proxy tool such as Charles as shown in scheenshot below: Comscore calls

Disclaimer

Comscore Plugin functionality is controlled by Comscore, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Conviva

Description

The Anvato iOS SDK implements the Conviva library which enables it to send analytics data to the conviva end point when this plugin is enabled. The SDK also allows the application to send custom metadata in these calls. The following sections describe how the conviva plugin can be enabled and how the application can pass data to the SDK to be inserted in the conviva calls. Conviva dashboards provide insights to content broadcasters by gathering key metrics during high demand events and monitor the system in real time.

Configuration Parameters

//Enables/Disables the Conviva plugin 
[ANVConfig sharedInstance].conviva.isActive = YES;

//Sets the Conviva parameters
[ANVConfig sharedInstance].conviva.customerKey = @"YOUR_PUBLISHER_SECRET_VALUE";
[ANVConfig sharedInstance].conviva.gatewayUrl = @"YOUR_PUBLISHER_SECRET_VALUE";

//Optional: logLevel determines the logging output from the conviva plugin. 0(debug) -> 4(Off)
[ANVConfig sharedInstance].conviva.logLevel = 0;

[ANVConfig sharedInstance].conviva.mapping.streamUrl = @"CURRENT_STREAM_URL";
[ANVConfig sharedInstance].conviva.mapping.viewerId = @"UNIQUE_VIEWER_ID";
[ANVConfig sharedInstance].conviva.mapping.assetName = @"NAME_OF_ASSET";
[ANVConfig sharedInstance].conviva.mapping.applicationName = @"APPLICATION_NAME";
[ANVConfig sharedInstance].conviva.mapping.cdnName = @"CDN";
[ANVConfig sharedInstance].conviva.mapping.defaultResource = @"CDN";
[ANVConfig sharedInstance].conviva.mapping.duration = @"DURATION";

//Optional: additional metadata to be sent to the conviva dashboard for current session
[ANVConfig sharedInstance].conviva.mapping.context = @{
                                                        @"key1": @"value1",
                                                        @"key2": @"value2"
                                                    };
Parameter Name Type Description
isActive BOOL Indicates if conviva plugin is enabled or not.
customerKey NSString* This property is used to set or get the unique customer key.
gatewayUrl NSString* This property is used to set or get the conviva end point URL.
logLevel int This property is used to set or get the logging level.
mapping ANVConvivaMappingConfig* This property is used to set all the remaining standard metadatas

Application Parameters

// Sending additional data with Conviva calls
ANVPlaybackOptions *options = [ANVPlaybackOptions new];
options.userData.mUserDataBundle = @{
                                    @"conviva":@{
                                        @"appName":@"Your_Application_Name",
                                        @"key1":@"value1"
                                        }
                                    };
// Load video with playback options
[self.anvatoSDK.video load:"videoMCPID" withType:ANV_VIDEO_TYPE_MCP withOptions:options];

From the application, to start the Conviva plugin, besides configuring the AnvatoConfig Conviva plugin on the SDK, the application needs to include the conviva library since the library is weakly linked in the AnvatoSDK. The Application can also send custom metadata in Conviva calls using the userData playback options of the ANVSDK. This is demonstrated in the code alongside.

Expected behavior

Once the video starts playing, the SDK will start sending relevant conviva calls for corresponding video events. To make sure conviva is working, we can filter for ANVConvivaManager in the device logs. We should see logs indicating whether the SDK was able to initialize the conviva library and make the relevant calls.

Disclaimer

Conviva Plugin functionality is controlled by Conviva, Inc. ("3rd Party"). Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

DFP

Description

The Anvato iOS SDK supports DFP (DoubleClick for Publishers, an advertisement software as a service application run by Google). Application can set DFP settings before using load to play video by using the APIs in the dfp namespace of the AnvatoConfig instance. Anvato IOS SDK will use these settings in the post object which is used to get video data from backend servers.

There are two type of DFP ad: server side dfp and client side dfp. We highly recommend using the server side dfp, since it has the following two advantages:

  1. Effectively prevent the Ad blocker;
  2. Better performance for the user experience when switching playback between ios device and Apple Airplay device or Google Chromecast device.

Client Side

// Sets the DFP in the Anvato SDK active
[ANVConfig sharedInstance].dfp.isActive = YES;

// Sets the DFP client side in the Anvato SDK active
[ANVConfig sharedInstance].dfp.client.isActive = YES;

// Only one of the following options should be set.
// Option 1: Set the ad preroll url
[ANVConfig sharedInstance].dfp.client.adTagUrl = @"adTagUrl";

// Option 2: Set the ad play list url, which includes preroll url and postroll url
[ANVConfig sharedInstance].dfp.client.playListUrl = @"playListUrl";

Configuration Parameters

Parameter Name Type Description
isActive BOOL Indicates if DFP is enabled or not.
client ANVDFPAdConfig DFP client ad configuration.
client.adTagUrl NSString The DFP ad preroll url.
client.isActive BOOL Indicates if DFP client side is enabled or not.
client.playListUrl NSString The DFP ad playlist Url, including ad preroll url and ad postroll url.

Server Side

// Sets the DFP in the Anvato SDK active
[ANVConfig sharedInstance].dfp.isActive = YES;

// Sets the DFP server side in the Anvato SDK active
[ANVConfig sharedInstance].dfp.server.isActive = YES;

// Set all the other parameters.
[ANVConfig sharedInstance].dfp.server.customParams = (NSMutableDictionary*)customParamsDic;
[ANVConfig sharedInstance].dfp.server.parameters = (NSMutableDictionary*)paramsDic;
[ANVConfig sharedInstance].dfp.server.serverUrl = @"serverUrl";
[ANVConfig sharedInstance].dfp.server.userAgent = @"userAgent";

Configuration Parameters

Parameter Name Type Description
isActive BOOL Indicates if DFP is enabled or not.
server ANVDFPAdConfig DFP server ad configuration.
server.customParams NSMutableDictionary The DFP custom paramaters.
server.isActive BOOL Indicates if DFP server side is enabled or not.
server.parameters NSMutableDictionary The DFP paramaters.
server.serverUrl NSString The DFP server url.
server.userAgent NSString The DFP user agent.

Expected behavior

When the dfp is set up, ads should be able to play in the app. Also, we can observe the impressions from the proxy logs (e.g. using HTTP proxy tool such as Charles). The impressions will be fired at the ad pod start point, the ad start point, the 25% ad point, the 50% ad point, the 75% ad point and the ad finish point.

Charles of Omniture Request

Disclaimer

Google DFP Plugin functionality is controlled by Google, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Freewheel

Description

The Anvato iOS SDK supports playback of client side and server side ads served from freewheel ad servers. By configuring the SDK with server side freewheel advertising parameters, the SDK will send the the values to the Anvato backend, which will insert the modified version of the advertisement into the original video asset and serve it to the player. Conversely, by using client side freewheel advertising parameters, the player will make an ad request and parse the VAST response by itself. The player will then play the video as a seperate play item as part of a playlist. We suggest server side ad stitching over client side since ad blockers cannot block server stitched ads.

Configuration Parameters

Through the freewheel object in ANVConfig the Application can set either the client side or server side ad stitching configuration. This can be done by accessing the client or server object of freewheel. The following sections shows how to set them.

//Activate freehweel server side ad stitching
[ANVConfig sharedInstance].freewheel.server.isActive = YES;
[ANVConfig sharedInstance].freewheel.server.network_id = @"123456";
[ANVConfig sharedInstance].freewheel.server.profile_id = @"123456:profile_anvato_ios";
[ANVConfig sharedInstance].freewheel.server.server_url = @"http://freewheel/server/url";
[ANVConfig sharedInstance].freewheel.server.site_section_id = @"test_anvato_app_vod_ipad";
[ANVConfig sharedInstance].freewheel.server.video_asset_id = @"ANV_ASSET_ID";

[ANVConfig sharedInstance].freewheel.server.customParams = @{
                                                                 @"Key1":@"Value1",
                                                                 @"Key2":@"Value2",
                                                                 @"Key3":@"Value3",
                                                                 };

Server Side Ad Stitching Parameters

The following parameters are to be set in the AnvatoConfig object to enable server side ad stitched content to be played on the Anvato player. These parameters needs to be configured before the Anvato video load API call.

Parameter Name Type Description
isActive BOOL Enables Freewheel server side advertisement plugin.
network_id *NSString The network ID to retrieve the advertisement.
profile_id *NSString The freewheel profile ID
server_url *NSString The freewheel server URL.
site_section_id *NSString The site section ID of the freewheel ad.
video_asset_id *NSString The video asset ID to be sent to freewheel to retrieve ads targeting the particular asset.
customParams *NSDictionary The custom parameters macros to be sent to backend to replace keys in ad tag url.

customParams is an optional field that can be used to send key value pairs to the Anvato Backend such that the keys set in the ad tag URL can be replaced by their corresponding value. For eg. if an ad tag has this as part of the URL: ....&myKey1=[Key1]&myKey2=[Key2]&..., Key1 and Key2 will be replaced by the corresponding values in customParam which will be sent at load time from the SDK. Sample code to send customParams is shown on the right.

Method Return Type Description
getDictionary NSDictionary Returns a dictionary containing the values of the freewheel server side paramters such as network_id, profile_id, server_url, site_section_id and video_asset_id.
//Activate freehweel client side ad stitching
[ANVConfig sharedInstance].freewheel.client.isActive = YES;
[ANVConfig sharedInstance].freewheel.client.server_url = @"http://freewheel/server/url";
[ANVConfig sharedInstance].freewheel.client.customParams = @{@"param1":@"value1",@"param2":@"value2"};
[ANVConfig sharedInstance].freewheel.client.parameters = @{@"key1":@"value1"};
[ANVConfig sharedInstance].freewheel.client.slotParamters = @{};

Client Side Ad Stitching Parameters

The following parameters are to be set in the AnvatoConfig object to enable client side ad stitched content to be played on the Anvato player. These parameters need to be configured before the Anvato video load API call. In case of client ad stitching, the player will fetch the ad by creating a URL out of the following parameters. Since the URL is called directly from the player, it can be blocked by ad blockers.

Parameter Name Type Description
isActive BOOL Enables Freewheel client side advertisement plugin.
customParams *NSMutableDictionary Custom parameters to send as part of the Freewheel ad query.
parameters *NSMutableDictionary Required list of parameters sent as part of the ad request.
server_url *NSString The freewheel server URL.
slotParameters *NSMutableArray slotParamaters is a list that is appended at the end of the URL, seperated by ';'
Method Return Type Description
getAdTagURL *NSString Returns a strng representation of the ad request URL that is created using the server_url, parameters, custom parameters and slotParameters.

Expected behavior

During playback of an advertisement fetched from freewheel, the SDK fires the ANV_VIDEO_EVENT_AD_POD_STARTED, for an ad pod and ANV_VIDEO_EVENT_AD_STARTED video event for every individual ad.We can also observe the relevant pings sent to freewheel server in a proxy tool. An image of a Ad Complete ping observed in Charles Proxy is shown below. Freewheel ad complete Call

Disclaimer

Freewheel Plugin functionality is controlled by Freewheel, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Google Analytics

Description

The Anvato iOS SDK implements the Google Analytics(GA) plugin which enables it to send analytics data to the Google Analytics end point when this plugin is enabled. The SDK also allows the application to send custom metadata in these calls. The following sections describe how the GA plugin can be enabled and how the application can pass data to the SDK to be inserted in the GA calls. GA dashboards provide insights to content broadcasters by gathering key metrics during high demand events and monitor the system in real time.

Configuration Parameters

//Enables/Disables the Google Analytics plugin 
[ANVConfig sharedInstance].googleAnalytics.isActive = YES;

//Sets the Google Analytics trackerId, dispatchInterval, and custom values.
[ANVConfig sharedInstance].googleAnalytics.trackerId = @"Mandatory Tracker ID";
[ANVConfig sharedInstance].googleAnalytics.dispatchInterval = 120;
[ANVConfig sharedInstance].googleAnalytics.mapping.customDimension.videoSecondsViewed = 10;
[ANVConfig sharedInstance].googleAnalytics.mapping.customDimension.context = @{@"11": @"title",
                                                                    @"12":@"assetId"};
[ANVConfig sharedInstance].googleAnalytics.mapping.customMetric =  @{@"videoPlayerLoad": @21,
                                                              @"videoStart": @22};

//Sets auto Ping Time, in case no ANV_DATA_EVENT_NEW_PROGRAM for live.
[ANVConfig sharedInstance].googleAnalytics.autoPingTime = 30;
Parameter Name Type Description
isActive BOOL Indicates if Google Analytics plugin is enabled or not. (Mandatory.)
trackerId NSString* This property is used to set or get the Google Analytics tracker ID. (Mandatory.)
dispatchInterval NSInteger The time interval between pings. By default, this is set to 120, which indicates tracking information should be dispatched automatically every 120 seconds.
mapping.customDimension.videoSecondsViewed NSDictionary* Custom dimension: Video Seconds Viewed.
mapping.customDimension.context NSDictionary* Custom dimension: context.
mapping.customMetric NSDictionary* Custom metric.
autoPingTime NSInteger The waiting time for the pings when there is no ANV_DATA_EVENT_NEW_PROGRAM for live.

From the application, to start Google Analytics plugin, besides configuring the AnvatoConfig Google Analytics plugin on the SDK, the application needs to include the libGoogleAnalyticsServices.a library since Google Analytics library is weakly linked in the AnvatoSDK.

Expected behavior

Once the video starts playing, the SDK will start sending relevant Google Analytics calls for corresponding video events. We should see logs indicating whether the SDK was able to initialize Google Analytics library and make the relevant calls. Google Analytics calls will show up in a proxy tool such as Charles.

Notice statement

Google Analytics Plugin functionality is controlled by Google, LLC. You must both have an account with the Google Analytics Service and enter into a license agreement with the Google to use this plugin.

Heartbeat

Description

The SDK implements the Adobe Heartbeat library and if this plugin in enabled, it sends relevant video, chapter, ad and quality of service metrics. During video playback, heartbeat calls are sent which contain information regarding the video being played. The plugin also allows the application to piggyback custom metadata on heartbeat calls so as to gather additional information regarding the video experience. The following sections explain the various heartbeat configuration parameters, steps to enable heartbeat plugin as well as configuring the SDK to send custom metadata on heartbeat calls.

Configuration Parameters

// Sets the Heartbeat plugin in the Anvato SDK active
[ANVConfig sharedInstance].heartbeat.isActive = YES;

// Shows verbose Debug logs. Adobe recommends debug mode be turned off for Production application
[ANVConfig sharedInstance].heartbeat.isDebugMode = YES;

[ANVConfig sharedInstance].heartbeat.channel = @"channel";
[ANVConfig sharedInstance].heartbeat.job_id = @"1";
[ANVConfig sharedInstance].heartbeat.ovp = @"ovp";
[ANVConfig sharedInstance].heartbeat.publisher = @"publisher-name";
[ANVConfig sharedInstance].heartbeat.SDK = @"1.6.6";
[ANVConfig sharedInstance].heartbeat.tracking_server = @"heartbeats.omtrdc.net ";
Parameter Name Type Description
isActive BOOL Indicates if Heartbeat is enabled or not.
isDebugMode BOOL Sets the Heartbeat library to debug mode.
channel NSString* The heartbeat channel name.
job_id NSString* The heartbeat job_id paramater.
ovp NSString* The heartbeat ovp paramater.
publisher NSString* The heartbeat publisher paramater.
sdk NSString* The heartbeat sdk version.
tracking_server NSString* Indicates the tracking server where the heartbeat calls are sent.

Application Parameters

ANVPlaybackOptions *options = [ANVPlaybackOptions new];
options.userData.mUserDataBundle = @{
                                         @"heartbeat":@{
                                            @"videoMVPD":@"Cablevision",
                                            @"videoScreen":@"fullscreen",
                                            @"videoInitiate":@"Manual"
                                         }
                                     };
// Load video with playback options
[self.anvatoSDK.video load:"videoMCPID" withType:ANV_VIDEO_TYPE_MCP withOptions:options];

The application can pass additional data to the SDK which will be sent as part of the heartbeat calls containing context metadata. This can be achieved by setting the mUserDataBundle dictionary of the userData object of the ANVPlaybackOptions. This has been demonstrated using the sample code on the side.

Events and Heartbeat Data Information

This sections maps out the events that are tracked by the Heartbeat Plugin as well as the data we send with the corresponding event. Some events like Ad Break start, Chapter start allow us to pass a context metadata dictionary along with the call. If the application passes additional data to be sent with heartbeat calls, it is attached to these dictionaries. A Video Start call is shown below. It has information related to the video being played such as video id, name, video type and video length and playhead. Heartbeat Video start Call Similaryly an ad start call has relevant information regarding the current advertisement being played such as ad ID, ad Name, ad Length and position of that ad in the ad break. It will also carry the ad break information which the ad is a part of. Heartbeat ad start Call

Events tracked by Heartbeat

Event Name Description
Video Load Load the main video asset
Video Unload Unload the main video asset
Play Playback start
Pause Playback stop/pause
Seek Start Seek start
Seek Complete Seek complete
Buffer Start Buffer start
Buffer Complete Buffer complete
Complete Playback complete
Ad Start An ad starts
Ad Complete An ad completes
Chapter Start A new chapter starts
Chapter Complete A chapter completes
Bitrate Change A switch to another bitrate occurs
Session Start Autoplay is on, or user clicks play
Application Error An error occurs at the application level

Heartbeat data information

Video Information

This information is sent by the plugin when the player first loads the video.

Parameter Custom Metadata Description
playerName YES The name of the player playing the video. Set to Anvato iOS Player by default.
streamType YES Indicates the type of the content (e.g., 'live', 'vod', 'clip')
videoId YES Shows the MCP ID of the video asset
name YES The user friendly name of the video asset
playhead NO Current position of the video player in seconds.
length NO Duration of te asset in seconds. -1 for live

Ad Break Information

This information is sent when the player starts an advertisement block.

Parameter Custom Metadata Description
playerName YES The name of the player playing the ad. It is set to Anvato Player SDK with version information by default.
name YES Friendly name of the ad pod. (e.g., 'preroll', 'midroll')
position NO Sequence number of the ad pod in the asset.
startTime NO The offset of the ad

Ad Information

This information is sent at every advertisement start.

Parameter Custom Metadata Description
adID YES The ID of the advertisement.
name YES User friendly name of the advertisement. If this is not available, player sets it to 'N/A' by default
position NO Position of the advertisement in the ad pod starting from 1
length NO Duration of the advertisement

Chapter Information

This information is sent at the transition from advertisement to content.

Parameter Custom Metadata Description
name YES User friendly name of the chapter
length NO Duration of the chapter
position NO Position of the chapter in the asset
startTime NO The offset of the chapter in the asset in seconds

QoS Information

This information is sent in every Heartbeat call and contains details regarding the quality of video being played.

Parameter Custom Metadata Description
startUpTime NO The time it took to load the content
bitrate NO Current bitrate of the video (available only for HLS content)
fps NO Framerate of the content. By default all videos is 30 fps
droppedFrames NO Number of dropped frames by the decoder.

Expected Behaviour

The device logs can be filtered by ANVHeartbeatManagerV4 to see if heartbeat manager was enabled and successfully initialized. Also the heartbeat plugin's isDebugMode can be set to YES to see more verbose logs in order to verify what data the SDK is providing to the Adobe Heartbeat library in response to video events.

Disclaimer

Adobe Heartbeat Plugin functionality is controlled by Adobe, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Heartbeat Nielsen

Description

The Adobe Heartbeat library has the implementation of the Nielsen DCR & DTVR. It can fire Nielsen pings by configurate the Heartbeat Nielsen parameters.

Heartbeat with joint Nielsen Version number

1.5.1.1

Configuration Parameters

// Sets the Heartbeat Nielsen plugin in the Anvato SDK active
    [ANVConfig sharedInstance].heartbeat.isNielsenEnabled = YES;
Parameter Name Type Description
isNielsenEnabled BOOL Indicates if Heartbeat Nielsen is enabled or not.

Video Information This Heartbeat Nielsen information is sent by the plugin when the player first loads the video.

Parameter Custom Metadata Description
enabled NO Indicates heartbeat nielsen enable or not
isTVRenabled NO Indicates heartbeat nielsen dTVR enable or not
configKey NO The string of Nilesen configKey
appID NO The string of Nilesen appID
clientID NO The string of Nilesen clientID
vcID NO The string of Nilesen vcID
appVersion NO The string of current application version nubmer
appName NO The string of current application appName
sfCode NO The string of Nilesen sfCode
type YES The detail of the block Type
program YES The name of program
title YES The name of current program title
length YES The length of the video
adLoadType NO The load type of the ad
assetID YES The asset ID
airDate YES The air date of current program
isFullEpisode YES Indicates if video is full episode

Nielsen (DCR)

Description

Nielsen DCR (Digital Content Rating) enables the developers to measure online video playing, app launches, app crashes, advertisements, page views, etc. DCR measurement content is developed for digital-only or linear TV content with dynamic ad-model.

Configuration Parameters

[ANVConfig sharedInstance].nielsen.app_id = @"app_id";
[ANVConfig sharedInstance].nielsen.app_name = @"app_name";
[ANVConfig sharedInstance].nielsen.app_version = @"app_version";
[ANVConfig sharedInstance].nielsen.isActive = YES;
[ANVConfig sharedInstance].nielsen.sf_code = @"sf_code";

Parameters in AnvatoConfig/ANVConfig (sharedConfig.nielsen):

Parameter Name Type Description
app_id NSString* Unique ID assigned to the player/site and configured by product.
app_name NSString* The name of the application.
app_version NSString* The version of the application.
isActive BOOL Indicating if nielsenDCR is active or not.
sf_code NSString* Unique identifier for the environment that the SDK should point to.

Application Parameters

The application pass no parameters to the SDK regarding the plugin.

Expected behavior

No Expected Behavior for now.

Disclaimer

Nielsen DCR Plugin functionality is controlled by Nielsen, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Nielsen (DTVR)

Description

Nielsen DTVR (Digital Television Ratings) is a product of Nielsen that measures live TV viewing up to seven days of broadcasting without change in National ads.

Anvato iOS SDK, provides simple methods to fully facilitate Nielsen functionalities.

Configuration Parameters

[ANVConfig sharedInstance].nielsenTVR.appID = @"appID";
[ANVConfig sharedInstance].nielsenTVR.appName = @"appName";
[ANVConfig sharedInstance].nielsenTVR.appVersion = @"appVersion";
[ANVConfig sharedInstance].nielsenTVR.isActive = YES;
[ANVConfig sharedInstance].nielsenTVR.sfCode = @"sfCode";
[ANVConfig sharedInstance].nielsenTVR.trackPlayhead = YES;

Parameters in AnvatoConfig/ANVConfig (sharedConfig.nielsenTVR):

Parameter Name Type Description
appID NSString* Unique ID assigned to the player/site and configured by product.
appName NSString* The name of the application.
appVersion NSString* The version of the application.
isActive BOOL Indicating if nielsenTVR is active or not.
sfCode NSString* Unique identifier for the environment that the SDK should point to.
trackPlayhead BOOL Indicating if thacking playhead.

Application Parameters

The application pass no parameters to the SDK regarding the plugin.

Expected behavior

- (IBAction)nielsenButtonClicked:(id)sender
{
if (self.mWebView)
{
[self.mWebView removeFromSuperview];
self.mWebView = nil;
}
else
{
NSString *optOutString = [self.anvatoSDK.nielsenTVR nielsenOptOutUrl];
NSLog(@"OptOutUrl: %@",optOutString);
if (!optOutString)
{
return;
}

NSString *urlAddress = optOutString;
NSURL *url = [[NSURL alloc] initWithString:urlAddress];
NSURLRequest *requestObj = [NSURLRequest requestWithURL:url];

self.mWebView = [[UIWebView alloc] initWithFrame:CGRectMake(0, 70, self.view.frame.size.width, self.view.frame.size.height - 100)];
self.mWebView.scalesPageToFit=YES;
self.mWebView.delegate = self;
[self.mWebView loadRequest:requestObj];
[self.view addSubview:self.mWebView];
}
}

- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
{
NSString *command = [NSString stringWithFormat:@"%@", request.URL];

if ([command isEqualToString:@"nielsen://close"])
{
// Close the webview
[self.mWebView removeFromSuperview];
self.mWebView = nil;
}
[self.anvatoSDK.nielsenTVR setNielsenOptOut:command];
return YES;
}

The Anvato SDK should get the nielsen opt-out url by calling [anvatoSDK.nielsenTVR nielsenOptOutUrl].

Then click the opt-out button on the Webview of opt-out url, the nielsenTVR should opt-out.

After clicking the close button on the Nielsen opt-out webview, the webview should be dismissed.

Disclaimer

Nielsen DTVR Plugin functionality is controlled by Nielsen, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Omniture

Description

The Anvato SDK integrates the Adobe Omniture Library which allows content providers to track various usage metrics. The SDK also allows the app to send custom metadata as part of omniture calls. This can include information such as whether the user is watching the video in fullscreen mode or preview mode, which are not determinable by the SDK but can be set by the Application.

Configuration Parameters

// Enable the omniture plugin
[ANVConfig sharedInstance].omniture.app_name = @"app_name";
[ANVConfig sharedInstance].omniture.isActive = YES;
[ANVConfig sharedInstance].omniture.network = @"network";
[ANVConfig sharedInstance].omniture.pass_network = @"pass_network";
[ANVConfig sharedInstance].omniture.player_name = @"player_name";
[ANVConfig sharedInstance].omniture.player_type = @"player_type";
[ANVConfig sharedInstance].omniture.report_suite_id = @"report_suite_id";
[ANVConfig sharedInstance].omniture.tracking_server = @"tracking_server";

Parameters in AnvatoConfig/ANVConfig (sharedConfig.omniture):

Parameter Name Type Description
app_name NSString* The name of the application.
isActive BOOL Enables or disables the Omniture plugin.
network NSString* Omniture network string.
pass_network NSString* Omniture pass network string.
player_name NSString* The name of the player.
player_type NSString* The type of the player.
report_suite_id NSString* Unique ID assigned to the player/site for report.
tracking_server NSString* Tracking server that the SDK should point to.

Application Parameters

This section describes how the application can pass parameters to the SDK to be bundled as part of the omniture calls made by the SDK in response to playback events.

ANVPlaybackOptions *options = [ANVPlaybackOptions new];
options.userData.mUserDataBundle = @{
                                         @"omniture":@{
                                            @"videoMVPD":@"Cablevision",
                                            @"videoPlayType":@"automatic"
                                         }
                                     };
[self.anvatoSDK.video load:self.channelID withType:ANV_VIDEO_TYPE_MCP withOptions:options];

Omniture can send any key and value which are concerned by the user.

Expected behavior

To check that omniture has been initialized without any issues and is sending event pings, we can do the following:

  1. Filter the device logs by the keyword omniture. This should show whether the SDK was able to initialize omniture with the provided configuration and also the data that is passed to the omniture library for relevant video events.

  2. From the proxy logs (e.g. using HTTP proxy tool such as Charles), an HTTP request going to Omniture Server URL should be sent. Values of the query string parameters should match to those set by the SDK and application.

Charles of Omniture Request

Disclaimer

Adobe Omniture Plugin functionality is controlled by Adobe, Inc. ("3rd Party") Anvato does not accept any responsibility for the plugin. Any technical questions regarding the full functionality of the plugin must be directed to the 3rd Party. You must both have an account with the 3rd Party and enter into a license agreement with the 3rd Party to use this plugin.

Reference Guide

SDK

The SDK can be initialized by providing it with the listeners that will receive the Data and Video Events as described in the Event Flow section. The following methods can be used to initialize the AnvatoSDK.

- (instancetype) initWithDataEventListener:(id )ANVDataEventListener withVideoEventListener:(id)ANVVideoEventListener;

- (instancetype) initWithDataEventListener:(id )ANVDataEventListener withVideoEventListener:(id)ANVVideoEventListener withData:(NSDictionary *)customData;

// Default Initialization of the Anvato SDK with data and video listeners.
self.anvatoSDK = [[ANVSDK alloc] initWithDataEventListener:self withVideoEventListener:self];
// OR
// Initializing Anvato SDK with Data, Video listeners and custom data in the form of a NSDictionary.
self.anvatoSDK = [[ANVSDK alloc] initWithDataEventListener:self withVideoEventListener:self withData:customData];

Method Parameters

Parameter Type nil Description
ANVDataEventListener ANVDataEventListener NO Instance inheritanted protocol ANVDataEventListener
ANVVideoEventListener ANVVideoEventListener NO Instance inheritanted protocol ANVVideoEventListener
customData (optional) NSDictionary NO Setting custom data

Return Value

Returns an Anvato SDK instance if successfully initialized. Returns nil if initialization failed for any reason.

- (void) initPlayerUI:(UIView*) view;

// Initializing Player UI
[self.anvatoSDK initPlayerUI:self.playerView];

When called, the SDK attempts to initialize the Anvato video player UI with the provided UIView.

Method Parameters

Parameter Type nil Description
view UIView NO The video player view.

- (NSDictionary *) handleCustomRequest:(NSString *)key withData:(NSDictionary *) data;

// Handling custom request
[self.anvatoSDK handleCustomRequest:key withData:data];

This is used as a custom communication channel to pass data to the SDK.

Method Parameters

Parameter Type nil Description
key NSString NO Key to add Custom Info into the dictionary.
data NSDictionary NO Custom Info to add into the dictionary

Return Value

Returns NSDictionary of the CustomInfo.

- (NSString *) getVersion;

// Getting SDK version
ANVLogd(TAG, @"| Initializing Anvato IOS SDK: %@",[self getVersion]);

Returns the current version of the Anvato iOS SDK.

Return Value

Returns Version Number as a String.

- (void) close;

// Closing SDK
[self.anvatoSDK close];

Closes the SDK and all the third party tools that have been initialized.

- (void) setLogLevel:(int) logLevel;

// Setting the Log Level
[self.anvatoSDK.video setLogLevel:0];

Sets the Anvato Log Level, so the log verbosity can be changed. 0 represents the highest verbosity while 5 will mute all logs from the SDK. Setting the logger to 4 will show only fatal errors.

Method Parameters

Parameter Type nil Description
logLevel int NO The desired log level between 0-5.

Video API

- (BOOL) load:(NSString *)videoInfo withType:(ANVVideoType)videoType;

// Loading MCP Video
NSString videoID = @"3058548";
[self.anvatoSDK.video load:videoID withType:ANV_VIDEO_TYPE_MCP];

//Loading External Video
NSString *videoURL = @"http://www.anvato.com/sample/bigBuckBunny.m3u8";
NSDictionary *videoInfo = @{@"url":videoURL,@"isVOD":@NO,@"video_format": @"hls"};
[self.anvatoSDK.video load:[ANVUtilFunc Dictionary2JSONStr:videoInfo] withType:ANV_VIDEO_TYPE_MCP_DIRECT];

This Video API call starts loading the requested video. The Video ID is provided along with the video type. Values for video type include 'ANV_VIDEO_TYPE_MCP', 'ANV_VIDEO_TYPE_MCP_DIRECT', 'ANV_VIDEO_TYPE_URL', 'ANV_VIDEO_TYPE_VPAID' and 'ANV_VIDEO_TYPE_UNKNOWN'.

Method Parameters

Parameter Type nil Description
videoInfo NSString NO If type is ANV_VIDEO_TYPE_MCP videoInfo is set to MCP ID.
Otherwise, it is set to JSON String that defines the video information
videoType ANVVideoType NO On of the parameters in ANVVideoType enum defined in ANVGlobals.h

- (BOOL) load:(NSString )videoInfo withType:(ANVVideoType)videoType withOptions:(ANVPlaybackOptions ) options;

// Loading MCP Video
NSString videoID = @"3058548";

// Set required playback options
ANVPlaybackOptions *options = [ANVPlaybackOptions new];
options.video.startFromInSec = 2038;

// Load the video with options
[self.anvatoSDK.video load:videoID withType:ANV_VIDEO_TYPE_MCP withOptions:options];

The Anvato SDK can also use the above method to start loading a video with a given videoType and additional playback options. The ANVPlaybackOptions class defines various video, content properties like allowing the application to set the starting point of playing a VOD, the initial volume of the player, etc. The PlaybackOptions also allows the Application to pass a dictionary to the SDK that can be used by the SDK to procure furter information not available to it. This can be done using the mUserDataBundle dictionary of the userData property of ANVPlaybackOptions.

Method Parameters

Parameter Type nil Description
videoID NSString NO If type is ANV_VIDEO_TYPE_MCP videoInfo is set to MCP ID.
Otherwise, it is set to JSON String that defines the video information
videoType ANVVideoType NO One of the parameters in ANVVideoType enum defined in ANVGlobals.h
options ANVPlaybackOptions YES Additional information to be provided to the Anvato SDK before loading the video.

Return Value

Returns YES if the parameters are NO, false otherwise.

Events Triggered

Type Name Description
DATA ANV_DATA_EVENT_VIDEO_LOAD_SUCCESS Indicates that video load is successful.
DATA ANV_DATA_EVENT_VIDEO_LOAD_FAIL Indicates that video load has failed.

- (BOOL) pause

When called, the SDK attempts to pause video playback.

// Requests the Anvato player to pause playback.
[self.anvatoSDK.video pause];

Return Value

Returns YES if video is currently playing. Otherwise, it will return NO.

Events Triggered

Type Name Description
VIDEO ANV_VIDEO_EVENT_PAUSED Indicates that video has been paused.

- (BOOL) resume

When called, the SDK attempts to resume video playback.

// Resume the video playback.
[self.anvatoSDK.video resume];

Return Value

Returns YES if video is currently paused. Otherwise, it will return NO.

Events Triggered

Type Name Description
VIDEO ANV_VIDEO_EVENT_RESUMED Indicates that video has been resumed.

- (BOOL) seek:(CMTime) time

When called, the SDK attempts to seek the video to the specified time.

// Seeking MCP Video to 120 sec.
[self.anvatoSDK.video seek:CMTimeMake(120, 1)];

Method Parameters

Parameter Type nil Description
time CMTime NO Time in seconds

Return Value

Returns YES if video is successfully sought . Otherwise, it will return NO.

Events Triggered

Type Name Description
VIDEO ANV_VIDEO_EVENT_SEEK_REQUESTED Indicates that video seek is requested.

- (BOOL) stop

When called, the SDK attempts to stop video playback.

// Stop current playback
[self.anvatoSDK.video stop];

Return Value

Returns YES if video is currently stopped. Otherwise, it will return NO.

- (void) setVolume:(float) level

When called, the SDK attempts to set video volume.

// Setting Video Volume
[self.anvatoSDK.video setVolume:self.mVolumeSlider.value];

Method Parameters

Parameter Type nil Description
volume float NO The audio level between 0.0 and 1.0

- (float) getVolume

When called, the SDK attempts to return video volume value.

// Getting current player volume
self.mVolumeSlider.value = [self.anvatoSDK.video getVolume];

Return Value

Returns a float value which is the audio level between 0.0 and 1.0.

- (BOOL) mute

When called, the SDK attempts to mute video playback.

// Muting current video
[self.anvatoSDK.video mute];

Return Value

Returns YES if video is muted. Otherwise, it will return NO.

Events Triggered

Type Name Description
VIDEO ANV_VIDEO_EVENT_MUTE Indicates that video has been muted.

- (BOOL) unmute

When called, the SDK attempts to unmute video playback.

// Unmuting MCP Video
[self.anvatoSDK.video unmute];

Return Value

Returns YES if video is unmuted. Otherwise, it will return NO.

Events Triggered

Type Name Description
VIDEO ANV_VIDEO_EVENT_UNMUTE Indicates that video has been unmuted.

- (NSDictionary*) getStateUpdate

When called, the SDK attempts to get the states of the video playback.

// Get state from SDK
NSDictionary *dictionary = [self.anvatoSDK.video getStateUpdate];

Return Value

Returns NSDictionary of the states.

Events Triggered

Key KeyType ValueTpye Description
playerType NSString NSString Describeing the player type. It is “native” for iOS player, “chromecast” for playing content over chromecast, etc.
numAds NSString Integer Number of ads in an ad-pod (available only during ads.
adIndex NSString Integer Position of the ad in an ad-pod (available only during ads).
adPodDur NSString Integer Duration of the ad pod (available only during ads).
playerName NSString NSString Formed as “ANV SDK Player:[SDK_VERSION]”.
state NSString NSString Describes that state of the video player. Possible values are [“idle” “buffering”, “paused”, “playing”].
videoType NSString NSString Describes the type of the video. Possible values are “vod” for VOD content and “live” for linear streams.
playHeadTime NSString Integer Current playback position of the player in seconds.
duration NSString Integer Duration of the content in seconds.
isAd NSString BOOL TRUE if add is playing FALSE otherwise.

Control Bar

- (void) setVisible:(BOOL)visible

// Set Visibility to NO. Can be used in cases where application might want to show a customized control bar.
[self.anvatoSDK.ui.controlbar setVisible:NO];

Sets the default control bar's visiblility. The application can implement its own control bar and hiding the default control bar by setting visibility to NO.

Method Parameters

Parameter Type nil Description
visible BOOL NO Indicate if set control bar visible or not

- (void) setAutoHideInterval:(NSTimeInterval)interval

//Set the control bar visibility interval to 20 seconds.
[self.anvatoSDK.ui.controlbar setAutoHideInterval:20.0];

Defines the amount of time, in seconds, that the control bar is to be shown when the user taps on the player view. After the time is elapsed, the control bar is hidden.

Method Parameters

Parameter Type nil Description
interval NSTimeInterval NO Indicate if set control bar visible or not

UI API

- (void) hideFullScreen:(BOOL)hide


[self.anvatoSDK.ui hideFullScreen:YES];

Hides full screen button in control bar.

Method Parameters

Parameter Type nil Description
hide BOOL NO Indicate if hide full screen button or not

- (void) expandVideoAspect:(BOOL)expand

//Sets Aspect Ratio to fill the screen if set to YES. Resizes the aspect ration when turned off. 
[self.anvatoSDK.ui expandVideoAspect:YES];

This method when called with expand set to TRUE, will change the aspect ratio of the video to fill up the player view. Similarly on setting this to NO, it will resize the video to go to default aspect ratio of the video. This is used as a reaction to a double tap by the user which 'zooms -in/out' the video.

Method Parameters

Parameter Type nil Description
expand BOOL NO Indicate if expand video aspect or not

- (void) setCaptions:(BOOL)isEnabled

//Setting setCaptions to TRUE will turn on the closed captions for the current video.
[self.anvatoSDK.ui setCaptions:YES];

Sets Closed Captions to be shown or not.

Method Parameters

Parameter Type nil Description
isEnabled BOOL NO Indicate if set closed captions or not

- (BOOL) updatePlayerView:(UIView *)view

//Sets the player to an updated UIView
[self.anvatoSDK.ui updatePlayerView:[[UIView alloc] initWithFrame:CGRectMake(0, 0, self.view.bounds.size.width, self.view.bounds.size.height-100)]];

Updates the players UIView with the given view. This is used by the application to resize the player so as to customize the position and size of the player.

Method Parameters

Parameter Type nil Description
view UIView NO The new player view

Return Value

Returns YES if player view is updated. Otherwise, it will return NO.

- (BOOL) updatePlayerView:(UIView *)view isFullScreen:(BOOL)isFull

//Sets the player to an updated UIView and lets the SDK know that player is now playing in fullscreen mode
[self.anvatoSDK.ui updatePlayerView:[[UIView alloc] initWithFrame:CGRectMake(0, 0, self.view.bounds.size.width, self.view.bounds.size.height-100)] isFullScreen:YES];

Updates the players UIView with the given view. While this is similar to the function above, it also notifies the SDK that it is currently been set to be in fullscreen.

Method Parameters

Parameter Type nil Description
isFull(optional) BOOL NO if the new player view is on full screen

Return Value

Returns YES if player view is updated. Otherwise, it will return NO.

- (BOOL) isPipModeAvailable

Check if Picture in Picture Mode is available for the given device. Picture in Picture is supported in all iPads with iOS greater than 9.0

//Returns whether Picture in Picture can be enabled or not
[self.anvatoSDK.ui isPipModeAvailable];

Return Value

Returns YES if Picture in Picture is available on current device. Otherwise, it will return NO.

- (void) setPiPMode:(BOOL) enable

Setting this method to true starts Picture in Picture(PiP) feature on a PiP-able device. Only iPads above iOS9 are currently supporting Picture in Picture

//Starting Picture in Picture
[self.anvatoSDK.ui setPiPMode:YES];

Events Triggered

Type Name Description
VIDEO ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_WILL_START Indicates that PiP mode is about to begin
VIDEO ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_STARTED Indicates that video is playing in PiP mode
VIDEO ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_WILL_END Indicates that PiP mode is about to close
VIDEO ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_ENDED Indicates that PiP mode has been closed
VIDEO ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_ERROR Indicates that PiP mode had to be terminated because of an error.

Chromecast API

-(void) connect:(NSString *)deviceName

//Connect to device named 'TestAnvato1'
[self.anvatoSDK.ccast connect:@"TestAnvato1"];

Connects to a given deviceName. The Application can call this method to connect to one of the devices listed in the ANV_VIDEO_EVENT_CAST_DEVICE_LIST bundle.

Method Parameters

Parameter Type nil Description
deviceName NSString NO The name of the device to be connected

-(void) disconnect

//Disconnect current device
[self.anvatoSDK.ccast disconnect];

Disconnectes from the current chromecast connection

-(BOOL) isConnected

//Returns status of chromecast connection
BOOL status = [self.anvatoSDK.ccast isConnected];

Returns the current status of the Chromecast

Return Value

Returns

-(void) setVolume:(float) vol

// Sets the volume of the chromecast player. Value should be between 0.0 (Muted) to 1.0 (Full Volume).
[self.anvatoSDK.ccast setVolume:1.0];

Sets the volume to currently connected Chromecast device

Method Parameters

Parameter Type nil Description
vol float NO The volume level to be set for the chromecast player

-(float) getVolume

// Returns the current volume of the chromecast player
[self.anvatoSDK.ccast getVolume];

Returns the volume for currently connected Chromecast device

Return Value

Returns float value between 0.0 to 1.0 representing the current volume of the chromecast player.

-(BOOL) anvConnect:(NSString )anvack withAnvSec:(NSString )seckey

//Connect to chromecast device with your given anvack and sec key.
[self.anvatoSDK.ccast anvConnect:@"YOUR_ANVACK_KEY" withAnvSec:@"YOUR_SEC_KEY"];

Method Parameters

Parameter Type nil Description
anvack NSString NO The client specific anvack key provided by Anvato
seckey NSString NO The client specific seckey provided by Anvato

Return Value

Returns YES if the SDK is able to connect to the chromecast device, NO otherwise.

+(NSString ) getChromecastVerificationPayloadWithAppKey:(NSString )anvack withSeckey:(NSString *)seckey

Method Parameters

Parameter Type nil Description
anvack NSString NO

Return Value

+(NSMutableDictionary ) getChromecastVideoPayload:(NSString )appKey withToken:(NSString )token withMcpVideoID:(NSString )mcpID

Method Parameters

Parameter Type nil Description
anvack NSString NO

Return Value

Adobe API

-(BOOL) setSelectedProvider:(NSString *)mvpdID

[self.anvatoSDK.adobepass setSelectedProvider:@"TempPass-LongTTL"];

Method Parameters

Parameter Type nil Description
mvpdID NSString NO The MVPD ID of the user

Return Value

-(BOOL) getAuthNTTL

[self.anvatoSDK.adobepass getAuthNTTL];

Initiates the login process, fires ANV_DATA_EVENT_ADOBE_AUTHN_MVPDID if user is authenticated and ANV_DATA_EVENT_ADOBE_MVPD_PICKER_NEEDED otherwise

Events Triggered

Type Name Description
DATA ANV_DATA_EVENT_ADOBE_AUTHN_MVPDID Indicates that the user is authenticated.
DATA ANV_DATA_EVENT_ADOBE_MVPD_PICKER_NEEDED Indicates that the user is not authenticated and the application should show the MVPD picker view.

Return Value

-(BOOL) login

[self.anvatoSDK.adobepass login];

Initiates the login process, fires ANV_DATA_EVENT_ADOBE_AUTHN_MVPDID if user is authenticated and ANV_DATA_EVENT_ADOBE_MVPD_PICKER_NEEDED otherwise

Return Value

-(BOOL) logout

[self.anvatoSDK.adobepass logout];

Tries to log the user out. Fires ANV_DATA_EVENT_ADOBEPASS_USER_LOGGED_OUT with mvpdID set the nil when complete

Return Value

-(BOOL) checkAuthN

[self.anvatoSDK.adobepass checkAuthN];

Checks if user is authenticated. fires ANV_DATA_EVENT_ADOBE_AUTHN_SUCCESS if user is authenticated, ANV_DATA_EVENT_ADOBE_AUTHN_FAIL otherwise.

Return Value

-(BOOL) checkAuthNWithCallback:(ANVCallback) callback

[self.anvatoSDK.adobepass checkAuthNWithCallback:^(ANVEventBundle *bundle) {
    if (bundle != nil )
    {
        NSLog(@"%@",[bundle getDictionary]);
    }
}];

Checks if user is authenticated. fires ANV_DATA_EVENT_ADOBE_AUTHN_SUCCESS if user is authenticated, ANV_DATA_EVENT_ADOBE_AUTHN_FAIL otherwise.

Method Parameters

Parameter Type nil Description
callback ANVCallback NO

Return Value

-(BOOL) getMvpdID

[self.anvatoSDK.adobepass getMvpdID];

Returns the mvpd id of an authenticated user. Fires ANV_DATA_EVENT_ADOBEPASS_AUTHN_MVPDID

Return Value

-(BOOL) getMvpdIDWithCallback:(ANVCallback) callback

[self.anvatoSDK.adobepass getMvpdIDWithCallback:^(ANVEventBundle *bundle) {
    if ( bundle != nil)
    {
        NSLog(@"%@",[bundle getDictionary]);
    }
}];

Returns the mvpd id of an authenticated user. Fires ANV_DATA_EVENT_ADOBEPASS_AUTHN_MVPDID

Method Parameters

Parameter Type nil Description
callback ANVCallback NO

Return Value

-(BOOL) getHomeZip

[self.anvatoSDK.adobepass getHomeZip];

Return Value

-(BOOL) getHomeZipWithCallback:(ANVCallback) callback

[self.anvatoSDK.adobepass getHomeZipWithCallback:^(ANVEventBundle *bundle)callback{
    if ( bundle != nil)
    {
        NSLog(@"%@",[bundle getDictionary]);
    }
}];

Method Parameters

Parameter Type nil Description
callback ANVCallback NO

Return Value

-(BOOL) getAuthZ

[self.anvatoSDK.adobepass getAuthZ];

Performs authZ check, uses ANVConfig.adobepass.resource_id as the resource.

Return Value

-(BOOL) getAuthZWithResource:(NSString *) resource

[self.anvatoSDK.adobepass getAuthZWithResource:@"Cablevision"];

Performs authZ check, uses the argument as the resource.

Method Parameters

Parameter Type nil Description
resource NSString NO

Return Value

-(BOOL) getAuthZWithResource:(NSString *) resource withCallback:(ANVCallback)callback

[self.anvatoSDK.adobepass getAuthZWithResource:@"Cablevision" withCallback:^(ANVEventBundle *bundle) {
    if ( bundle != nil)
    {
        NSLog(@"%@",[bundle getDictionary]);
    }
}];

Performs authZ check, uses the argument as the resource and returns with callback

Method Parameters

Parameter Type nil Description
resource NSString NO
callback ANVCallback NO

Return Value

-(BOOL) getMaxRating

[self.anvatoSDK.adobepass getMaxRating];

Return Value

Nielsen TVR API

-(NSString *) nielsenOptOutUrl;

// Get the nielsen opt out URL to navigate the user to nielsens web page in case they want to opt out of Nielsen tracking
NSString *optouturlString = [self.anvatoSDK.nielsenTVR nielsenOptOutUrl];

Calling the nielsenOptOutUrl method of the nielsenTVR object returns a NSString which is the URL to direct the user to in case the user decides to opt out of Nielsen tracking. This method shouyld be called in response to the user clicking on the opt out button. On getting this string, the URL should be loaded in a UIWebView.

-(void) setNielsenOptOut:(NSString *)command;

// Call this with the response of the web page command. 
[self.anvatoSDK.nielsenTVR setNielsenOptOut:command];

Calling the 'setNielsenOptOut' method of the nielsenTVR object provides the response of the web page that was shown to the user. In case the response is nielsen://close, simply close the web view as the user simply chose to cancel the page and remain in previous state.

Method Parameters

Parameter Type nil Description
command NSString NO The response command from the webpage used to describe the nielsen opt-out/opt-in page.

Release Notes

Version 5.0.27

ANV_VIDEO_EVENT_VIDEOVIEW_CLICKED_CANCEL

New Video Event Added

Added Video Event which is fired when the user dismisses the default dialog box appearing on an ad click through.

Version 5.0.26

Live Manifest Error not considered Fatal

Getting 403's/404's on manifest requests is no longer considerer FATAL for the Live stream and the player is more resilient to network/server errors.

Version 5.0.25

Resizing Vpaid Ad when player view changes

Updating the player's view also updates the VPAID ad's view in case the player is currently in a VPAID Ad.

Version 5.0.24

Updated IMA Ad Experience

IMA Ad Player architecture has been changed to consistently play preroll before content starts. IMA midrolls are disabled for now. Also added ability to turn on Open Measurement in IMA SDK.

Version 5.0.23

Updated IMA Ad Experience

This update includes fixes to IMA player to connect with Pause/Resume Anvato API. Also added changes to IMA player to resume when foregrounded.IMA Player now honors the same volume as the anvato player.

Version 5.0.22

General bug fixes and enhancements performed.

Version 5.0.21

General bug fixes and enhancements performed.

Version 5.0.20

General bug fixes and enhancements performed on client side ad experience.

Version 5.0.19

Adobe Heartbeat 2.0 Plugin added

 [ANVConfig sharedInstance].heartbeat.isHb2Enabled = YES;

The Adobe Heartbeat version 2.0 has been implemented as part of the Anvato iOS Player SDK and can be enabled by accessing the isHb2Enabled and setting it to YES.

Version 5.0.18

Added Configuration to disable external playback on Airplay

[ANVConfig sharedInstance].video.allowsAirplayExternalPlayback = NO;

Added configuration parameter allowsAirplayExternalPlayback to indicate if blocking direct airplay video. Please note that this only disables the video and does not disable audio playback.

Version 5.0.17

Conviva Plugin Enabled

[ANVConfig sharedInstance].conviva.isActive = YES;
[ANVConfig sharedInstance].conviva.customerKey = @"CUSTOMER_KEY";
[ANVConfig sharedInstance].conviva.gatewayUrl = @"GATEWAY_URL";
[ANVConfig sharedInstance].conviva.logLevel = 0;    //Optional

As part of this release, the Conviva plugin has been integrated as part of the Anvato SDK. The plugin itself is weakly linked thereby enabling the application to use the appropriate version. Currently it supports upto v.2.141.0.

Version 5.0.13

Disable default buffering spinner

[ANVConfig sharedInstance].ui.enableLoadingSpinner = NO;

The Buffering/Loading spinner can now be disabled such that the Application can show their own spinner during buffering start/end as well as when video is being loaded. By default this is set to YES thereby showing the default spinner wheel.

Passing metadata to chromecast

ANVPlaybackOptions *options = [ANVPlaybackOptions new];
options.userData.mChromecastUserDataBundle =
    @{
          @"videoPlayerName":@"Anvato Chromecast Player",
    };

The SDK is now capable of sending chromecast related metadata to chromecast thereby separating the analytics being sent from chromecast and that from the mobile SDK's. This works in conjunction with the Anvato derived metadata solution. Beware the metadata sent from player will overwrite the default derived metadata sent from backend.

Version 5.0.12

General bug fixes and enhancements.

Version 5.0.11

New Closed Captions Language List API

// Lists all the captions languages available in Manifest
[self.anvatoSDK.ui getCaptionsLanguageList];
//Requests player to set captions to a particular language
[self.anvatoSDK.ui setCaptionsLanguage:@"en"];

Exposed APIs to display and select different closed caption tracks as declared in the master manifest. The setCaptionsLanguage API accepts a string that will enable the player to show a particular captions as long as the provided string is amongst the options returned in getCaptionsLanguageList method.

Anvato iOS v4 Release Notes

Version 4.1.8

Nielsen ­ DCR & DTVR Play content and Tracking

-(NSString *) nielsenOptOutUrl;
-(void) setNielsenOptOut:(NSString *)command;
//Get the nielsen optout URL and show it to the user in a web view.object
[self.anvatoSDK.nielsenTVR nielsenOptOutUrl]
// If the user chooses to opt out of the tracking, send the command to the nielsenTVR 
[self.anvatoSDK.nielsenTVR setNielsenOptOut:@"nielsen://close"]

The Joint Adobe Nielsen DCR and DTVR plugin has been implemented as part of the Anvato SDK. Nielsen allows users to Opt­Out of Nielsen tracking. To achieve this, the application needs to display the nielsen Opt­Out page where the user understands the terms and accepts to either opt­out or opt­in to the Nielsen Analytics. To fetch the URL, that sends the user to Nielsen’s Opt Out page, the application can access the ‘nielsenOptOutUrl’ parameter under the NielsenTVR namespace in the ANVSDK object.

Similarly the application can listen to the user’s actions on the Nielsen Opt­out page and pass on the command to the SDK using the ‘setNielsenOptOut’ method.

Sample code to fetch nielsen optout URL as well as to pass command to the nielsen plugin in the SDK is as follows.

Version 4.1.5

Akamai QoS Plugin added

The SDK now supports Akamai QoS plugin. The SDK also allows both the backend (using derived metadata) and the application to pass custom key value pair (see the following section).

Override default Ad Click Pop up

@property (nonatomic, assign) BOOL enableAdClickPopup;

The application has the ability to disable the default behavior of the SDK for handling the event of tapping on an advertisement with web links. Starting with version 4.1.5, the ANVConfig object project the following variables under 'ui' namespace.

If enableAdClickPopup parameter is set to NO, then the SDK does not render the popup message, allowing the application to render a customized UI component. In case the default behavior of the SDK is disabled, it becomes the application's responsibility to fire the appropriate beacons to track user's interaction. Also the application is responsible for showing the associated click-through web page to the user.

Version 4.1.4

Nielsen Heartbeat Joint SDK Implementation

The SDK now supports the Nielsen DCR by Heartbeat-­Nielsen joint SDKs.

Picture in Picture

//enablePiP must be configured to True for PiP mode to work.
[ANVConfigsharedInstance].ui.enablePiP = true;

SDK supports the Picture in Picture feature on available devices. This feature is disabled by default and can easily be enabled by the configuration.

//Sets PiP mode on.
[sdk.ui setPiPMode:true];
//Disables PiP mode.
[sdk.ui setPiPMode:false];

This needs to be done before the construction of the Anvato SDK. Once enabled, the application can easily enter/exit the PIP mode using the setPiPMode methods.

// SDK will return YES if the device supports Picture In Picture. Genrally PiP is only avaialble for iOS 9.0 and above on iPad's 
[sdk.ui isPipModeAvailable];

The application can also check the availability of the PiP, using the isPipModeAvailable method in the UI namespace of the AnvatoSDK object.

When switching between modes, Anvato iOS SDK fires the following events to notify the application about the state of the PiP.

Event Name Description
ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_WILL_START Notifies that PiP is about to start.
ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_STARTED Notifies that PiP has started.
ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_WILL_END Notifies that PiP is about to end.
ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_ENDED Notifies that PiP has ended.
ANV_VIDEO_EVENT_PICTURE_IN_PICTURE_ERROR Notifies that PiP has failed due to error.

Version 4.0.23

Custom Ad Views

// SDK will should not display more info button for digital ads. 
[ANVConfig sharedInstance].ui.enableAdWebView = false; 

The SDK allows the application to render webviews during advertisement if the DAI ad has clickthru URL. This can be configured from the ANVConfig object, by setting enableAdWebView to false under ui namespace.

Version 4.0.20

Video Load Fail Details

// Application Code
- (void) onDataEvent:(ANVDataEvent)event bundle:(ANVEventBundle *)bundle
{

    if ( event == ANV_DATA_EVENT_VIDEO_LOAD_FAIL )
    {
        int errorType = (int)[bundle getI:@"errorType"];
        if ( errorType == ANV_VIDEO_LOAD_FAIL_TYPE_ADOBEPASS_AUTHN )
        {
            //  Adobepass Authentication failure. show picker???
        }
    }
}

...

// ANVGlobals.h
typedef NS_ENUM(NSInteger, ANVVideoLoadFailType)
{
    ANV_VIDEO_LOAD_FAIL_TYPE_ADOBEPASS_AUTHN = -101,
    ANV_VIDEO_LOAD_FAIL_TYPE_ADOBEPASS_AUTHZ = -102,
    ANV_VIDEO_LOAD_FAIL_TYPE_ADOBEPASS_PARENTAL = -103,
    ANV_VIDEO_LOAD_FAIL_TYPE_ANVATO_HOMEZIP_RESTRICTION = -201,
    ANV_VIDEO_LOAD_FAIL_TYPE_ANVATO_GEOZIP_RESTRICTION = -202, 
    ANV_VIDEO_LOAD_FAIL_TYPE_ANVATO_MVPD_RESTRICTION = -203,
    ANV_VIDEO_LOAD_FAIL_TYPE_ANVATO_CHANNEL_RESTRICTION = -204,
    ANV_VIDEO_LOAD_FAIL_TYPE_ANVATO_DEVICE_RESTRICTION = -205,
    ANV_VIDEO_LOAD_FAIL_TYPE_DEVELOPER = -301, 
    ANV_VIDEO_LOAD_FAIL_TYPE_NETWORK_FAILURE = -999,
};

The SDK provides detailed information about the nature of failure for a video load request. SDK fires ANV_DATA_EVENT_VIDEO_LOAD_FAIL data event. The bundle contains details of the error fields.

errorType is an integer value from ANVVideoLoadFailType enumeration defined in ANVGlobals.h.
msg is a string value that describes the issue for the application developer.
The video load fail type enum is provided below.

Version 4.0.18

Akamai QoS

[ANVConfig sharedInstance].akamaiQoS.isActive = YES;
[ANVConfig sharedInstance].akamaiQoS.configUrl = [CONFIG_URL];
[ANVConfig sharedInstance].akamaiQoS.viewerId = [VIEWER_ID];

Akamai QoS support has been added. Using the SDK v4.0.18, your backend configuration can be updated to enable this plugin. The plugin can also be enabled from the application side using ANVConfig object. The fields that you need provide is

Version 4.0.16

Temppass flow for AdobePass

The SDK provides the authentication expiration date when the user is logged in using a temppass credential. This information is notified using ANV_DATA_EVENT_ADOBEPASS_AUTHENTICATION_TTL event on onDataEvent callback.

- (void) onDataEvent:(ANVDataEvent)event bundle:(ANVEventBundle *)bundle
{
    if ( event == ANV_DATA_EVENT_ADOBEPASS_AUTHENTICATION_TTL )
    {
        NSLog(@"Stream will expire on %@",[bundle getS:@"temppassdate"]);
    }
}

Version 4.0.14

Adobe Heartbeat

[ANVConfig sharedInstance].heartbeat.isActive = YES; 
[ANVConfig sharedInstance].heartbeat.tracking_server = @"SERVER_URL"; 
[ANVConfig sharedInstance].heartbeat.job_id = @"JOB_ID"; 
[ANVConfig sharedInstance].heartbeat.channel = @"CHANNEL"; 

The support for AdobeHeartbeat is added. Using the SDK v4.0.14, your backend configuration can be updated to enable this plugin. The plugin can also be enabled from the application side using ANVConfig object. The fields that you need provide is

Version 4.0.10

Enhanced User Info Support

[ANVConfig sharedInstance].nielsenOCR.isActive = YES;
[ANVConfig sharedInstance].nielsenOCR.c9 = @"[Optout]";
[ANVConfig sharedInstance].comscoreVCE.device = @"[Device]";
[ANVConfig sharedInstance].comscoreVCE.isActive = YES;
[ANVConfig sharedInstance].comscoreVCE.device = @"[Device]";
[ANVConfig sharedInstance].openPixel.isActive = YES;
[ANVConfig sharedInstance].openPixel.dvApp = @"[Your Dev App]";

The application can provide more information about the user. These new features are listed as follows.

Version 4.0.7

AdobePass flow has been added. Please check the Entitlements page for more details.

Version 4.0.6

ComscoreVCE, NielsenOCR, OpenPixel Support

[ANVConfig sharedInstance].nielsenOCR.isActive = YES;
[ANVConfig sharedInstance].nielsenOCR.c9 = @"[Optout]";
[ANVConfig sharedInstance].comscoreVCE.device = @"[Device]";
[ANVConfig sharedInstance].comscoreVCE.isActive = YES;
[ANVConfig sharedInstance].comscoreVCE.device = @"[Device]";
[ANVConfig sharedInstance].openPixel.isActive = YES;
[ANVConfig sharedInstance].openPixel.dvApp = @"[Your Dev App]";

The SDK has started to support new plugins, ComscoreVCE, NielsenOCR and OpenPixel. The application can configure these plug'ins using the ANVConfig object.

Version 4.0.5

Airplay Notification

- (void) onVideoEvent:(ANVVideoEvent)event bundle:(ANVEventBundle *)bundle
    {
    if ( event == ANV_VIDEO_EVENT_AIRPLAY_START )
    {
        // Update the UI to notify the user that the video is being airplayed.
    }
    else if ( event == ANV_VIDEO_EVENT_BUFFERING_COMPLETED )
    {
        // Undo UI update
    }
}

The SDK now notifies the application when Airplay session starts and ends. This is notified using onVideoEvent callback.

Version 4.0.4

Access Control

Application can specify when and which access controls needs to be specified. There are listed as follows.

[ANVConfig sharedInstance].accessConfig.onStartAuthZ = YES;
[ANVConfig sharedInstance].accessConfig.onTuneAuthZ = YES;
[ANVConfig sharedInstance].accessConfig.onStartTVE = YES;
[ANVConfig sharedInstance].accessConfig.onTuneTVE = YES;