Adobe Primetime TVSDK 1.4 for ios Programmer's Guide

Transcription

1 Adobe Primetime TVSDK 1.4 for ios Programmer's Guide

2 Contents TVSDK 1.4 for ios Programmer's Guide...5 Overview...5 Overview...5 Primetime TVSDK features...5 Considerations and best practices...6 Requirements...7 Content playback options...8 Set up the PTMediaPlayer...8 Set up notifications...9 Configure the player user interface...12 Quality of service statistics...16 Read QOS playback, buffering, and device statistics...16 Work with MediaPlayer objects...17 About the MediaPlayerItem class...17 MediaPlayer object lifecycle...18 Instant-on...19 Advertising...20 Advertising requirements...20 Partial ad-break insertion...20 Inserting ads...21 Default and customized playback behavior with ads...23 Customize playback with ads...24 Primetime ad server metadata...29 Companion banner ads...31 Clickable ads...33 Repackage incompatible ads using Adobe Creative Repackaging Service...33 Ad measurements from Moat...35 VPAID 2.0 ad support...35 Ad fallback for VAST and VMAP ads...37 Ad loading for a DVR window...37 Last updated 4/26/2018 TVSDK 1.4 for ios Programmer's Guide

3 Contents Custom tags...38 Updating ad creative selection rules...44 Tokenized segment streams...50 Customize opportunity detectors and content resolvers...50 Opportunity generators and content resolvers...50 Implement a custom opportunity/content resolver...51 Delete and replace ads in VOD streams...53 Ad deletion and replacement API changes...53 Use cases to delete and replace ads...54 Handle blackouts in live streams...57 Blackout API elements...58 Implement blackout handling...59 Subtitles and closed captioning...62 Expose subtitles...63 Expose closed captions...63 Alternate audio...64 Alternate audio tracks in the playlist...65 Access alternate audio tracks...66 Video analytics...66 Initialize and configure video analytics...66 Implement custom metadata support...69 Implement chapter support...70 Implement custom time updates...70 Set up video analytics reporting on the server side...71 Access video analytics reports...71 Content protection...71 Primetime DRM interface overview...71 Implementing Primetime DRM in a TSVDK application...72 Apple FairPlay in TVSDK applications...72 Whitelist your ios application...75 Notifications for player status, activity, errors, and logging...76 Notification content...77 Notification setup...77 Listening to notifications...77 Last updated 4/26/2018 TVSDK 1.4 for ios Programmer's Guide

4 Implementing notification callbacks...78 Adding custom notifications...78 Customized logging...78 Listening to logs...79 Adding new log messages...80 Failover...80 Billing metrics...80 Configure billing metrics...81 Transmit billing metrics...81 Primetime Player classes summary...82 Media player classes...82 Logging classes...83 Metadata classes...83 Notification classes...84 QoS classes...84 Timeline classes...85 Timeline advertising classes...85 Digital Rights Management classes...86 Video Analytics classes...86 Notification codes...86 ERROR notification codes...87 WARNING notification codes...89 INFO notification codes...91 Copyright...92 Last updated 4/26/2018 TVSDK 1.4 for ios Programmer's Guide

5 5 TVSDK 1.4 for ios Programmer's Guide Overview The Adobe Primetime Software Development Kit (TVSDK) is a toolkit that allows you to add advanced video playback functionality to your applications. For a list of the features that are supported by TVSDK, see Primetime Player TVSDK features. For specific hardware and software requirements for using TVSDK, see Requirements. Overview This guide provides information about how to develop video player applications by using TVSDK for ios, which is implemented in Objective-C. Product overview TVSDK includes API descriptions and code samples to help you to integrate advanced video functionality, content protection, and advertising features into your player. You use Objective-C to create a video player user interface. TVSDK helps you connect that user interface to its media player. This allows you to play videos and advertising based on media manifests. You can also use TVSDK to retrieve information about the video, handle security, and control and monitor playback. For specific hardware and software requirements for using TVSDK, see Requirements Audience This guide assumes that you understand how to develop applications and video players using Objective-C. You implement a video player user interface by using that language and incorporate TVSDK features. About this guide This guide provides information that allows you to incorporate TVSDK features in a video player by using Objective-C on ios devices. Primetime TVSDK features TVSDK for ios includes a variety of features. TVSDK provides the following main capabilities: VOD and live/linear playback Management of the playback window, including methods that play, stop, pause, seek, and retrieve the playhead position Support for full-event replay Closed captioning (608, WebVTT) and alternate forms of audio for increased accessibility DVR capability Adaptive bit rate (ABR) logic and initial set up of ABR controls Subscription to non-hls and HLS tags Live manifest failover support

6 6 Advertising VPAID 2.0 Client-side ad stitching Seamless ad insertion, including support for VAST/VMAP Support for custom cue tags for ads Support for marking, replacing, and deleting C3 ads Customizable content/ad insertion workflow including blackout signaling Content protection Access to digital rights management (DRM)-related services Playback of HLS streams unencrypted or with Protected HTTP Live Streaming (PHLS) Resolution-based output control, based on DRM policy Video and ad tracking QoS event tracking Notifications that help TVSDK and your application to communicate asynchronously about the status of videos, advertisements, and other elements, and also that log activity Integration with Adobe Analytics and heartbeat support Logging Debug logging Considerations and best practices To use TVSDK most effectively, you should consider certain details of its operation and follow certain best practices. Considerations Remember the following information when using TVSDK: Adobe Primetime does not work on ios simulators. You must use real devices for testing. Playback is supported only for HTTP Live Streaming (HLS) content. Main video content can be multiplexed, where video and audio streams are in the same rendition, or nonmultiplexed, where video and audio streams are in separate renditions. The TVSDK API is implemented in Objective-C. Video playback requires the native Apple AV Foundation framework. This affects how and when media resources, including closed captions and timelines, can be accessed: Timeline adjustments cannot be revised after the initial setup. For example, an advertisement cannot be removed from the timeline after it has played. If the user seeks back in the presentation, the same ad plays again even if the policy would have been to remove the ad. Depending on encoder precision, the actual encoded media duration might differ from the durations that are recorded in the stream resource manifest.

7 7 There is no reliable way to resynchronize between the ideal virtual timeline and the actual playout timeline. Progress tracking of the stream playback for ad management and Video Analytics must use the actual playout time, so reporting and user interface behavior might not precisely track the media and advertisement content. The incoming user agent for all HTTP requests from TVSDK on this platform is determined by the device and the ios version that is running on the device. The value of the user agent string defaults to what the operating system assigns. Best practices Here are recommended practices for TVSDK: Use HLS version 3.0 or above for program content. Use Apple s mediastreamvalidator tool to validate VOD streams. The PTSDKConfig class provides methods to enforce SSL on requests made to Primetime ad decisioning, DRM, and Video Analytics servers. For more information, see the forcehttps and isforcinghttps methods in this class. Important: Requests to third-party domains such as Ad Tracking pixels, Content and Ad URLs, and similar requests are not modified. It is the responsibility of the content providers and ad servers to provide URLs that are supported through HTTPS. Requirements TVSDK requires specific properties for media content, manifest content, and software versions. System and software requirements To use TVSDK, ensure that your hardware, operating system, and application versions all meet the minimum requirements listed below. Operating system ios 6.0 or later Content and manifest requirements Check the restrictions and requirements for streams and playlists (manifests), including DRM encryption keys. Content segment key frames Sequence numbers in live/linear video Each content segment must begin with a key frame. Must match between all bit-rate renditions for the main content at any given time. #EXT-X-VERSION requirements The version of #EXT-X-VERSION in the.m3u8 file affects what features are available to your application and what EXT tags are valid in your playlist/manifest. Here is some information about the #EXT-X-VERSION tag, which specifies the HLS protocol version: The version must match the features and attributes in the HLS playlist; otherwise, playback errors might occur. For more information, see HTTP Live Streaming specification.

8 8 If the tag is not included in the master or media playlists, or if no version is specified, version 1 is used by default. Content that does not comply with version 1 will not play. Adobe recommends using at least version 2 for playback in TVSDK-based clients. Clients and servers must implement the versions in the following way: Use at least this version EXT-X-VERSION:2 EXT-X-VERSION:3 To use these features The IV attribute of the EXT-X-KEY tag. Floating-point EXTINF duration values The duration tags (#EXTINF:<duration>,<title>) in version 2 were rounded to integer values. Version 3 and above require durations to be exact in floating point. TVSDK features such as ad insertion and seamless ABR EXT-X-VERSION:4 The EXT-X-BYTERANGE tag The EXT-X-I-FRAME-STREAM-INF tag The EXT-X-I-FRAMES-ONLY tag The EXT-X-MEDIA tag The AUDIO and VIDEO attributes of the EXT-X-STREAM-INF tag TVSDK alternate audio Content playback options TVSDK provides tools for creating an advanced video player application (your Primetime player), which you can integrate with other Primetime components. Use your platform's tools to create a player and connect it to the media player view in TVSDK, which has methods to play and manage videos. For example, TVSDK provides play and pause methods. You can create user interface buttons on your platform and set the buttons to call those TVSDK methods. Set up the PTMediaPlayer The PTMediaPlayer interface encapsulates the functionality and behavior of a media player object. To set up your PTMediaPlayer: 1. Fetch the media's URL from your user interface, for example, in a text field. NSURL *url = [NSURL URLWithString:textFieldURL.text]; 2. Create PTMetadata. Assume that your method createmetada prepares metadata (see Advertising). PTMetadata *metadata = [self createmetadata] 3. Create PTMediaPlayerItem by using your PTMetadata instance. PTMediaPlayerItem *item = [[[PTMediaPlayerItem alloc] initwithurl:url mediaid:yourmediaid metadata:metadata] autorelease]; 4. Add observers to notifications that TVSDK dispatches. [self addobservers]

9 9 5. Create PTMediaPlayer using your new PTMediaPlayerItem. PTMediaPlayer *player = [PTMediaPlayer playerwithmediaplayeritem:item]; 6. Set properties on your player. Here are some of the available PTMediaPlayer properties: player.autoplay = YES; player.closedcaptiondisplayenabled = YES; player.videogravity = PTMediaPlayerVideoGravityResizeAspect; player.allowsairplayvideo = YES; 7. Set the player's view property. CGRect playerrect = self.adplayerview.frame; playerrect.origin = CGPointMake(0, 0); playerrect.size = CGSizeMake(self.adPlayerView.frame.size.width, self.adplayerview.frame.size.height); [player.view setframe:playerrect]; [player.view setautoresizingmask: ( UIViewAutoresizingFlexibleWidth UIViewAutoresizingFlexibleHeight )]; 8. Add the player's view in the current view's subview. [self.adplayerview setautoresizessubviews:yes]; [self.adplayerview addsubview:(uiview *)player.view]; 9. Call play to start media playback. [player play]; Set up notifications The player can listen for a range of events that indicate the state of the player. Assuming that PTMediaPlayer is a property of the client player, self.player in the following example represents the PTMediaPlayer instance. The following example implements the addobservers method that are shown in the PTMediaPlayer set up instructions and includes most of the notifications: [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayerstatuschange:) name:ptmediaplayerstatusnotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayernotification:) name:ptmediaplayernewnotificationentryaddednotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayertimechange:) name:ptmediaplayertimechangenotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeritemplaystarted:) name:ptmediaplayerplaystartednotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeritemplaycompleted:) name:ptmediaplayerplaycompletednotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeritemtimelinechanged:) name:ptmediaplayertimelinechangednotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeritemmediaselectionoptionsavailable:) name:ptmediaplayermediaselectionoptionsavailablenotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeradbreakstarted:) name:ptmediaplayeradbreakstartednotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeradbreakcompleted:) name:ptmediaplayeradbreakcompletednotification object:self.player];

10 10 [[NSNotificationCenter defaultcenter] addobserver:self name:ptmediaplayeradstartednotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self name:ptmediaplayeradprogressnotification object:self.player]; [[NSNotificationCenter defaultcenter] addobserver:self name:ptmediaplayeradcompletednotification object:self.player]; ios notifications ThePTMediaPlayerNotifications class lists the notifications that the TVSDK dispatches to your player. Notification PTMediaPlayerAdBreakCompletedNotification PTMediaPlayerAdBreakStartedNotification PTMediaPlayerAdClickNotification PTMediaPlayerAdCompletedNotification PTMediaPlayerAdProgressNotification PTMediaPlayerAdStartedNotification PTBackgroundManifestErrorNotification PTMediaPlayerBufferingCompletedNotification PTMediaPlayerBufferingStartedNotification PTAudioTrackChangeCompleted PTAudioTrackChangeStarted Meaning An ad break ended. An ad break started. A user clicked a banner ad. An individual ad ended. An ad progressed; dispatched constantly while an ad plays. An individual ad started. Downloading the background manifest failed. Buffering has completed. The media player enters a buffering state. A change on the audio track of the currently playing media has completed. A change on the audio track of the currently playing media is initiated. PTMediaPlayerItemChangedNotification PTMediaPlayerItemDRMMetadataChanged PTMediaPlayerMediaSelectionOptionsAvailableNotification A different PTMediaPlayerItem of the PTMediaPlayer has been set. DRM metadata changed. There are new subtitles and alternate audio tracks (PTMediaSelectionOption). PTMediaPlayerNewNotificationEntryAddedNotification A new PTNotification has been added to the PTNotificationHistoryItem of the current PTMediaPlayerItem, that is, when a notification event is added to the notification history. PTMediaPlayerPlayCompletedNotification PTMediaPlayerSeekCompletedNotification PTMediaPlayerSeekErrorNotification PTMediaPlayerSeekStartedNotification PTMediaPlayerPlayStartedNotification Media playback ended. Seeking has completed. The current seek operation has failed. Seeking is starting. Playback started.

11 11 PTMediaPlayerStatusNotification The player status changed. Possible status values are: PTMediaPlayerStatusCreated PTMediaPlayerStatusInitializing PTMediaPlayerStatusInitialized PTMediaPlayerStatusReady PTMediaPlayerStatusPlaying PTMediaPlayerStatusPaused PTMediaPlayerStatusStopped PTMediaPlayerStatusCompleted PTMediaPlayerStatusError PTMediaPlayerTimeChangeNotification PTMediaPlayerTimelineChangedNotification PTTimedMetadataChangedNotification PTTimedMetadataChangedInBackgroundNotification The playback current time changed. The current player timeline changed. The TVSDK encountered the first occurrence of a subscribed tag. A subscribed tag is identified on the background manifest and a new PTTimedMetadata instance is prepared from it. Sample handlers for notifications The following code snippets illustrate some of the ways you can use notifications. Fetch the PTAdBreak instance using PTMediaPlayerAdBreakKey: - (void) onmediaplayeradbreakstarted:(nsnotification *) notification // Fetch the PTAdBreak instance using PTMediaPlayerAdBreakKey PTAdBreak *adbreak = [notification.userinfo objectforkey:ptmediaplayeradbreakkey]; Set subtitlesoptions and audiooptions: - (void) onmediaplayeritemmediaselectionoptionsavailable:(nsnotification \*) notification //SubtitlesOptions and audiooptions are set and accessible now. NSArray* subtitlesoptions = self.player.currentitem.subtitlesoptions; NSArray* audioop tions = self.player.currentitem.audiooptions; Fetch the PTAd instance using PTMediaPlayerAdKey: - (void) onmediaplayeradplaystarted:(nsnotification \*) notification // Fetch the PTAdinstance using PTMediaPlayerAdKey PTAd *ad = [notification.userinfo objectforkey:ptmediaplayeradkey];...

12 12... Configure the player user interface With the TVSDK, you can control the basic playback experience for live and video on demand (VOD). Instead of configuring the player for you, TVSDK provides methods and properties on the player instance that you can use to configure the player user interface. Wait for a valid state Before you can use most of the TVSDK player methods, the player must be in a valid status. The player moves through various statuses. Waiting for the player to be in the correct status ensures that the media resource has successfully loaded. If the player is not in at least the required status, many player methods throw IllegalStateException. The required status is usually PTMediaPlayerStatusReady. Implement a play/pause button You can set up buttons that call TVSDK methods to pause and play the media. Use the following sample code to implement a play or pause button: _playpausebutton = [[UIButton alloc] initwithframe:cgrectmake(button_pos_x, BUTTON_POS_Y, BUTTON_SIZE_W, BUTTON_SIZE_H)]; [_playpausebutton setimage:[uiimage imagenamed:@"play.png"] forstate:uicontrolstatenormal]; [_playpausebutton setimage:[uiimage imagenamed:@"pause.png"] forstate:uicontrolstateselected]; [_playpausebutton addtarget:self action:@selector(playtouch:) forcontrolevents:uicontroleventtouchupinside]; [self addsubview:_playpausebutton];... - (void)playtouch:(id)sender if (self.player.status == PTMediaPlayerStatusPlaying) _playpausebutton.selected = YES; [self.player pause]; else _playpausebutton.selected = NO; [self.player play]; Display the duration of the video You can display the duration of the currently active content. Implement a video-duration display using the following sample code: The PTMediaPlayer property, seekablerange, contains the current seekable window range: For VOD, this range is the entire VOD content range, including ads. For live/linear, this range represents the seekable window. For more information about the API, see TVSDK 1.4 for ios API Reference CMTimeRange seekablerange = self.player.seekablerange; if (CMTIMERANGE_IS_VALID(seekableRange)) double start = CMTimeGetSeconds(seekableRange.start); double duration = CMTimeGetSeconds(seekableRange.duration);

13 13 Display the current time and remaining time You can display the current and remaining time of the content that is being played. 1. To implement a display that shows the current and remaining time of the active content, use the following sample code: // 1. Register for the PTMediaPlayerTimeChangeNotification [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayertimechange:) name:ptmediaplayertimechangenotification object:self.player];... // 2. Create labels for displaying current and remaining time _timecurrentlabel = [[UILabel alloc] initwithframe:cgrectmake(50.0, 16.0, 50.0, 21.0)]; _timecurrentlabel.text _timecurrentlabel.font = [UIFont boldsystemfontofsize:12.0]; _timecurrentlabel.numberoflines = 1; _timecurrentlabel.textalignment = UITextAlignmentCenter; _timecurrentlabel.backgroundcolor = [UIColor clearcolor]; _timecurrentlabel.textcolor = [UIColor colorwithred:209.0/255.0 green:209.0/255.0 blue:209.0/255.0 alpha:1.0]; [self addsubview:_timecurrentlabel]; _timeremaininglabel = [[UILabel alloc] initwithframe:cgrectmake(485.0, 16.0, 50.0, 21.0)]; _timeremaininglabel.text _timeremaininglabel.font = [UIFont boldsystemfontofsize:12.0]; _timeremaininglabel.numberoflines = 1; _timeremaininglabel.textalignment = UITextAlignmentCenter; _timeremaininglabel.backgroundcolor = [UIColor clearcolor]; _timeremaininglabel.textcolor = [UIColor colorwithred:209.0/255.0 green:209.0/255.0 blue:209.0/255.0 alpha:1.0];... // 3. This method is called whenever the player time changes (PTMediaPlayerTimeChangeNotification) - (void) onmediaplayertimechange:(nsnotification *)notification //The seekable range provides the playback range of a stream CMTimeRange seekablerange = self.player.seekablerange; //Verify if the seekablerange is a valid CMTimeRange if (CMTIMERANGE_IS_VALID(seekableRange)) double duration = CMTimeGetSeconds(seekableRange.duration); double currenttime = CMTimeGetSeconds(self.player.currentItem.currentTime); if (CMTIME_IS_INDEFINITE(self.player.currentItem.duration)) //If the duration is indefinite then the content is live. [_timecurrentlabel settext:[nsstring stringwithformat:@"--:--"]]; [_timeremaininglabel settext:[nsstring stringwithformat:@"live"]]; else [_timecurrentlabel settext:[self timeformatter:currenttime]]; [_timeremaininglabel settext:[self timeformatter:(duration - currenttime)]]; 2. To implement a display that show the progress of an ad and the remaining time, use the following sample code:

14 14 double adbreakdurationleft; double adbreakduration; float currentadposition; (void)onmediaplayeradbreakstarted:(nsnotification *) notification PTAdBreak *adbreak = [notification.userinfo objectforkey:ptmediaplayeradbreakkey]; self.adbreakduration = CMTimeGetSeconds(adBreak.range.duration); self.adbreakdurationleft = self.adbreakduration; (void)onmediaplayeradbreakcompleted:(nsnotification *) notification self.adbreakduration = 0.0f; self.adbreakdurationleft = 0.0f; (void)onmediaplayeradplaystarted:(nsnotification *) notification self.currentadposition = 0; (void)onmediaplayeradplayprogress:(nsnotification *) notification PTAd *ad = [notification.userinfo objectforkey:ptmediaplayeradkey]; CMTime progress = [(NSValue *)[notification.userinfo objectforkey:ptmediaplayeradprogresskey] CMTimeValue]; if (ad!= nil) // remaining ad playback time in milliseconds self.currentadposition = CMTimeGetSeconds(progress); double timeleft = self.adbreakdurationleft - (double)self.currentadposition; float currentprogress = 1.0f - (timeleft/self.adbreakduration); (void)onmediaplayeradplaycompleted:(nsnotification *) notification PTAd *ad = [notification.userinfo objectforkey:ptmediaplayeradkey]; self.adbreakdurationleft = self.adbreakdurationleft - ad.primaryasset.duration; Display a seek scrub bar with the current playback time position You can display the current and remaining time of the content that is being played. To implement a scrub bar, use the following sample code: // 1. Register for the PTMediaPlayerTimeChangeNotification [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayertimechange:) name:ptmediaplayertimechangenotification object:self.player];... _positionslider = [[UISlider alloc] initwithframe:cgrectmake(105.0, 14.0, 370, 24)]; [_positionslider addtarget:self action:@selector(sliderthumbreleased:) forcontrolevents:uicontroleventtouchupinside];... // 2. Cover the event where the user moves to a different location in the stream - (void)sliderthumbreleased:(id)sender double slidertime = [_positionslider value]; CMTimeRange seekablerange = self.player.seekablerange; if (CMTIMERANGE_IS_VALID(seekableRange)) double start = CMTimeGetSeconds(seekableRange.start); double duration = CMTimeGetSeconds(seekableRange.duration); CMTime newtime = CMTimeMakeWithSeconds((sliderTime * duration) + start, AD_TIMESCALE); [self.player seektotime:newtime];

15 15... // 3. This method is called whenever the player time changes (PTMediaPlayerTimeChangeNotification) - (void) onmediaplayertimechange:(nsnotification *)notification CMTimeRange seekablerange = self.player.seekablerange; if (CMTIMERANGE_IS_VALID(seekableRange)) double start = CMTimeGetSeconds(seekableRange.start); double duration = CMTimeGetSeconds(seekableRange.duration); double currenttime = CMTimeGetSeconds(self.player.currentItem.currentTime); if (duration > 0) //Set the position slider value on the current playback time [_positionslider setvalue:((currenttime - start) / duration)]; Adaptive bit rates (ABR) for video quality HLS and DASH streams provide different bit rate encodings (profiles) for the same short burst of video. TVSDK can select the quality level for each burst based on the available bandwidth. TVSDK constantly monitors the bit rate to ensure that the content is played at the optimal bit rate for the current network connection. You can set the adaptive bit-rate (ABR) switching policy and the initial, minimum, and maximum bit rates for a multiple-bit-rate (MBR) stream. TVSDK automatically switches to the bit rate that provides the best playback experience in the specified configuration. Initial bit rate The desired playback bit rate (in bits per second) for the first segment. When playback starts, the closest profile, which is equal to or greater than the initial bit rate, is used for the first segment. If a minimum bit rate is defined, and the initial bit rate is lower than the minimum rate, TVSDK selects the profile with the lowest bit rate above the minimum bit rate. If the initial rate is above the maximum rate, TVSDK selects the highest rate below the maximum rate. If the initial bit rate is zero or undefined, the initial bit rate is determined by the ABR policy. Minimum bit rate Maximum bit rate The lowest allowed bit rate to which the ABR can switch. ABR switching ignores profiles with a bit rate that is lower than this bit rate. The highest allowed bit rate to which the ABR can switch. ABR switching ignores profiles with a bit rate higher than this bit rate. Keep the following information in mind: TVSDK does not dispatch events from bit-rate switching. You can change your ABR settings at any time, and the player switches to use the profile that most closely matches the most recent settings. For example, if a stream has the following profiles:

16 16 1: : : : : If you specify a range of to , TVSDK considers only profiles 1, 2 and 3. This allows applications to adjust to various network conditions, such as switching from WiFi to 3G or to various devices such as a phone, a tablet, or a desktop computer. Configure adaptive bit rates To configure TVSDK adaptive bit-rate parameters: 1. Configure an instance of PTABRControlParameters to set the initial, minimum, and maximum bit-rate settings. The default values are displayed in the following code snippet, but your application can set any integer value for each of these parameters. Important: Specify the bit-rate settings in bits-per-second (bps). // ARC (add autorelease for non-arc) PTABRControlParameters *abrmetadata = [[PTABRControlParameters alloc] init]; abrmetadata.initialbitrate = -1; abrmetadata.minbitrate = 0; abrmetadata.maxbitrate = INT_MAX; 2. Update your PTMediaPlayer instance with the configured PTABRControlParameters instance. // assuming self.player is the PTMediaPlayer instance self.player.abrcontrolparameters = abrmetadata; Remember the following: The application must set the abrcontrolparameters property on PTMediaPlayer before configuring a PTMediaPlayerItem instance for the initial and minimum bitrate settings to take effect. After content playback starts, setting a new instance only affects the maximum bitrate setting. To update the maximum bitrate setting during playback, create a new PTABRControlParameters instance and set it on the player instance. You can update the maximum bitrate setting during playback only on ios 8.0 and later. For earlier versions, the maxbitrate value that was set before content playback started is used. Quality of service statistics Quality of service (QoS) offers a detailed view into how the video engine is performing. TVSDK provides detailed statistics about playback, buffering, and devices. Read QOS playback, buffering, and device statistics You can read playback, buffering, and device statistics from the PTQOSProvider class.

17 17 The PTQOSProvider class provides various statistics, including information about buffering, bit rates, frame rates, time data, and so on. It also provides information about the device, such as the model, operating system, and manufacturer's device ID. Tip: You cannot change the playback buffer size, but you can monitor the status of the buffer size for debugging or analysis. PTPlaybackInformation includes such properties as playbackbufferfull and playbacklikelytokeepup. 1. Instantiate a media player. 2. Create a PTQOSProvider object and attach it to the media player. The PTQOSProvider constructor takes a player context so that it can retrieve device-specific information. qosprovider = [[PTQOSProvider alloc]initwithplayer:self.player]; 3. (Optional) Read the playback statistics. One solution to read playback statistics is to have a timer, such as an NSTimer, that periodically fetches the new QoS values from the PTQOSProvider. For example: - (void)printplaybackinfolog PTPlaybackInformation *playbackinfo = qosprovider.playbackinformation; if (playbackinfo) // For example: NSString *infolog = [NSString stringwithformat:@"observedbitrate : %f\n",playbackinfo.observedbitrate]; [consoleview logmessage:@"====%@\n\n",infolog]; 4. (Optional) Read the device-specific information. PTDeviceInformation *devinfo = qosprovider.deviceinformation; if (devinfo) [consoleview logmessage:@"=== qosdeviceinfo:==\n os =%@\n model = %@\n id =%@\n\n", devinfo.os, devinfo.model, devinfo.id]; [NSTimer scheduledtimerwithtimeinterval:2.0 target:self selector:@selector(printplaybackinfolog) userinfo:nil repeats:yes]; Work with MediaPlayer objects The PTMediaPlayer object represents your media player. A PTMediaPlayerItem represents audio or video on your player. About the MediaPlayerItem class After a media resource is successfully loaded, TVSDK creates an instance of the PTMediaPlayerItem class to provide access to that resource. The PTMediaPlayer resolves the media resource, loads the associated manifest file, and parses the manifest. This is the asynchronous part of the resource loading process. The PTMediaPlayerItem instance is produced after the resource has been resolved, and this instance is a resolved version of a media resource. TVSDK provides access to the newly created PTMediaPlayerItem instance through PTMediaPlayer.currentItem. Tip: You must wait for the resource to be successfully loaded before accessing the media player item.

18 18 MediaPlayer object lifecycle From the moment that you create the PTMediaPlayer instance to the moment when you terminate (reuse or remove) it, this instance completes a series of transitions from one status to another. Some operations are permitted only when the player is in a particular state. For example, calling play in PTMediaPlayerStatusCreated is not allowed. You can call this status only after the player reaches the PTMediaPlayerStatusReady status. To work with statuses: You can retrieve the current status of the MediaPlayer object with PTMediaPlayer.status. The list of statuses is defined in PTMediaPlayerStatus. State-transition diagram for the lifecycle of a MediaPlayer instance: The following table provides additional details: PTMediaPlayerStatus Occurs when PTMediaPlayerStatusCreated Your application requested a new media player by calling playerwithmediaplayeritem. The newly created player is waiting for you to specify a media player item. This is the media player's initial status. PTMediaPlayerStatusInitializing Your application calls PTMediaPlayer.replaceCurrentItemWithPlayerItem, and the media player is loading.

19 19 PTMediaPlayerStatus PTMediaPlayerStatusInitialized Occurs when TVSDK successfully set the media player item. PTMediaPlayerStatusReady The content is prepared and ads have been inserted in the timeline, or the ad procedure failed. Buffering or playback can begin. PTMediaPlayerStatusPlaying Your application has called play, so TVSDK is trying to play the video. Some buffering might occur before the video actually plays. PTMediaPlayerStatusPaused As your application plays and pauses the media, the media player moves between this state and PTMediaPlayerStatusPlaying. PTMediaPlayerStatusCompleted The player reached the end of the stream, and playback has stopped. PTMediaPlayerStatusStopped Your application has released the media player, which also releases any associated resources. You can no longer use this instance PTMediaPlayerStatusError An error occurred during the process. An error also might affect what your application can do next. Tip: You can use the status to provide feedback on the process (for example, a spinner while waiting for the next status change) or to take the next step in playing the media, such as waiting for the appropriate status before calling the next method. Instant-on Instant-on preloads parts of the media on one or more channels. After a user selects or switches channels, the content starts sooner because some of the buffering has already completed. When your player is in the PTMediaPlayerStatusReady status, call preparetoplay to preload and process some of the content for later playback. Tip: If you do not call preparetoplay, calling play automatically calls preparetoplay first. The preloading and processing is completed at this time. TVSDK completes some or all of the following tasks for preparetoplay: If the metadata key ksynccookieswithavasset is set, TVSDK makes one request to the original M3U8 file to synchronize cookies. Loads DRM metadata keys. Creates and prepares some structures, elements, or assets that are needed for playing content. Tip: The PTMediaPlayer and PTMediaPlayerItem preparetoplay methods are equal. To avoid creating a separate PTMediaPlayer instance for each asset, use the PTMediaPlayerItem method.

20 20 Instant-on helps you launch multiple media player instances, or media-player item loader instances, simultaneously in the background and buffer video streams in all of these instances. When a user changes the channel, and the stream has buffered properly, calling play on the new channel starts the playback sooner. Advertising You can insert ads in your VOD and live/linear content by using the Adobe Primetime ad decisioning interface. Primetime ad decisioning works with TVSDK to identify ad opportunities, resolve ads, and insert resolved ads in your video streams. Advertising requirements To incorporate ads in your video content, ensure that the advertising and main video content meets the following requirements: The advertising content's HLS version cannot be higher than the main content's HLS version. Ads must be multiplexed and must contain an audio-only rendition, regardless of whether the main content is multiplexed. Ad playlists should have the same bit-rate renditions as the renditions in the main content playlist. The target duration and individual fragment duration of an ad cannot exceed the target duration of the main content. If the main content contains an audio-only stream, the advertising content must also contain an audio-only stream. If the main content contains subtitle streams, the advertising content must be unencrypted. If the main content is multiple bit rate (MBR), the advertising content must also be MBR. If the main content has alternate audio tracks, each ad must have at least one audio-only stream. If the ad does not have at least one audio-only stream, the ad is skipped. Partial ad-break insertion TVSDK provides a TV-like experience of being able to join in the middle of an ad, in live streams. The partial ad-break insertion feature allows you to mimic a TV-like experience where, if the client starts a live stream inside a mid-roll, it starts playing within that mid-roll. It is similar to switching to a TV channel and the commercials run seamlessly. For example, If a user joins in the middle of a 90 seconds ad break (three 30 seconds ads), 10 seconds into the second ad (that is, at 40 seconds into the ad break), the second ad is played for the remaining duration (20 seconds) followed by the third ad. Tracking Ad trackers for the partially played ad (the second ad) are not triggered. In the example above, only the tracker for the third ad is triggered. Behavior with pre-roll The feature works when a pre-roll ad is played with live content. The stream plays from the live point after pre-roll ad ends.

21 21 Ad break events is sent even if there are no complete ads in this ad break. An ad is considered partial ad, if is skipped for more than one second. For example, if a viewer watches an ad that they skipped for 800 ms, it is considered as a complete ad. Inserting ads Ad insertion resolves ads for video-on-demand (VOD), for live streaming, and for linear streaming with ad tracking and ad playback. TVSDK makes the required requests to the ad server, receives information about ads for the specified content, and places the ads in the content in phases. An ad break contains one or more ads that play in sequence. TVSDK inserts ads in the main content as members of one or more ad breaks. Tip: If the ad has errors, TVSDK ignores the ad. VOD ad resolving and insertion TVSDK supports several use cases for VOD ad resolving and insertion. In VOD, TVSDK supports the following use cases: Pre-roll ad insertion, where ads are inserted at the beginning of the content. Mid-roll ad insertion, where at least one ad is inserted in the middle of the content. Post-roll ad insertion, where at least one ad is appended at the end of the content. TVSDK resolves the ads, inserts the ads in locations defined by the ad server, and computes the virtual timeline before playback starts. After playback starts, no changes, such as ads being inserted or inserted ads being removed, can occur. Live and linear ad resolving and insertion TVSDK supports several use cases for live and linear ad resolving and insertion. TVSDK supports the following live and linear use cases: Pre-roll ad insertion, where at least one ad is inserted at the beginning of the content. Mid-roll ad insertion, where at least one ad is inserted in the middle of the content. TVSDK resolves the ads and inserts the ads when a cue point is encountered in the live or linear stream. By default, TVSDK supports the following cues as valid ad markers when resolving and placing ads: #EXT-X-CUEPOINT #EXT-X-AD #EXT-X-CUE #EXT-X-CUE-OUT These markers require the metadata field's DURATION in seconds and the cue s unique ID. For example: #EXT-X-CUE DURATION=27 ID=identiferForThisCue... For more information about additional cues, see Subscribe to custom tags. Client ad tracking TVSDK automatically tracks ads for VOD and live/linear streaming.

22 22 Notifications are used to inform your application about an ad's progress, including information about when an ad begins and when it ends. Implement an early ad break return For live stream ad insertion, you might need to exit from an ad break before all the ads in the break are played to completion. Here are some examples for an early ad break return: The duration of the ad break in certain sports events. Although a default duration is provided, if the game resumes before the break finishes, the ad break must be exited. An emergency signal during an ad break in a live stream. The ability to exit from an ad break early is identified through a custom tag in the manifest known as a splice-in or a cue-in tag. TVSDK allows the application to subscribe to these splice-in tags to provide a splice-in opportunity. To use the #EXT-X-CUE-IN tag as a splice-in opportunity and implement an early ad break return: 1. Subscribe to the tag. [PTSDKConfig setsubscribedtags:[nsarray arraywithobject:@"#ext-x-cue-in"]]; 2. Add the cue-in opportunity resolver. // self.player is the PTMediaPlayer instance created for content and ad playback PTDefaultMediaPlayerClientFactory *clientfactory = self.player.mediaplayerclientfactory; // Set cue in opportunity resolver [clientfactory registeropportunityresolver:[ptdefaultadspliceinopportunityresolver adspliceinopportunityresolverwithtag:@"#ext-x-cue-in"]]; To share the same tag for splice-out and splice-in: 1. If the application is sharing the same cue to indicate cue-out/splice-out and cue-in/splice-in, extend PTDefaultAdOpportunityResolver and implement the prepareplacementopportunity method. Tip: The following code assumes that the app has an implementation for the iscueinopportunity method. - (PTPlacementOpportunity *)prepareplacementopportunity:(pttimedmetadata *)timedmetadata if ([self iscueinopportunity:timedmetadata]) return [PTPlacementOpportunity advertisementspliceinopportunitywithtimedmetadata:timedmetadata]; else return [super prepareplacementopportunity:timedmetadata]; 2. Register the extended opportunity resolver on the PTDefaultMediaPlayerClientFactory instance. // self.player is the PTMediaPlayer instance created for content and ad playback PTDefaultMediaPlayerClientFactory *clientfactory = self.player.mediaplayerclientfactory; // Clear existing resolver and register the new opportunity resolver [clientfactory clearopportunityresolvers]; [clientfactory registeropportunityresolver:[[ptdefaultextendedadopportunityresolver new] autorelease]];

23 23 Default and customized playback behavior with ads The behavior of media playback is affected by seeking, pausing, and the inclusion of advertising. To override the default behavior, use PTAdPolicySelector. Important: For VOD and live/linear streaming, timeline adjustments cannot be revised. This means that an advertisement cannot be removed from the timeline after it has played. If the user seeks back, the same ad plays again even if the normal policy would have been to remove it. Important: TVSDK does not provide a way to disable seeking during ads. Adobe recommends that you configure your application to disable seeking during ads. The following table describes how TVSDK handles ads and ad breaks during playback: Video activity During normal play, an ad break is encountered. Your application seeks forward over ad break(s) into main content. Your application seeks backward over ad break(s) into main content. Your application seeks forward into an ad break. Your application seeks backward into an ad break. Your application seeks forward or backward over watched ad break(s) into main content. Default TVSDK behavior policy Plays the last unwatched ad break that was skipped over and resumes playback at the desired seek position when the break(s) playback is complete. Skips to the desired seek position without playing ad breaks. Plays from the beginning of the ad in which the seek ended. Plays from the beginning of the ad in which the seek ended. If the last ad break skipped has already been watched, skips to the user-selected seek position. Customization available through PTAdPolicySelector Specify a different policy for the ad break by using selectpolicyforadbreak. Select which skipped break to play by using selectadbreakstoplay. Select which skipped break to play by using selectadbreakstoplay. Specify a different ad policy for the ad break and for the specific ad where the seek ended by using selectpolicyforseekintoad. Specify a different ad policy for the ad break and for the specific ad in which the seek ended by using selectpolicyforseekintoad. Select which of the skipped breaks to play using selectadbreakstoplay and determine which breaks have already been watched by using PTAdBreak.isWatched. Important: By default, TVSDK marks an ad break as watched immediately after entering the first ad in the ad break.

24 24 Video activity Your application seeks forward or backward over one or more ad breaks and drops into a watched ad break. Your application seeks forward over ads that were inserted using custom ad markers. Default TVSDK behavior policy Skips the ad break and seeks to the position immediately following the ad break. Skips to the user-selected seek position. Customization available through PTAdPolicySelector Specify a different ad policy for the ad break (with the watched status set to true) and for the specific ad where the seek ended by using selectpolicyforseekintoad. Customize playback with ads When playback reaches an ad break, passes an ad break, or ends in an ad break, TVSDK defines some default behavior for the positioning of the current playhead. Tip: You can override the default behavior by using the PTAdPolicySelector class. The default behavior varies, depending on whether the user passes the ad break during normal playback or by seeking in a video. You can customize ad playback behavior in the following ways: Save the position where the user stopped watching the video and resume playing at the same position in a future session. If an ad break is presented to the user, display no additional ads for a number of minutes, even if the user seeks to a new position. If the content fails to play after a few minutes, restart the stream or fail over to a different source for the same content. On the failover playback session, to allow the user to skip ads and resume to the previous failed position, you can disable pre-roll and/or mid-roll ads. TVSDK provides methods to enable skipping pre-roll and mid-roll ads. API elements for ad playback TVSDK provides classes and methods you can use to customize the playback behavior of content that contains advertising. The following API elements are useful for customizing playback: API element PTAdMetadata PTAdPolicySelector PTDefaultAdPolicySelector Content that supports advertising Control whether an ad break should be marked as having been watched by a viewer, and if yes, when to mark it. Set and get the watched policy using adbreakaswatched property. Protocol that allows customization of TVSDK ad behavior. Class that implements the default TVSDK behavior. Your application can override this class to customize the default behaviors without implementing the complete interface.

25 25 API element PTMediaPlayer Content that supports advertising localtime. This is the local time of the playback, excluding the placed ad breaks. seektolocaltime. Here, the seek occurs relative to a local time in the stream. gettimeline.converttolocaltime. The virtual position on the timeline is converted to the local position. PTAdBreak iswatched property. Indicates whether the viewer has watched the ad. Set up customized playback You can customize or override default ad behaviors. Before you can customize or override ad behaviors, register the ad policy instance with TVSDK. To customize ad behaviors, do one of the following: Conform to the PTAdPolicySelector protocol and implement all the required policy selection methods. This option is recommended if you need to override all the default ad behaviors. Override the PTDefaultAdPolicySelector class and provide implementations for only those behaviors that require customization. This option is recommended if you need to override only some of the default behaviors. For both options, complete the following tasks: 1. Register the policy instance to be used by TVSDK through the client factory. Attention: Custom ad policies that are registered at the beginning of playback are cleared when the PTMediaPlayer instance is deallocated. Your application must register a policy selector instance each time a new playback session is created. For example: // Create an instance of the custom policy selector PTS5MinuteSkipBreakPolicySelector *adpolicyselector = [[[PTS5MinuteSkipBreakPolicySelector alloc] initwithmediaplayer:self.player] autorelease]; // register this instance [[PTDefaultMediaPlayerClientFactory defaultfactory] registeradpolicyselector:adpolicyselector]; 2. Implement your customizations. Skip ad breaks for a period of time By default, TVSDK forces an ad break to play when the user seeks over an ad break.you can customize the behavior to skip an ad break if the time elapsed from a previous break completion is within a certain number of minutes. Important: When there is an internal seek to skip an ad, here might be a slight pause in the playback.

26 26 The following example of a customized ad policy selector skips ads in the next five minutes (wall clock time) after a user has watched an ad break. 1. Register the policy instance to be used by TVSDK through the client factory. // Create an instance of the custom policy selector PTS5MinuteSkipBreakPolicySelector *adpolicyselector = [[[PTS5MinuteSkipBreakPolicySelector alloc] initwithmediaplayer:self.player] autorelease]; // register this instance [[PTDefaultMediaPlayerClientFactory defaultfactory] registeradpolicyselector:adpolicyselector]; 2. Implement your customization. PTS5MinuteSkipBreakPolicySelector.h #import "PTMediaPlayerNotifications.h" #import "PTMediaPlayer.h" #import "PTDefaultAdPolicySelector.h" // extend the default policy selector@interface PTS5MinuteSkipBreakPolicySelector : PTDefaultAdPolicySelector - (id)initwithmediaplayer:(ptmediaplayer PTS5MinuteSkipBreakPolicySelector.m #import "PTS5MinuteSkipBreakPolicySelector.h" double MIN_BREAK_INTERVAL = 60 * 5; // 5 PTS5MinuteSkipBreakPolicySelector PTMediaPlayer *_player; NSTimeInterval _lastadbreakplayedtime; - (id)initwithmediaplayer:(ptmediaplayer *)player if (self = [super init]) _lastadbreakplayedtime = 0; _player = [player retain]; [self addobservers]; return self; - (NSArray *)selectadbreakstoplay:(ptadpolicyinfo *)info NSLog(@"%@ - selectadbreakstoplay (%f): %f", self, CMTimeGetSeconds(info.currentTime), _lastadbreakplayedtime); BOOL shouldplay = [self shouldplayadbreaks]; if (shouldplay) return [super selectadbreakstoplay:info]; return nil; - (PTAdBreakPolicyType)selectPolicyForAdBreak:(PTAdPolicyInfo *)info NSLog(@"%@ - selectpolicyforadbreak (%f): %f %f", self,

27 27 CMTimeGetSeconds(info.currentTime), _lastadbreakplayedtime, [[NSDate date] timeintervalsince1970]); BOOL shouldplay = [self shouldplayadbreaks]; if (shouldplay) return [super selectpolicyforadbreak:info]; return PTAdBreakPolicyTypeSkip; - (BOOL)shouldPlayAdBreaks NSTimeInterval currenttime = [[NSDate date] timeintervalsince1970]; if (_lastadbreakplayedtime <= 0) return YES; if (_lastadbreakplayedtime > 0 && (currenttime - _lastadbreakplayedtime) > MIN_BREAK_INTERVAL) return YES; // don't play any ad break if 5 minutes hasn't elapsed return NO; - (void) onmediaplayeradbreakstarted:(nsnotification *) notification NSLog(@"%@ - AdBreak Start", self); - (void) onmediaplayeradbreakcompleted:(nsnotification *) notification _lastadbreakplayedtime = [[NSDate date] timeintervalsince1970]; NSLog(@"%@ - AdBreak Complete at: %f", self, _lastadbreakplayedtime); - (void)addobservers [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeradbreakstarted:) name:ptmediaplayeradbreakstartednotification object:_player]; [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeradbreakcompleted:) name:ptmediaplayeradbreakcompletednotification object:_player]; - (void)removeobservers [[NSNotificationCenter defaultcenter] removeobserver:self]; - (void)dealloc [self removeobservers]; [_player release]; [super

28 28 Save the video position and resume later You can save the current playback position in a video and resume playing at the same position in a future session. Dynamically inserted ads differ between user sessions, so saving the position with spliced ads refers to a different position in a future session. TVSDK provides methods to retrieve the playback position while ignoring spliced ads. 1. When the user quits a video, your application retrieves and saves the position in the video. Tip: Ad durations are not included. Ad breaks can vary in each session due to ad patterns, frequency capping, and so on. The current time of the video in one session might be different in a future session. When saving a position in the video, the application retrieves the local time. Use the localtime property to read this position, which you can save on the device or in a database on the server. For example, if the user is at the 20th minute of the video, and this position includes five minutes of ads, currenttime will be 1200 seconds, while localtime at this position will be 900 seconds. Important: Local time and current time are the same for live/linear streams. In this case, converttolocaltime has no effect. For VOD, local time remains unchanged while ads play. - (void) onmediaplayertimechange:(nsnotification *)notification CMTimeRange seekablerange = self.player.seekablerange; if (CMTIMERANGE_IS_VALID(seekableRange)) double seekablerangestart = CMTimeGetSeconds(seekableRange.start); double seekablerangeduration = CMTimeGetSeconds(seekableRange.duration); double currenttime = CMTimeGetSeconds(self.player.currentTime); // includes ads double localtime = CMTimeGetSeconds(self.player.localTime); // no ads 2. To resume the video at the same position: To resume playing the video from the position that was saved from a previous session, use seektolocaltime. Tip: This method is called only with local time values. If the method is called with current time results, incorrect behavior occurs. To seek to the current time, use seektotime. 3. When your application receives the PTMediaPlayerStatusReady status change event, seek to the saved local time. [self.player seektolocaltime:cmtimemake(900, 1) completionhandler:^(bool finished) [self.player play]; ]; 4. Provide the ad breaks as specified in the ad policy interface. 5. Implement a custom ad policy selector by extending the default ad policy selector. 6. Provide the ad breaks that must be presented to the user by implementing selectadbreakstoplay. This method includes a pre-roll ad break and the mid-roll ad breaks before the local time position. Your application can decide to play a pre-roll ad break and resume to the specified local time, play a mid-roll ad break and resume to the specified local time, or play no ad breaks.

29 29 Primetime ad server metadata TVSDK supports resolving and inserting ads for VOD and live/linear streams. Prequisite: Before you can include advertising in your video content, provide the following metadata information: A mediaid, which identifies the specific content to play. Your zoneid, which identifies your company or website. Your ad server domain, which specifies the domain of your assigned ad server. Other targeting parameters. Set up Primetime ad server metadata Your application must provide TVSDK with the required PTAuditudeMetadata information to connect to the ad server. To set up the ad server metadata: 1. Create an instance of PTAuditudeMetadata and set its properties. PTAuditudeMetadata *admetadata = [[PTAuditudeMetadata alloc] init]; admetadata.zoneid admetadata.domain // Optionally set user agent admetadata.useragent 2. Set the PTAuditudeMetadata instance as metadata for the current PTMediaPlayerItem metadata by using PTAdResolvingMetadataKey. // Metadata is an instance of PTMetadata that is used to create the PTMediaPlayerItem [metadata setmetadata:admetadata forkey:ptadresolvingmetadatakey]; [admetadata release]; Here is an example: PTMetadata *metadata = [self createmetadata]; PTMediaPlayerItem *item = [[[PTMediaPlayerItem alloc] initwithurl:url mediaid:yourmediaid metadata:metadata] autorelease]; - (PTMetadata *) createmetadata PTMetadata* metadata = [[[PTMetadata alloc] init] autorelease]; PTAuditudeMetadata *admetadata = [[[PTAuditudeMetadata alloc] init] autorelease]; admetadata.zoneid = yourzoneid; admetadata.domain = youradserverdomain; [metadata setmetadata:admetadata forkey:ptadresolvingmetadatakey]; return metadata; Enable ads in full-event replay Full-event replay (FER) is a VOD asset that acts as a live/dvr asset, so your application must take steps to ensure that ads are placed correctly. For live content, TVSDK uses the metadata/cues in the manifest to determine where to place ads. However, sometimes live/linear content might resemble VOD content. For example, when live content completes, an EXT-X-ENDLIST tag

30 30 is appended to the live manifest. For HLS, the EXT-X-ENDLIST tag means that the stream is a VOD stream. TVSDK cannot automatically differentiate this stream from a normal VOD stream to correctly insert ads. Your application must tell TVSDK whether the content is live or VOD by specifying the PTAdSignalingMode. For a FER stream, the Adobe Primetime ad decisioning server should not provide the list of ad breaks that need to be inserted on the timeline before starting the playback. This is the typical process for VOD content. Instead, by specifying a different signaling mode, TVSDK reads all the cue points from the FER manifest and goes to the ad server for each cue point to request an ad break. This process is similar to live/dvr content. In addition to each request that is associated with a cue point, TVSDK makes an additional ad request for pre-roll ads. 1. From an external source, such as vcms, obtain the signaling mode that should be used. 2. Create the advertising-related metadata. 3. If the default behavior must be overwritten, specify the PTAdSignalingMode by using PTAdMetadata.signalingMode. The valid values are PTAdSignalingModeDefault, PTAdSignalingModeManifestCues, and PTAdSignalingModeServerMap. You must set the ad signaling mode before calling preparetoplay. After TVSDK starts to resolve and place ads on the timeline, changes to the ad signaling mode are ignored. Set the mode when you create the advertising metadata for the resource. 4. Continue to playback. PTMetadata *metadata = [[[PTMetadata alloc] init] autorelease]; PTAuditudeMetadata *admetadata = [[[PTAuditudeMetadata alloc] init] autorelease]; admetadata.zoneid = your-auditude-zone-id; admetadata.domain //admetadata.enabledvrads = YES; // FOR LIVE DVR case //admetadata.signalingmode = PTAdSignalingModeManifestCues; // FOR VOD FER case NSMutableDictionary *targetingparameters = [[[NSMutableDictionary alloc] init] autorelease]; [targetingparameters setvalue:@"ipad" forkey:@"device"]; [targetingparameters setvalue:@"preroll" forkey:@"ad_opportunity_id"]; admetadata.targetingparameters = targetingparameters; NSMutableDictionary *customparameters = [[[NSMutableDictionary alloc] init] autorelease]; [customparameters setvalue:@"your-media-id" forkey:@"nw_id"]; [customparameters setvalue:@"preroll" forkey:@"ad_opportunity_id"]; admetadata.customparameters = customparameters; [metadata setmetadata:admetadata forkey:ptadresolvingmetadatakey]; Ad signaling mode The ad signaling mode specifies where the video stream should get advertising information. The valid values are PTAdSignalingModeDefault, PTAdSignalingModeManifestCues, and PTAdSignalingModeServerMap. The following table describes the effect of AdSignalingMode values for various HLS stream types: Default Manifest cues Ad server map Video on Demand (VOD) Uses server map for placement detection Uses in-stream cues for placement detection Uses server map for placement detection

31 31 Default Manifest cues Ad server map Ads are inserted Pre-roll ads are inserted in the Ads are inserted main stream Mid-rolls ads replace main stream Live/linear Uses manifest cues for Uses in-stream cues for placement placement detection detection Ads replace main stream Ads replace main stream Not supported Companion banner ads TVSDK supports companion banner ads, which are ads that accompany a linear ad and often remain on the page after the linear ad ends.your application is responsible for displaying the companion banners that are provided with a linear ad. When displaying companion ads, follow these recommendations: Attempt to present as many of a video ad's companion banner ads as will fit in your player's layout. Present a companion banner only if you have a location that exactly matches its specified height and width. Tip: Do not resize the banner. Present the companion banner(s) as soon as possible after the ad begins. Do not overlay the main ad/video container with companion banners. Continue to display companion banners after the ad ends. The standard is to display each companion banner until you have a replacement for this banner. Companion banner data The content of a PTAdAsset describes a companion banner. The PTMediaPlayerAdStartedNotification notification returns a PTAd instance that contains a companionassets property (array of PtAdAsset). Each PtAdAsset provides information about displaying the asset. Available information width height resource type data Description Width of the companion banner in pixels. Height of the companion banner in pixels. The resource type for this companion banner: html: The data is in HTML code. iframe: The data is an iframe URL (src). static: The data is a staticurl that is a direct URL to an image. The data of the type that is specified by resourcetype for this companion banner.

32 32 Display banner ads To display banner ads, you need to create banner instances and allow TVSDK to listen for ad-related events. TVSDK provides a list of companion banner ads that are associated with a linear ad through the PTMediaPlayerAdPlayStartedNotification notification event. Manifests can specify companion banner ads by: An HTML snippet The URL of an iframe page The URL of a static image or an Adobe Flash SWF file For each companion ad, TVSDK indicates which types are available for your application. 1. Create a PTAdBannerView instance for each companion ad slot on your page. Ensure that the following information has been provided: To prevent the retrieval of companion ads of different sizes, a banner instance that specifies the width and height. Standard banner sizes. 2. Add an observer for the PTMediaPlayerAdStartedNotification that does the following: a) Clears existing ads in the banner instance. b) Gets the list of companion ads from Ad.getCompanionAssets PTAd.companionAssets. c) If the list of companion ads is not empty, iterate over the list for banner instances. Each banner instance ( a PTAdAsset) contains information, such as width, height, resource type (html, iframe, or static), and data that is required to display the companion banner. d) If a video ad has no companion ads booked with it, the list of companion assets contains no data for that video ad. To show a standalone display ad, add the logic to your script to run a normal DFP (DoubleClick for Publishers) display ad tag in the appropriate banner instance. e) Sends the banner information to a function on your page that displays the banners in an appropriate location. This is usually a div, and your function uses the div ID to display the banner. For example: - (void) onmediaplayeradplaystarted:(nsnotification *) notification _currentad = [notification.userinfo objectforkey:ptmediaplayeradkey]; if (_currentad!= nil) [self removeallbanners]; // remove any existing PTAdBannerView views // banners if (_currentad.companionassets && _currentad.companionassets.count > 0) PTAdAsset *bannerasset = [_currentad.companionassets objectatindex:0]; PTAdBannerView *bannerview = [[PTAdBannerView alloc] initwithasset:bannerasset]; bannerview.player = self.player; bannerview.delegate = self; bannerview.frame = CGRectMake(0.0, 0.0, bannerasset.width, bannerasset.height); [_adbannerview.bannerview addsubview:bannerview];

33 33 Clickable ads TVSDK provides you with information so that you can act on click-through ads. As you create your player UI, you must decide how to respond when a user clicks on a clickable ad. In TVSDK for ios, only linear ads are clickable. Respond to clicks on ads When a user clicks on an ad, a companion banner ad, or a related button, your application must respond. TVSDK provides you with information about the destination URL for the click. 1. To set up an event listener for TVSDK, and provide the click-through information, add an observer for PTMediaPlayerAdClickNotification. When a user clicks on an ad, a companion banner ad, or a related button, TVSDK dispatches this notification, including information about the destination for the click. 2. Monitor user interactions on clickable ads. 3. When the user touches or clicks the ad or button, to notify TVSDK, use [_player notifyclick:_currentad.primaryasset];. 4. Listen for the PTMediaPlayerAdClickNotification event from TVSDK. 5. To retrieve the click-through URL and related information, use the PTMediaPlayerAdClickURLKey object. 6. Pause the video. 7. Use the click-through information to display the ad click-through URL and the related information. You could, for example, display the information in one of the following ways: In your application by opening the click-through URL in a browser. On desktop platforms, the video ad playback area is used to invoke click-through URLs at user clicks. Redirect users to their external mobile web browser. On mobile devices, the video ad playback area is used for other functions, such as hiding and showing controls, pausing playback, expanding to full screen, and so on. On these devices, a separate view, such as a sponsor button, is used to launch the click-through URL. 8. Close the browser window in which the click-through information is displayed and resume playing the video. For example: // Listening for click notification [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayeradclick:) name:ptmediaplayeradclicknotification object:self.player]; - (void) onmediaplayeradclick:(nsnotification *) notification NSString *url = [notification.userinfo objectforkey:ptmediaplayeradclickurlkey]; if (url!= nil) [self openbrowser:[nsurl URLWithString:url]]; Repackage incompatible ads using Adobe Creative Repackaging Service Some third-party ads (or creatives) cannot be stitched into the HTTP Live Streaming (HLS) content stream because their video format is incompatible with HLS. Primetime ad insertion and TVSDK can optionally attempt to repackage incompatible ads into compatible M3U8 videos.

34 34 Ads served from various third parties, such as an agency ad server, your inventory partner, or an ad network, are often delivered in incompatible formats, such as progressive-download MP4. When TVSDK first encounters an incompatible ad, the player ignores the ad and issues a request to the creative repackaging service (CRS), which is part of the Primetime ad insertion back end, to repackage the ad into a compatible format. CRS attempts to generate multiple-bit-rate M3U8 renditions of the ad and stores these renditions on the Primetime Content Delivery Network (CDN). The next time TVSDK receives an ad response that points to that ad, the player uses the HLS-compatible M3U8 version from the CDN. To enable this optional feature, contact your Adobe representative. For more information about CRS, see Creative Packaging Service (CRS). Multiple CDN support for CRS ad delivery While the default Creative Repackaging Service (CRS) scenario is to use one Content Data Network (CDN), you can deploy CRS assets on more than one CDN. You can use multiple CDNs for the following reasons: A requirement to scale up for large viewing events. A requirement to match the CDN source of the CRS asset with the CDN source of the main content. You can transform the default URL that is provided by the CRS by using TVSDK URL Transformer APIs. Here are the API additions in TVSDK: PTURLTransformer A protocol that describes the methods that are required to transform the CRS ad URLs that are requested by TVSDK. Applications can implement this protocol and provide implementations for the required methods. PTDefaultURLTransformer The default URL transformer instance that is created in TVSDK and that implements the PTURLTransformer protocol. Applications can override this class or add a post URL transformation handler. This handler is useful when the application wants to make changes to the URL request after the default transformation has been applied. PTNetworkConfiguration seturltransformer:defaulttransformer A setter method that is provided on the PTNetworkConfiguration metadata instance to set the PTURLTransformer implementation. Important: Your app implementations must check for the PTURLTransformerInputType enumeration and only transform URLs of type PTURLTransformerInputTypeCRSCreative for CRS. The following code sample shows how your application can change the default host component to a different string (for example, cdn.mycrsdomain.com): // The sample code below uses Non-ARC code PTNetworkConfiguration *networkconfiguration = [[[PTNetworkConfiguration alloc] init] autorelease]; PTDefaultURLTransformer *defaulttransformer = [[[PTDefaultURLTransformer alloc] init] autorelease]; [defaulttransformer addposturltransformhandler:^nsstring *(NSString *url, PTURLTransformerInputType type) if (type == PTURLTransformerInputTypeCRSCreative) return [url stringbyreplacingoccurrencesofstring:[nsurl URLWithString:url].host withstring:@"cdn.mycrsdomain.com"];

35 35 ]; return url; [networkconfiguration seturltransformer:defaulttransformer]; // metadata is the PTMetadata instance set on a PTMediaPlayerItem instance. [metadata setmetadata:[self getnetworkconfiguration] forkey:ptnetworkconfigurationmetadatakey]; Ad measurements from Moat TVSDK takes information from FreeWheel and other adservers providing VAST responses. FreeWheel provides, within VAST responses, information from the Moat service. The Moat service counts ad impressions with an accuracy that better shows that creatives capture or neglect an audience's interests. Moat is a service measuring ad viewing across many uses, from browsers to within applications. Moat generates marketing analytics data in real-time across multiple platforms. The VAST response XML has a property and an element your code can read, the outermost ad id property and the outermost extension element. Either way, your code can use TVSDK to save both the ad id information and the extension information and organize the information in a tree structure. With this organization, your code can pick up the data from any level and pass it along to wherever it needs to go. The value of the outermost ad id property enables your code to coordinate information from the associated campaign. For example, FreeWheel can return data in an Extensions element. Below is a sample element. <Extensions> <Extension type="freewheel"> <Parameter name="moat"> <MeasurementInfo renditionid=" " type="mediafile"> <MoatID> <![CDATA[169843;56705; ; ; ;g ; ;g436558;530633]]]]> <![CDATA[> </MoatID> </MeasurementInfo> <MeasurementInfo renditionid=" " type="mediafile"> <MoatID> <![CDATA[169843;56705; ; ; ;g ; ;g436558;530633]]]]> <![CDATA[> </MoatID> </MeasurementInfo> </Parameter> </Extension> </Extensions> Freewheel can also set the id property in the Ad element, as shown in the sample below. <Ad id="118566" sequence="1"> Refer to the API documentation for the class PTNetworkAdInfo in PTAdAsset. VPAID 2.0 ad support Video Player Ad-Serving Interface Definition (VPAID) 2.0 provides a common interface to play video ads. It provides a rich media experience for users and allows publishers to better target ads, track ad impressions, and monetize video content. The following features are supported: Version 2.0 of the VPAID specification For more information, refer to IAB VPAID 2.0.

36 36 Linear VPAID ads on video-on-demand (VOD) content JavaScript VPAID ads VPAID ads must be JavaScript-based, and the ad response must identify the media type of the VPAID ad as application/javascript. The following features are not supported: Version 1.0 of the VPAID specification Skippable ads Nonlinear ads such as overlay ads, dynamic companion ads, minimizable ads, collapsible ads, and expandable ads Preloading VPAID ads VPAID ads in live content Flash VPAID ads Post-roll VPAID ad API Changes The following changes were made to the API: PTAuditudeMetadata has a customadloadtimeout property to change the default timeout on the VPAID loading process. The default timeout value is 10 seconds. PTMediaPlayerCustomAdNotification is dispatched from the PTMediaPlayer instance While the VPAID ad is playing: The VPAID ad is displayed in a view container above the player view, so the code that relies on taps by users on the player view does not work. The main content player is paused, and calls to pause and play on the player instance are used to pause and resume the VPAID ad. VPAID ads do not have a predefined duration, because the ad can be interactive. The ad duration and total ad break duration that are defined by the ad server response might not be accurate. Implement VPAID 2.0 integration To add VPAID 2.0 support in your ios application: 1. (Optional) Add a listener for custom ad events. [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(onmediaplayercustomadnotification:) name:ptmediaplayercustomadnotification object:self.player]; 2. (Optional) Display the notification. -(void)onmediaplayercustomadnotification:(nsnotification *)notification PTCustomAdNotificationObject *notificationobject = [notification.userinfo objectforkey:ptcustomadnotificationobjectkey]; if (notificationobject) NSLog(@"ViewController:: Custom Ad Notification Received: %ld", notificationobject.type);

37 37 Ad fallback for VAST and VMAP ads For Digital Video Ad Serving Template (VAST) ads (or creatives) that have the fallback rule enabled, TVSDK treats an ad with an invalid media type as an empty ad and attempts to use fallback ads in its place. You can configure some aspects of fallback behavior. The VAST/Digital Video Multiple Ad Playlist (VMAP) specification states that for ads where VAST fallback is enabled, empty ads automatically trigger the use of fallback ads. When a VAST ad is empty, TVSDK looks for a valid HLS media type replacement among the fallback ads. When a VAST ad in a wrapper has an invalid media type, TVSDK treats this ad as empty. You can configure whether TVSDK should do the same for ads inline in a VMAP. For more information about the VAST fallbackonnoad feature, see Digital Video Ad Serving Template (VAST) 3.0. Define fallback ad behavior for VMAP inline ads You can turn on fallback when a VMAP inline ad contains an invalid media type. Set FallbackOnInvalidCreativeEnabled to YES to have VMAP fall back when the media type for a linear/inline ad is invalid for HLS. The default value is NO. If a linear ad fails because it is has an invalid media type, or because the ad cannot be repackaged, this flag allows Primetime ad decisioning to follow the same fallback behavior as if the ad was an empty VAST wrapper. PTAuditudeMetadata *admetadata = [[[PTAuditudeMetadata alloc] init] autorelease]; admetadata.isfallbackoninvalidcreativeenabled = YES; Ad fallback behavior for VAST and VMAP When Primetime ad decisioning encounters a VAST ad (creative) that is empty or that has a media type that is invalid for HLS, it evaluates the fallback ads to determine what to return. In TVSDK, the only valid media type is application/x-mpegurl (M3U8). When there are stand-alone fallback ads, the Primetime ad decisioning plug-in looks examines these ads in the following order and returns the first ad with a valid media type: 1. If repackaging is enabled, the first occurrence of an ad with an invalid media type is treated like other invalid media types. If repackaging fails, this process applies to additional occurrences of the ad. 2. If TVSDK finds no valid fallback ads, it returns the original ad with the invalid media type. 3. If a fallback ad with a valid MIME type is returned instead of the original ad, Primetime ad decisioning sends error code 403 to the VAST error URL, if available. 4. If a fallback ad is a wrapper and returns multiple ads, only ads with the correct media type are returned. Important: This behavior is always enabled for ads in VAST wrappers. For VAST ads inline in a VMAP, the behavior is disabled by default, but your application can enable it. Ad loading for a DVR window You can decide whether to resolve only the ads that occur after the user s current live point or to also resolve ads that occur before the current live point.

38 38 When a user starts to view content at the beginning of a DVR stream, TVSDK resolves all ads for the stream at that time. However, when the user starts to view content at a point after the beginning of the stream, you can decide whether to resolve only the ads that occur after the user s current live point or to also resolve ads that occurred before the current live point. Tip: Resolving ads after the current live point is faster, but if the user seeks backwards, this option prevents the player from playing ads that appeared earlier. Control ad loading for a DVR window To control ad loading for a DVR window: To load all ads for the entire stream, set the PTAdMetadata.enableDVRAds property to YES. The default value is NO, and this option loads ads only from the current live point. For example: PTMetadata *metadata = [[[PTMetadata alloc] init] autorelease]; PTAuditudeMetadata *admetadata = [[[PTAuditudeMetadata alloc] init] autorelease]; admetadata.zoneid = <ZoneId>; admetadata.domain = <Domain>; // Enable DVR Ads by setting to YES the enabledvrads property on PTAdMetadata // (PTAuditudeMetadata is a subclass of PTAdMetadata) admetadata.enabledvrads = YES; [metadata setmetadata:admetadata forkey:ptadresolvingmetadatakey]; //Create PTMediaPlayerItem with the previously prepared metadata playeritem = [[PTMediaPlayerItem alloc] initwithurl:url mediaid:yourmediaid metadata:metadata]; Custom tags Media streams can carry additional metadata in the form of tags in the playlist/manifest file, and this file indicates the placement of advertising. You can specify custom tag names and be notified when certain tags appear in the manifest file. HLS content tags Important: This feature is not available for Safari on Apple computers, because TVSDK uses the video tag, rather than Flash or MSE, to play HLS content. TVSDK provides out-of-the-box support for specific #EXT advertising tags. Your application can use custom tags to enhance the advertising workflow or to support blackout scenarios. To support advanced workflows, TVSDK allows you to specify and subscribe to additional tags in the manifest. You can be notified when these tags appear in the manifest file. Tip: You can subscribe to custom tags both for VOD and live/linear streams. Limitation: When HLS is played by using the Video tag in Safari, and not by using Flash Fallback, this feature will not be available in Safari.

39 39 Using custom HLS tags Here is an example of a customized VOD asset: #EXTM3U #EXT-X-VERSION:3 #EXT-X-TARGETDURATION:7 #EXT-X-ASSET:AID=10 #EXTINF:9.9766, seg1.ts #EXTINF:9.9766, seg2.ts #EXTINF:9.9766, seg3.ts #EXT-X-AD:DURATION=10 #EXTINF:9.9766, seg4.ts #EXTINF:9.9766, seg5.ts #EXT-X-ENDLIST Your application can set up the following scenarios: A notification when #EXT-X-ASSET tags, or any other set of custom tag names to which you have subscribed, exist in the file. Insert ads when an #EXT-X-AD tag, or any other custom tag name, is found in the stream. You can subscribe to any of the following tags as custom tags: EXT-PROGRAM-DATE-TIME, EXT-X-START, EXT-X-AD, EXT-X-CUE, EXT-X-ENDLIST. You are notified with a TimedMetadata event during parsing of manifest files. There are some advertising tags, such as EXT-X-CUE, to which you are already subscribed. These ad tags are also used by the default opportunity generator.you can specify which ad tags are used by the default opportunity generator by setting the adtags property. Example of a customized VOD asset Here is an example of a customized VOD asset: #EXTM3U #EXT-X-VERSION:3 #EXT-X-TARGETDURATION:7 #EXT-X-ASSET:AID=10 #EXTINF:9.9766, seg1.ts #EXTINF:9.9766, seg2.ts #EXTINF:9.9766, seg3.ts #EXT-X-AD:DURATION=10 #EXTINF:9.9766, seg4.ts #EXTINF:9.9766, seg5.ts

40 40 #EXT-X-ENDLIST Your application could set up the following scenarios: A notification when #EXT-X-ASSET tags, or any other set of custom tag names to which you have subscribed, exist in the file. Insert ads when an #EXT-X-AD tag, or any other custom tag name, is found in the stream. Config class methods for tags You can configure custom tag names in TVSDK globally with the PTSDKConfig class. TVSDK applies the global configuration automatically to any media stream that does not specify a stream-specific configuration. PTSDKConfig exposes these methods to manage the custom tags: Subscribe to specific custom tags subscribedtags setsubscribedtags Retrieves the current list of subscribed tags. Sets the list of subscribed tags that will be exposed to the application. Customize the ad tags used by the default opportunity detector adtags setadtags Retrieves the current list of ad tags. Sets the list of ad tags that will be used by default opportunity generator. Remember the following: The setter methods do not allow the tags parameter to contain null values. The custom tag name must contain the # prefix. For example, #EXT-X-ASSET is a correct custom tag name, but EXT-X-ASSET is incorrect. You cannot change the configuration after the media stream has been loaded. Timed metadata class When TVSDK detects a subscribed tag in the playlist/manifest, the player automatically tries to process the tag and expose it in the form of a PTTimedMetadata object. The class provides the following elements: Property metadataid name time Type NSString NSString CMTime Description Unique identifier of the timed metadata. This value is usually extracted from the cue/tag ID attribute. Otherwise, a unique random value is provided. The name of the timed metadata. If the type is TAG, the value represents the cue/tag name. If the type is ID3, it is null. The time position, in milliseconds, relative to the start of the main content where this timed metadata is present in the stream.

41 41 Property type Type PTTimedMetadataType Description The type of the timed metadata. TAG - indicates that the timed metadata was created from a tag in the playlist/manifest. ID3 - indicates that the timed metadata was created from an ID3 tag in the media stream. Remember the following: TVSDK automatically extracts the attributes list into key-value pairs and stores the attributes in the metadata property. Tip: Complex data in custom tags in the manifest, such as strings with special characters, must be in quotes. For example: #EXT-CUSTOM-TAG:type=SpliceOut,ID=1,time= ,duration=30.0,url= " If the extraction fails because of a custom tag format, the content property always contains the tag's raw data, which is the string after the colon. No error is thrown in this case. Element TAG, (nonatomic, assign) CMTime (nonatomic, assign) PTTimedMetadataType (nonatomic, retain) NSString (nonatomic, retain) NSString *name Description Possible types for the timed metadata. The time position, relative to the start of the main content, where this metadata was inserted in the stream. Returns the type of the timed metadata. Returns the ID extracted from the cue/tag attributes. Otherwise, a unique random value is provided. Returns the name of the cue, which is usually the HLS tag name. Subscribe to custom tags TVSDK prepares PTTimedMetadata objects for subscribed tags each time these objects are encountered in the content manifest. Before the playback starts, you must subscribe to the tags. To be notified about custom tags in HLS manifests: Set the custom ad tag names globally by passing an array that contains the custom tags to setsubscribedtags in PTSDKConfig. Important: You must include the # prefix when working with HLS streams. For example: NSArray *customhlstags = [NSArray arraywithobjects:@"#ext-oatcls-scte35",@"#ext_custom_tag2",nil]; [PTSDKConfig setsubscribedtags:customhlstags];

42 42 Add listeners for timed metadata notifications To receive notifications about tags in the manifest, implement the appropriate notification listener(s). You can monitor timed metadata by listening for the following events, which notify your application of related activity: PTTimedMetadataChangedNotification: Each time a unique subscribed tag is identified during parsing of the content, TVSDK prepares a new PTTimedMetadata object and dispatches this notification. The object contains the name of the tag to which you subscribed, the local time in the playback where this tag will appear, and other data. PTMediaPlayerTimeChangeNotification: For live/linear streams where the manifest/playlist refreshes periodically, additional custom tags might appear in the updated playlist/manifest, so additional TimedMetadata objects might be added to the MediaPlayerItem.timedMetadata property. This event notifies your application when this happens. Retrieve the timed metadata in one of the following ways. Set your application to add itself as a listener to the PTTimedMetadataChangedNotification notification and fetch the object using PTTimedMetadataKey. [[NSNotificationCenter defaultcenter] addobserver:self selector:@selector(ontimedmetadatachanged:) name:pttimedmetadatachangednotification object:self.player.currentitem]; - (void) ontimedmetadatachanged:(nsnotification *) notification NSDictionary *timedmetadatauserinfo = [[NSDictionary alloc]initwithdictionary: notification.userinfo]; PTTimedMetadata *newtimedmetadata = [timedmetadatauserinfo objectforkey: PTTimedMetadataKey]; Access the timedmetadatacollection property of PTMediaPlayerItem, which consists of all the PTTimedMetadata objects that have been notified so far. Store timed metadata objects as they are dispatched Your application must use the appropriate PTTimedMetadata objects at the appropriate times. During content parsing, which happens before playback, TVSDK identifies subscribed tags and notifies your application about these tags. The time that is associated with each PTTimedMetadata is the absolute time on the playback timeline. Your application must complete the following tasks: 1. Keep track of the current playback time. 2. Match the current playback time to the dispatched PTTimedMetadata objects. 3. Use the PTTimedMetadata where the start time equals the current playback time. Restriction: The code below assumes that there is only one PTTimedMetadata instance at a time. If there are multiple instances, the application must save them appropriately in a dictionary. One method is to create an array at a given time and store all instances in that array.

43 43 The following example shows how to save PTTimedMetadata objects in a NSMutableDictionary (timedmetadatacollection) keyed by the start time of each timedmetadata. NSMutableDictionary *timedmetadatacollection; - (void)onmediaplayersubscribedtagidentified:(nsnotification *)notification if (!timedmetadatacollection) timedmetadatacollection = [[NSMutableDictionary alloc] init]; NSDictionary *userinfo = [notification userinfo]; PTTimedMetadata *timedmetadata = [(PTTimedMetadata *)[userinfo objectforkey:pttimedmetadatakey] retain]; if ([timedmetadata.name NSLog(@"Adding timedmetadata %@ to timedmetadatacollection with time %f",timedmetadata.name,cmtimegetseconds(timedmetadata.time)); NSNumber *timedmetadatastarttime = [NSNumber numberwithint:(int)cmtimegetseconds(timedmetadata.time)]; [timedmetadatacollection setobject:timedmetadata forkey:timedmetadatastarttime]; [timedmetadata release]; Parsing Nielsen ID3 tags To extract the ID3 tag for parsing, use the following on the onmediaplayersubscribedtagidentified method: (void)onmediaplayersubscribedtagidentified:(nsnotification *)notification NSDictionary *userinfo = [notification userinfo]; PTTimedMetadata *timedmetadata = (PTTimedMetadata *)[userinfo objectforkey:pttimedmetadatakey]; if (timedmetadata.type == PTTimedMetadataTypeID3) Unknown macro: PTMetadata *metadata = (PTMetadata *)timedmetadata; NSString * nstr = [[NSString alloc] initwithformat After you parse the ID3 tag, extract the Nielsen-specific metadata using the following: (NSString *)parsenielsenurlfromid3tag:(nsstring *)str /* ID3 tag <AVMetadataItem: 0x15e58e60, identifier=id3/priv, keyspace=org.id3, key class = NSCFString, key=priv, commonkey=(null), extendedlanguagetag=(null), datatype=(null), time= / = , duration= INVALID, startdate=(null), extras= info = " 1TsDo0jIrNn9N2yTPe6nVG3dHZHfgS52fJeQjf9fJCga9tj4OW4NXPZ9fI1mx0gfYUPBXnjqolHemZPtn_FCoNg 8Dqw8-Auruf15fU04pJfXTTN0IgZ4iWBmeRiPpS9X100zdCIGeIlgZnkYj6UvVjmPIdY5jyRQTA=/00000/21778/00";, value length=1> */ NSString *nielsenstr = nil; for (NSString *keyvaluepairstring in [str componentsseparatedbystring:@", "]) if([keyvaluepairstring rangeofstring:@"nielsen.com"].location!= NSNotFound) // Nielsen NSRange start = [keyvaluepairstring rangeofstring:@"\""]; NSRange end = [keyvaluepairstring rangeofstring:@"\";"]; nielsenstr = [keyvaluepairstring substringwithrange:nsmakerange(start.location + 1, end.location-start.location)];

44 44 return nielsenstr; Use timed metadata You can use TimedMetadata when the current playback time matches the start time. To use these saved PTTimedMetadata objects during playback, use the saved dictionary from Store timed-metadata objects as they are dispatched. 1. Extract and update the current playback time from this notification and find all of the PTTimedMetadata objects with start times that match the current playback time. You can use these objects to complete various actions. For example: - (void) onmediaplayertimechange:(nsnotification *)notification CMTimeRange seekablerange = self.player.seekablerange; if (CMTIMERANGE_IS_VALID(seekableRange)) int currenttime = (int) CMTimeGetSeconds(self.player.currentTime); NSArray *allkeys = timedmetadatacollection? [timedmetadatacollection allkeys] : [NSArray array]; NSMutableArray *timedmetadatastodelete = [[[NSMutableArray alloc] init] autorelease]; int count = [allkeys count]; for (int i=count - 1; i > -1; i--) NSNumber *currtimedmetadatatime = allkeys[i]; if ([currtimedmetadatatime integervalue] == currenttime) /* Use the timed metadata here and remove it from the collection. */ NSLog (@"IN PLAYBACK TIME %i TO EXECUTE TIMEDMETADATA %@ scheduled at time %f",currenttime,currtimedmetadata.name,cmtimegetseconds(currtimedmetadata.time)); PTTimedMetadata *currtimedmetadata = [timedmetadatacollection objectforkey:currtimedmetadatatime]; [timedmetadatastodelete addobject:currtimedmetadatatime]; for (int i=0; i<[timedmetadatastodelete count]; i++) NSNumber *timedmetadatatodelete = timedmetadatastodelete[i]; [timedmetadatacollection removeobjectforkey:timedmetadatatodelete]; 2. Periodically flush stale PTTimedMetadata instances from the list to prevent memory from continuously growing. Updating ad creative selection rules You can use the TVSDK configuration file (AdobeTVSDKConfig.json) to update the priorities for ad creative selection on VAST/VMAP responses.you can also use this configuration file to define the source URL transformation rules for ad creatives.

45 45 When your video player makes a request to an ad server, the VAST/VMAP response usually includes multiple ad creatives (MediaFile elements), each of which provides a URL to a different container-codec version. In some cases, ad creatives in the VAST/VMAP response each provide a different bitrate for the ad. If you want to specify your own priority and transformation rules for these ad creatives, you can do so in the AdobeTVSDKConfig.json configuration file. Important: Do not change the name of the TVSDK configuration file. The name must remain AdobeTVSDKConfig.json. You can place this file anywhere that is accessible to your bundle. You can specify two types of rules in AdobeTVSDKConfig.json: Priority rules and Normalize rules. Disabling Pre-Roll To disable pre-roll you will need to change the default opportunity generators to not make the pre-roll call. By default, TVSDK uses the following opportunity generators: /** */ override protected function doretrievegenerators(item:mediaplayeritem):vector.<opportunitygenerator> var result:vector.<opportunitygenerator> = new Vector.<OpportunityGenerator>(); result.push(new AdSignalingModeOpportunityGenerator()); result.push(new SpliceOutOpportunityGenerator()); return result; To disable the pre-roll on live streams, this should change to include only the SpliceOutOpportunityGenerator: /** */ override protected function doretrievegenerators(item:mediaplayeritem):vector.<opportunitygenerator> var result:vector.<opportunitygenerator> = new Vector.<OpportunityGenerator>(); if (preroll_enabled == true) result.push(new AdSignalingModeOpportunityGenerator()); result.push(new SpliceOutOpportunityGenerator()); return result; Priority rules The priority rule defines the priority order of the ad creatives that will be selected for playback from a VAST/VMAP response. Table 1: A Priority rule has the following attributes and possible values: Key Type Values Description priority Array An array of lowercase mime-types that define the priority in which source creatives must be selected for playback.

46 46 Key Type Values Description item String host Currently only host is supported. This attribute must be present when matches and values attributes are defined. matches String multiple Possible values: eq - equals ne - not equals co - contains nc - not contains sw - starts with ew - ends with type String priority The value must always be priority values Array TVSDK will use the matches attribute on the item of the source creative and match against the values defined in this array stream String Value can be vod or live "ads": "rules": "default": [ "type": "priority", "stream": "vod", "priority": [ "application/x-mpegurl", "application/vnd.apple.mpegurl", "application/x-shockwave-flash", "video/mp4", "video/m4v", "video/x-flv", "video/webm" ],..., ] Normalize rules The normalize rule defines a URL transformation to apply to a source creative URL obtained from a VAST/VMAP response.

47 47 Table 2: The normalize rule has the following attributes and possible values: Key Type Values Description type String normalize The value must always be normalize. item String host Currently only host is supported. This attribute must be present when matches and values attributes are defined. matches Possible values: eq - equals ne - not equals co - contains nc - not contains sw - starts with ew - ends with values Array TVSDK will use the matches attribute on the item of the source creative and match against the values defined in this array. find regex A regular expression to apply on the source creative URL to match. replace regex A regular expression to apply on the source creative URL to replace based on the match. "ads": "rules": "default": [... "type": "normalize", "item": "host", "matches": "ew", "values": [ "redirector.gvt1.com" ], "find": "videoplayback/(.*?)/expire/.*?/(.*?)/signature/.*?/", "replace": "videoplayback/$1/expire//$2/signature//" ]

48 48 Sample creative selection rules In the AdobeTVSDKConfig.json you can specify default rules as well as rules for specific zones. Sample default rules The following is an example of an AdobeTVSDKConfig.json file that defines only default rules: "ads": "rules": "default": [ "type": "priority", "stream": "vod", "priority": [ "application/x-mpegurl", "application/vnd.apple.mpegurl", "application/x-shockwave-flash", "video/mp4", "video/m4v", "video/x-flv", "video/webm" ], "type": "priority", "stream": "live", "priority": [ "application/x-mpegurl", "application/vnd.apple.mpegurl", "video/mp4", "video/m4v", "video/x-flv", "video/webm" ], "type": "normalize", "item": "host", "matches": "ew", "values": [ "redirector.gvt1.com" ], "find": "videoplayback/(.*?)/expire/.*?/(.*?)/signature/.*?/", "replace": "videoplayback/$1/expire//$2/signature//" ] Sample default rules with additional zone rules The following is an example of an AdobeTVSDKConfig.json file that defines default rules, plus additional rules for a specific zone ID (in this case, zone "1234"): "ads": "rules": "default": [ "type": "priority", "stream": "vod", "priority": [ "application/x-mpegurl", "application/vnd.apple.mpegurl",

49 49,, ] "application/x-shockwave-flash", "video/mp4", "video/m4v", "video/x-flv", "video/webm" "type": "priority", "stream": "live", "priority": [ "application/x-mpegurl", "application/vnd.apple.mpegurl", "video/mp4", "video/m4v", "video/x-flv", "video/webm" ] "type": "normalize", "item": "host", "matches": "ew", "values": [ "redirector.gvt1.com" ], "find": "videoplayback/(.*?)/expire/.*?/(.*?)/signature/.*?/", "replace": "videoplayback/$1/expire//$2/signature//" ], "1234": [ "type": "priority", "matches": "nc", "item": "host", "values": [ "my.domain.com", "a.bcd.com" ], "priority": [ "application/x-shockwave-flash", "video/mp4", "video/x-flv", "video/quicktime", "video/webm", "application/x-mpegurl", "application/vnd.apple.mpegurl", "application/javascript" ] ] Applying creative selection rules TVSDK applies creative selection rules in the following ways: TVSDK applies all default rules first, followed by the zone-specific rules. TVSDK ignores any rules that are not defined for the current zone ID. Once TVSDK applies the default rules, the zone-specific rules can further change the creative priorities based on the host (domain) matches on the creative selected by the default rules. In the included sample rules file with additional zone rules, once TVSDK applies the default rules, if the M3U8 creative domain does not contain my.domain.com or a.bcd.com and the ad zone is 1234, the creatives are

50 50 re-ordered and the Flash VPAID creative is played first if available. Otherwise an MP4 ad is played, and so on down to JavaScript. If an ad creative is selected that TVSDK cannot play natively (.mp4,.flv, etc.), TVSDK issues a repackaging request. Note that the ad types that can be handled by TVSDK are still defined through the validmimetypes setting in AuditudeSettings. Tokenized segment streams HLS streams that are delivered through a Content Delivery Network (CDN) can sometimes use authentication tokens on the manifest and segment requests for verification. These tokens can be provided as URL parameters or as cookie headers. Tokens provided as cookies on the master manifest (m3u8) response are not shared with the segment (ts) requests even when the segment requests are for the same domain. To enable the sharing of these cookies in a segment request, set the following property on the PTMetadata instance provided to the player item: PTMetadata *metadata = [[[PTMetadata alloc] init] autorelease]; [metadata setvalue:[nsnumber numberwithbool:yes] forkey:ksynccookieswithavasset]; An additional request is made to the master manifest (m3u8) before the stream begins to play. Important: This cookie-sharing feature is only supported on devices running ios 8 or above. Customize opportunity detectors and content resolvers An opportunity detector is a TVSDK component that detects custom tags in a stream and identifies placement opportunities. These opportunities are sent to the content resolver, which customizes the content/ad insertion workflow based on the placement opportunity properties and metadata. TVSDK includes a default opportunity detector: PTOpportunityResolver, which understands default ad cues TVSDK also includes a default content resolver that provides content to be inserted based on the metadata key in the player item: PTContentResolver You can override the default opportunity detectors and content resolvers to customize the advertising workflow in the following ways: Add support for custom tag detection Recognize custom tags for ad insertion Create a customized ad provider Black out content Opportunity generators and content resolvers TVSDK provides default opportunity generators and content resolvers that place ads in the timeline, and these generators and resolvers are based on nonstandard tags in the manifest. Your application might need to alter the timeline based on opportunities that are identified in the manifest, such as indicators for a blackout period.

51 51 An opportunity represents a point of interest on the timeline that usually indicates an ad placement opportunity. This opportunity can also indicate a custom operation that might affect the timeline, such as a blackout period. An opportunity generator identifies specific opportunities (tags) in the timeline and notifies TVSDK that these opportunities have been tagged. Opportunities are identified in a timeline in PTTimedMetadata by including a nonstandard (non-hls) tag. When your application is notified about an opportunity (tag), your application might alter the timeline by, for example, inserting a series of ads, by switching to an alternate stream (blackouts) or by otherwise editing the timeline content. By default, TVSDK calls the appropriate content resolver to implement the required timeline changes or actions. Your application can use the default TVSDK advertisement content resolver or register its own content resolver. You can also use PTSDKConfig.setAdTags to add more ad marker tags/cues so that TVSDK can recognize and use PTSDKConfig.setSubscribedTags and notify your application about additional tags that might carry advertising workflow information. One possible use of a custom resolver is for blackout periods. To handle these periods, your application could implement and register a blackout opportunity detector that is responsible for handling blackout tags. When TVSDK encounters this tag, it polls all the registered content resolvers to find the first one that handles the specified tag. In this example, it is the blackout content resolver, which can, for example, replace the current item with alternate content on the player for the duration that is specified by the tag. Implement a custom opportunity/content resolver You can implement your resolvers based on the default resolvers. 1. Develop a custom ad resolver by extending the PTContentResolver abstract class. PTContentResolver is an interface that must be implemented by a content resolver class. An abstract class with the same name is also available and handles the configuration automatically (getting the delegate). Tip: PTContentResolver is exposed through the PTDefaultMediaPlayerClientFactory class. Clients can register a new content resolver by extending the PTContentResolver abstract class. By default, and