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'

and run:

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.

To open ads in a browser window in place of the webview:

[bbPlayerSetup setOpenAdsInNewWindow: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 nameDescriptionRelated API function
onReadyThe player API is ready and functions can be called from the API.
onPlayThe player has executed a play
onPauseThe player is now paused.pause()
onStartedThe player has started for the first time. This event only happens once before the ended event.
onEndedPlayback has stopped because the end of the media resource was reached.
onErrorThe player has encountered an error which prevents it from playing the content further.
onLoadedClipDataClip data is loaded.getClipData()
onFullscreenThe player is now fullscreen.fullscreen()
onRetractFullscreenThe player is now not fullscreen.retractFullscreen()
destroyCleanup 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 nameDescription
playStart playback
pausePause playback
getCurrentTimeReturns a float of the current media offset time in seconds
fullscreenMake the player go to fullscreen mode
retractFullscreenRetract fullscreen mode
isPlayingReturns true when the media is currently playing and false when it is not
isFullscreenReturns true when the player is currently fullscreen and false when it is not
playerInViewCall when the player is in view
playerOutViewCall when the player is out of view
Method nameArgumentsDescription
loadclipclip ID (string)Load the specified clip (id) into the player.
seektimeInSeconds (float)Seek to the time offset in seconds
oneventName (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.
callmethodName (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 July 26, 2021

Was this article helpful?

Related Articles