iOS player SDK guide


With our iOS component we try to make implementing parts of our video management system in your iOS apps as easy as possible. 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:

To SDK or not to SDK

If the app is used to just 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, this will make it hard if not impossible to place buttons to control the player.

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)

Getting started with the iOS Component

To get started, install cocoa pods by running

gem install cocoapods

and then run

pod try BlueBillywigPlayerSDK

to get started with our example application.
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.

Setting up the project

Start a new project and initialize a pod file by running

pod init

Now add

pod 'BlueBillywigPlayerSDK'

to the Podfile


pod 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.


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. 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)

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

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.

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];

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];

Ad support

To support ads, we've added a setAdUnit function which can be used to display an ad defined in the OVP.

[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/personalized 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"];

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];


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.


-(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).


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\"}"];

IOS Whatsapp fix

Following error shows when checking canOpenURL:

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.

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.