iOS Player SDK Guide

1.0 | Introduction

Our iOS component makes implementing parts of our video management system in your iOS apps simple. It can be used for outstream (“stand-alone”) ads as well as normal video content (with pre- and post-roll ads). The component places a webview containing our webplayer and provides a bridge between iOS and javascript. Please refer to the guide below on how to place our video player within your app. Should you have any questions after reading this guide, please contact our Support Team:

When to use the SDK

Using the SDK is recommended when controlling the player directly from an app. This makes it possible to receive events like progress from the player, and also starting or pausing the video. An example for this could be only allowing to watch the second video when a question has been answered correctly. It’s also recommended if you need the device id to be available for advertisement capping / targeting. The SDK supports the following DfP-style macro’s:

%%ADVERTISING_IDENTIFIER_PLAIN%% (the device identifier)
%%ADVERTISING_IDENTIFIER_IS_LAT%% (the Limit Ad Tracking setting)

When not to use the SDK

If the app is simply used to show a video without having to control it from the app and/or using the player control bar to control the player, we do not advise using the SDK. Also, when most of the page is used to show a webpage with an embedded video, it’s difficult to place buttons to control the player. If you want to know how to embed an inarticle ad in iOS UIWebview, click here.

2.0 | Setting up the project

To get started, install cocoa pods by running:

gem install cocoapods

And then run the following to get started with our example application:

pod try BlueBillywigPlayerSDK

Alternatively download our iOS Blue Billywig component. In the component library there is a documented example code included. In the section below we will expand about how to use this component.

Start a new project and initialise a pod file by running:

pod init

Now add this to the Podfile:

pod 'BlueBillywigPlayerSDK'
pod update

After the update is complete the Blue Billywig SDK library has been added to the project. Add a new BBComponent object. Use the initWithPublication:@”[your publication name]” vhost:@”[your publication vhost]” method with the correct publicationname and vhost. This will create a new BBComponent object which you can use to create a new player. Example:

BBComponent *bbComponent =  [[BBComponent alloc] initWithPublication:@"demo" vhost:@“"];

Create a BBPlayerSetup object to set the specific options for the player. Also specify a playoutname which you created earlier in the VMS:

BBPlayerSetup *bbPlayerSetup = [[BBPlayerSetup alloc] init];
[bbPlayerSetup setPlayout:@"default"];

It is advised that you use a playout with 100% width and height. This way you can size the player by sizing the webview. It is also advised to disable the fullscreen button if you want full control over what controls the player uses (some devices can only play fullscreen video in the native player which can cause confusion when also using controls provided by our video player).

Now, either add a UIView to the storyboard and use this as a placeholder to place the player, or use a CGRect to programatically place the player.

2.1 | Placing the player with a storyboard

Add a Storyboard with a ViewController to the project then add and connect a UIView to it, which will be a placeholder where the BBPlayer component should be placed. Then create a BBPlayer object which references the UIView frame on the Storyboard:

self.bbPlayerWebView = [bbComponent createPlayer:self.playerViewPlaceholder.frame clipId:@"2119201" setup:bbPlayerSetup];

2.2 | Placing the player with a CGRect

Alternatively to just add the web view with a CGRect which defines x, y, width and height:

CGRect frame = CGRectMake(0, 500, 768, 450);
BBPlayer bbPlayerWebView = [bbComponent createPlayer:frame clipId:@"2119206" setup:bbPlayerSetup];

3.0 | Ad support

To support ads, we’ve added a setAdUnit function which can be used to display an ad defined in the Online Video Platform:

[bbPlayerSetup setAdUnit:@"<name of adunit>"];

The adunit name corresponds to the adunit code and can be found in “Ad services” -> “Ad units”. In the case of ads it’s not required to use createPlayer with clipId but instead:

[bbComponent createPlayer:CGRectMake(0, 0, width, height) setup:bbPlayerSetup];

Updating limit ad tracking/personalised ads can be done by calling:

[self.bbPlayerWebView showPersonalizedAds:<YES|NO>];

If the user has set “limit ad tracking” in the iPhone, this will take precedence over setting showPersonalizedAds to YES.

Catching errors can be done with:

[self.bbPlayerWebView on:@"adnotfound" parent:self function:@"adnotfound"];
[self.bbPlayerWebView on:@"aderror" parent:self function:@"aderror"];

4.0 | Fullscreen Player Setup

To be able to show the player fullscreen at all times, for example after clicking on the video, a couple of extra steps should be taken. First make sure that the playout that is used is configured to use a width of 100% and a height of 100%; Second, in the viewDidLoad function add (after initializing the bbPlayerWebview):

self.bbPlayerWebView.translatesAutoresizingMaskIntoConstraints = FALSE;

Third, to activate the full browser mode:

[self.bbPlayerWebView.topAnchor constraintEqualToAnchor: self.view.topAnchor].active = TRUE;
[self.bbPlayerWebView.bottomAnchor constraintEqualToAnchor: self.view.bottomAnchor].active = TRUE;
[self.bbPlayerWebView.leftAnchor constraintEqualToAnchor: self.view.leftAnchor].active = TRUE;
[self.bbPlayerWebView.rightAnchor constraintEqualToAnchor: self.view.rightAnchor].active = TRUE;

To deactivate full browser mode, set all the .active lines to FALSE;

5.0 | Further Setup

To be able to listen to predefined events also add the following line:

self.bbPlayerWebView.playerDelegate = self;

Finish by adding the BBPlayer to the main view.

[self.view addSubview:self.bbPlayerWebView];

6.0 | Delegates


The following delegates can receive events from the player:

Event name Description Related API function
onReady The player API is ready and functions can be called from the API.
onPlay The player has executed a play command. play()
onPause The player is now paused. pause()
onStarted The player has started for the first time. This event only happens once before the ended event.
onEnded Playback has stopped because the end of the media resource was reached.
onError The player has encountered an error which prevents it from playing the content further.
onLoadedClipData Clip data is loaded. getClipData()
onFullscreen The player is now fullscreen. fullscreen()
onRetractFullscreen The player is now not fullscreen. retractFullscreen()
destroy Cleanup the webview/player after calling removeFromSuperview

These delegates can also be found in the BBPlayer.h file below @protocol BBPlayerEventDelegate. Example:

-(void) onStarted{
    NSLog(@"The player has started playing");

Furthermore, all events described in the player API can be bound to using the on method (see methods).

7.0 | Methods


The following methods can be called on the BBPlayer object:

Method name Description
play Start playback
pause Pause playback
getCurrentTime Returns a float of the current media offset time in seconds
fullscreen Make the player go to fullscreen mode
retractFullscreen Retract fullscreen mode
isPlaying Returns true when the media is currently playing and false when it is not
isFullscreen Returns true when the player is currently fullscreen and false when it is not
Method name Arguments Description
loadclip clip ID (string) Load the specified clip (id) into the player.
seek timeInSeconds (float) Seek to the time offset in seconds
on eventName (string)callbackFunction (string)targetObject (object) With the on method, you can bind to any of the events that are listed in the player API events. This is useful for any event that is not in the delegate list.
call methodName (string)argument (json string) Call any other method on the player API methods that is not in the list above.

Some examples:

//Start playing the player:
[self.bbPlayerWebView play];

// Load a new clip into the player:
[self.bbPlayerWebView loadClip:@"2337181"];

// Bind to the playing event (Execute the "onPlayerPlaying" method of the parent "self" when the player throws the "playing" event):
[self on:@"playing" parent:self function:@"onPlayerPlaying"];

// Load a clip with a token through the call method
[self.bbPlayerWebView call:@"load" argument:@"{\"type\":\"LoadParams\", \"clipId\":\"2337181\", \"token\": \"1ffdf19e65c37a3871577e0bd4ed20516640ec5d\"}"];

8.0 | iOS Whatsapp Fix

Following error shows when checking canOpenURL:

Error message

failed for URL: “whatsapp://” – error: This app is not allowed to query for scheme whatsapp

In iOS 9 you must whitelist any URL schemes your App wants to query in Info.plist under the LSApplicationQueriesSchemes key.

9.0 | Deploy and debug information

For debugging/testing in the iPhone/iPad and simulator the zip file contains a fat debug library in the BBComponent/bin/lib/debug directory already added to the project. The playout that is used will need the ‘Force “can autplay”‘ setting turned on, please ask support if this option isn’t available in the behavior tab.

The release build contains 2 libraries. To test the release on iPhone/iPad and simulator in the BBComponent/bin/lib/release-all directory. For iOS submission an iPhone only release build for arm and arm64 in the BBComponent/bin/lib/release-arm directory.

Updated on August 25, 2020

Was this article helpful?

Related Articles