iOS Integration Guide

Introduction

This is a guide to help you integrate Streamlyzer iOS plug-in to your iOS application.

Requirements

  • Xcode 7.1 or later
  • Add the “NSAppTransportSecurity” key on your info.plist file to allow http requests.

31883299

Observers and Properties

Overview

There are 4 types of events to track (aka Observer components),

  • playbackObserver for tracking media playback.
  • userDefinedObserver for tracking user defined events.
  • sharedContentObserver for tracking sharing contents.
  • pageReferrerObserver for tracking page referrer.

Prior to initialization of Observers, you need to set properties as it needs. For your convenience, we group them into 5 categories. Depending on which observers you use, some of properties are required and some of them could be optional.

  • Audience properties
  • Content properties
  • Service properties
  • Platform properties
  • Customer properties

Properties

Audience properties
Variables Default Required Description
userId ‘Unset’ O User Unique ID. You should specify user unique id for each users. It shall be unique string or e-mail address or user id. It should be unique string so that data can be grouped by user id.
userType ‘Unset’ User Type. You can define the type of user. For example, “free user”, “non-free user” or “premium”.
gender ‘Unset’ User’s Gender. For example, “male” or “female”.
yearOfBirth ‘Unset’ User’s year of birth. This is for calculating user’s age. For example, “1995”.
Content properties
Variables Default Required Description
thumbnailImage ‘Unset’ URL of thumbnail image. You can specify thumbnail image of the contents. This thumbnail url will be used for displaying thumbnail image on Dashboard
seriesName ‘Unset’ Series name of movie. You can define series name of asset. For example, “Heroes”, “House of Cards”
episodeName ‘Unset’ Season/Episode name of movie. User can define Episode information into log. For example, Season 1 Episode 10 shall be “S1:E10”.
liveChannelName ‘Unset’ Live channel Name. If the media is not a live channel, you can input the movie id.
movieId ‘Unset’ O Movie ID. The tile of movie. This should be unique string so that metrics will be grouped by movie id.
movieCategory ‘Unset’ O Movie Category. You can define unique key string for grouping movie category. For example, this value can be “drama”, “comedy”, “horror” or “anime”.
movieSubcategory ‘Unset’ Movie Subcategory. You can define unique key string for grouping movie subcategroy. For example, this value can be “romantic drama”,”crime drama”, classic drama” or “teen drama”.
movieContentsProvider ‘Unset’ Movie Content providers. User can define unique key string for grouping contents providers. For example, this value can be “abc”, “desiney”, “time wanner”, “kbs” and so on.
movieRate ‘Unset’ Movie Rate. You can define movie rate. For example, “R”, “PG-13”, “PG”
Service properties
Variables Default Required Description
live false O Is Live Service or not. If the service is Live, it shall be true, If not, it shall be false. For example, if the content is VOD, it shall be “false”.
serviceType ‘Unset’ Serivce Type. You can define the type of service. For example, “TV” or “Radio”.
sessionId ‘Unset’ O Session ID. You could set session id based on each session.
streamingServerName ‘Unset’ O You can specify streaming server URL or CDN urls. It can be used for metrics grouped by streaming edge.
abTestMark ‘Unset’ O A/B test mark. This for A/B testing. You can put “A” or “B” or other unique string for A/B testing.
Platform properties
Variables Default Required Description
playerPlatformVersion ‘Unset’ O Player Platform Version. You can define user specific version information to group data. For example, you can specify player version information such flash 7, flash 8
mediaPlayerVersion ‘Unset’ O Media Player Version. You can define user specific version information to group data. For example, you can specify player version information such as jwplayer 7.5, jwplayer 9.8
Customer properties
Variables Default Required Description
customerKey ‘Unset’ O Customer Key. This value is given by Streamlyzer. It is used for identifying logs you send. The log with invalid key value will be rejected.

Observers

Common

Description

For all observes, below three steps should be taken to set up properties.

  1. Initialize plug-in
  2. setProperties
  3. Close plug-in

// Initialize plug-in
[StreamlyzerPlugin initPlugin];

// Set properties
[szrEvent setProperties:<Dictionary>];

// close plug-in
[szrEvent closeObserver];

playbackObserver

Description
Playback Observer will be attached with media player, and monitor playback event based on user’s interaction.

How to initialize
To initialize PlaybackObserver, you should set up 3 things,
1. Initialize plug-in
2. Initialize playbackObserver
3. Set proper properties on the Observer.

First, initialize plug-in and the observer and provide all of the required properties:


```objective-c
// Initialize plug-in
[StreamlyzerPlugin initPlugin];

// Initialize playbackObserver
SZRPlaybackObserver *szrEvent = [[SZRPlaybackObserver alloc] init];

// Set properties
[szrEvent setProperties:@{
    // key provided by Streamlyzer
    SZR_CUSTOMER_KEY : @"<Key Provided by Streamlyzer>"

    // end user related properties
    , SZR_USER_ID : @"<User ID>"
    , SZR_USER_TYPE : @"<User Type>"
    , SZR_GENDER : @"<User Gender>"   /* SZR_VALUE_GENDER_FEMALE or SZR_VALUE_GENDER_MALE */
    , SZR_YEAR_OF_BIRTH : @"<User Year of Birth>"

    // service related properties
    , SZR_SERVICE_TYPE : @"<Service Type>"
    , SZR_SESSION_ID : @"<Session ID>"
    , SZR_STREAMING_SERVER_NAME : @"<Streaming Server Name>"  /*Server name or source URL */
    , SZR_ABTEST_MARK : @"<AB Test Marking>"

    // platform related properties
    , SZR_PLATFORM_NAME : @"<Apple iOS>"
    , SZR_APPLICATION_NAME : @"<Streamlyzer Example Application>"                           
    , SZR_APPLICATION_VERSION : @"<0.9.x.0>"
    , SZR_PLAYER_PLATFORM_VERSION : @"<MPMoviewPlayer>"
    , SZR_MEDIA_PLAYER_VERSION : @"<Streamlyzer Example VideoPlayer 0.9.x.0>"

    // contents related properties
    , SZR_LIVE : SZR_VALUE_LIVE_TRUE        /* SZR_VALUE_LIVE_TRUE or SZR_VALUE_LIVE_FALSE */
    , SZR_MOVIE_ID : @"<Movie ID>"
    , SZR_MOVIE_CATEGORY : @"<Movie Category>"
    , SZR_LIVE_CHANNEL_NAME : @"<Live Channel Name>"
    , SZR_BIT_RATE : @320   /* bitrate in kbs */
    , SZR_RESOLUTION : @"720p"  /* resolution */
    , SZR_MOVIE_SUBCATEGORY : @"<Movie Subcategory>"
    , SZR_MOVIE_CONTENTS_PROVIDER : @"<Movie Contents Provider>"
    , SZR_MOVIE_RATE : @"<Movie Rate>"
    , SZR_SERIES_NAME : @"<Series Name>"
    , SZR_EPISODE_NAME : @"<Episode Name>"
    , SZR_THUMBNAIL_NAME : @"<Movie Thumbnail Image>" /* Thumbnail URL */
}];

Implement protocol SZRPluginPlaybackEventDelegate

The plug-in will call these methods to collect media status during playback.

Function Signiture Default Return Description
getPosition 0 It gets called to get the current position of media file. It can be the absolute position in millisecond unit.The return value should be Number, not String.
getBitrate 0 If there is any bitrate or video quality info available, this has to return current video bitrate in kbps (kilobits per seconds). For example, if current bitrate is “256kbps”, you should return “256”. The return value should be Number, not String.
getResolution nil It returns video resolution. This method works with setProperty.
getDuration 0 It returns the total length in millisecond of the viewed media file. The return value should be Number, not String.

Event API for tracking AVPlayer

Function Signiture Description
setAVPlayerItemCB It is called when the play item is set (AVPlayer Item observer is set).
resetAVPlayerItemCB It is called when the play item removed (AVPlayer Item observer is removed) from player.
AVPlayerObserverCB It is called when the AVPlayer state is changed (Usually called from AVPlayer observer).
AVPlayerItemObserverCB It is called when the AVPlayer Item state is changed (Usually called from AVPlayerItem observer).
AVPlayerAccessLogCB It is called when new access log added.
AVPlayerItemFailedToPlayToEndTimeNotificationCB It is called when the player is finished with error.

Event API for tracking media player

Function Signiture Description
onPlayerLoad It is called when the player is loaded.
onPlayerReady It is called when the player is ready to playback.
onPlayerItemSet It is called when the player item is set.
onPlayerError It is called when getting playback error, any your defined error, or buffering time limit exceeded. Streamlyzer will count the number of errors or categorize errors with error message. error message has to be passed as the argument NSError.
onChangeChannel It is called when channel is changed.
onPlayerStateUpdateGP It is called when playback state or load state (=buffer state) is updated.
onPlayerIsPreparedToPlayNotificationGP It is called when playback is loaded to play.
onPlayerFinishWithError It is called when the player is finished with error.Example for AVPlayer

Here is an example with AVPlayer class.


szrEvent = [[SZRPlaybackObserver alloc] init];
[szrEvent setProperties:<Dictionary>];

szrEvent.delegate = self;

// call onPlayerLoad before init player
[szrEvent onPlayerLoad:SZRPlayerTypeAVPlayer];         
// call onPlayerReady after init Player
[szrEvent onPlayerReady];                              

// set AVPlayer Observer
[szrEvent AVPlayerObserverCB:keyPath withRate:__AVPLAYER__.rate withStatus:__AVPLAYER__.status];

// set AVPlayer Item Observer
[szrEvent AVPlayerItemObserverCB:keyPath withPlaybackLikelyToKeepUp:__AVPLAYER_CURRENTITEM__.playbackLikelyToKeepUp
                  withPlaybackBufferFull:__AVPLAYER_CURRENTITEM__.playbackBufferFull withPlaybackBufferEmpty:__AVPLAYER_CURRENTITEM__.playbackBufferEmpty];

// set AVPlayer Item Observer
[szrEvent AVPlayerItemFailedToPlayToEndTimeNotificationCB:notification withKey:AVPlayerItemFailedToPlayToEndTimeErrorKey];


// set AVPlayer Access Log Callback
[szrEvent AVPlayerAccessLogCB:__AVPLAYER_ACCESS_LOG__.URI
                 withPlaybackType:__AVPLAYER_ACCESS_LOG__.playbackType
                withSwitchBitrate:__AVPLAYER_ACCESS_LOG__.switchBitrate
              withObservedBitrate:__AVPLAYER_ACCESS_LOG__.observedBitrate
             withIndicatedBitrate:__AVPLAYER_ACCESS_LOG__.indicatedBitrate];

// set AVPlayer Item Callback
[szrEvent setAVPlayerItemCB];

// reset AVPlayer Item Callback
[szrEvent resetAVPlayerItemCB];
// call onChangeChannel after changing contents
[szrEvent onChangeChannel];

// implement protocol delegate methods
- (NSInteger) getPosition;
- (NSInteger) getBitrate;
- (NSString *) getResolution;
- (NSInteger) getDuration;

// to release plug-in resources
[szrEvent closeObserver];

Example for Generic Player (including MPMoviePlayer)

Here is an example with MPMoviePlayer class.


szrEvent = [[SZRPlaybackObserver alloc] init];
[szrEvent setProperties:<Dictionary>];

szrEvent.delegate = self;

// call onPlayerLoad before init player
[szrEvent onPlayerLoad:SZRPlayerTypeMPMoviePlayer];

// call onPlayerReady after init Player
[szrEvent onPlayerReady];                              

// call onPlayerItemSet before updating contents URL
[szrEvent onPlayerItemSet];


// set callback methods for finish with error
[szrEvent onPlayerFinishWithError:[[notification userInfo] objectForKey:@"error"]];

// set callback methods for state update (playback state, load state)
[szrEvent onPlayerStateUpdateGP:__CURRENT_MOVIE_PLAYER_CONTROLLER__.playbackState withLoadState:__CURRENT_MOVIE_PLAYER_CONTROLLER__.loadState];

// set callback methods for play ready
[szrEvent onPlayerIsPreparedToPlayNotificationGP];

// call onChangeChannel after changing contents
[szrEvent onChangeChannel];

// implement protocol delegate methods
- (NSInteger) getPosition;
- (NSInteger) getBitrate;
- (NSString *) getResolution;
- (NSInteger) getDuration;

// to release plug-in resources
[szrEvent closeObserver];

userDefinedObserver

Description

userDefinedObserver allows you to define any events you want to collect for your application and your business.
Event group is for classifying your User Defined Event.
All should not include any spaces or special characters. For example,

  • “Media Player” – Wrong Expression (x)
  • “Media_Player” – Wrong Expression (x)
  • “MediaPlayer” – Correct Expression (o)

Please notice this, If you include any spaces or special characters, then plug-in will delete spaces and special characters. for example, plug-in send all keys as “MediaPlayer” when you try to send above properties.

How to initialize

To initialize UserDefinedEventObserver, you should set up proper properties. You can initialize observer like:

UserDefinedEventObserver Example  Expand source

Event API

Function Signiture Description
postUserDefinedCountEvent Count Event is an event that you want to count the number of event. group: Group name of the event. cntEvtName : Count event name
postUserDefinedSumEvent Sum Event is an event that you want to sum sumProperty of event. group: Group name of the event. sumEvtName: The key name to be summed. sumValue: The value to be summed. This should be Number, not String.
postUserDefinedRevenueEvent Revenue Event is an event that you want to analyze revenue you make from individual users. By associating with users, you can analyze revenue across different user segment and calculate key business metrics such as lifetime value. group: Group name of the event revEvtName: The key name of Revenue type revValue: The value of Revenue. This should be Number, not String.

Example


// trigger UserDefinedEvent
[szrEvent postUserDefinedCountEvent:@"EventGroupName" withCountEventName:@"CountName"];

[szrEvent postUserDefinedSumEvent:@"EventGroupName" withSumEventName:@"SumEvent" withSumValue:12345];

[szrEvent postUserDefinedRevenueEvent:@"EventGroupName" withRevenueEventName:@"RevenueEvent" withRevenueValue:123.45];


pageReferrerObserver

Description
pageReferrerObserver analyzes your service traffic.

How to initialize
To initialize pageReferrerObserver, you should set up proper properties. you can initialize observer like:


// Initialize plug-in
[StreamlyzerPlugin initPlugin];

// Initialize pageReferrerObserver
SZRPageReferrerObserver *szrEvent = [[SZRPageReferrerObserver alloc] init];

// Set properties
[szrEvent setProperties:@{       
        // key provided by Streamlyzer
        SZR_CUSTOMER_KEY : @"<Key Provided by Streamlyzer>"

        // end user related properties
        , SZR_USER_ID : @"<User ID>"                   
        , SZR_USER_TYPE : @"<User Type>"                   
        , SZR_GENDER : @"<User Gender>"   /* SZR_VALUE_GENDER_FEMALE or SZR_VALUE_GENDER_MALE */
        , SZR_YEAR_OF_BIRTH : @"<User Year of Birth>"

        // service related properties                           
        , SZR_SERVICE_TYPE : @"<Service Type>"
        , SZR_SESSION_ID : @"<Session ID>"
        , SZR_STREAMING_SERVER_NAME : @"<Streaming Server Name"  /*Server name or source URL */
        , SZR_ABTEST_MARK : @"<AB Test Marking>"

        // platform related properties
        , SZR_PLATFORM_NAME : @"<Apple iOS>"
        , SZR_APPLICATION_NAME : @"<Streamlyzer Example Application>"                           
        , SZR_APPLICATION_VERSION : @"<0.9.x.0>"
        , SZR_PLAYER_PLATFORM_VERSION : @"<MPMoviewPlayer>"
        , SZR_MEDIA_PLAYER_VERSION : @"<Streamlyzer Example VideoPlayer 0.9.x.0>"
}];

sharedContentObserver

Description
sharedContentObserver analyzes your service out-bound traffic. For example, your audience shares your video. You will be able to tack which video is shared with this Observer.

How to initialize
To initialize sharedContentObserver, you should set up proper properties. you can initialize observer like:


// Initialize plug-in
[StreamlyzerPlugin initPlugin];

// Initialize sharedContentsObserver
SZRSharedContentsObserver *szrEvent = [[SZRSharedContentsObserver alloc] init];

// Set properties
[szrEvent setProperties:@{       
    // key provided by Streamlyzer
    SZR_CUSTOMER_KEY : @"<Key Provided by Streamlyzer>"

    // end user related properties
    , SZR_USER_ID : @"<User ID>"                   
    , SZR_USER_TYPE : @"<User Type>"                   
    , SZR_GENDER : @"<User Gender>"   /* SZR_VALUE_GENDER_FEMALE or SZR_VALUE_GENDER_MALE */
    , SZR_YEAR_OF_BIRTH : @"<User Year of Birth>"

    // service related properties                           
    , SZR_SERVICE_TYPE : @"<Service Type>"
    , SZR_SESSION_ID : @"<Session ID>"
    , SZR_STREAMING_SERVER_NAME : @"<Streaming Server Name"  /*Server name or source URL */
    , SZR_ABTEST_MARK : @"<AB Test Marking>"

    // platform related properties
    , SZR_PLATFORM_NAME : @"<Apple iOS>"
    , SZR_APPLICATION_NAME : @"<Streamlyzer Example Application>"                           
    , SZR_APPLICATION_VERSION : @"<0.9.x.0>"
    , SZR_PLAYER_PLATFORM_VERSION : @"<MPMoviewPlayer>"
    , SZR_MEDIA_PLAYER_VERSION : @"<Streamlyzer Example VideoPlayer 0.9.x.0>"  

    , SZR_LIVE : SZR_VALUE_LIVE_TRUE        /* SZR_VALUE_LIVE_TRUE or SZR_VALUE_LIVE_FALSE */
    , SZR_MOVIE_ID : @"<Movie ID>"
    , SZR_MOVIE_CATEGORY : @"<Movie Category>"
    , SZR_LIVE_CHANNEL_NAME : @"<Live Channel Name>"
}];

Event API

Function Signiture Description
postPageReferrerEvent Count Event is an event that you want to count the number of event. referrerHostName : Referrer Host Name referrerPagePath : Referrer Page Path currentPagePath : Current Page Path

Example


// trigger pageReferrerEvent
[szrEvent postPageReferrerEvent:@&amp;amp;quot;&amp;amp;lt;referrer host name&amp;amp;gt;&amp;amp;quot; referrerPagePath:@&amp;amp;quot;&amp;amp;lt;referrer page path&amp;amp;gt;&amp;amp;quot; currentPagePath:@&amp;amp;quot;&amp;amp;lt;current page path&amp;amp;gt;&amp;amp;quot;];

Event API

Function Signiture Description
postSharedContentsEvent evtGroup: Group name of the event. destination: Shared Destination. with this property. you can send any string, however, we strongly recommend to use below list. Twitter: “twitter” Facebook: “facebook” Google+: “googleplus” Blogger: “blogger” Tumblr: “tumblr” reddit: “reddit” Pinterest: “pinterest” LiveJournal: “livejournal”

Example


// trigger pageReferrerEvent
[szrEvent postPageReferrerEvent:@"<referrer host name>" referrerPagePath:@"<referrer page path>" currentPagePath:@"<current page path>"];


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s