iOS Player SDK Guide


1.0 | Introduction

Use our iOS component to easily implement parts of our video management system in your iOS apps. 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 with the Blue Billywig webplayer and provides a bridge between iOS and Javascript. Use the guide below to place our video player within your app.

When to use the iOS SDK

We recommend using the iOS SDK when controlling the player directly from an app. This makes it possible to receive events from the player as well as to control the player (play, start, seek, etc).

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_TYPE%% (the device type)
%%ADVERTISING_IDENTIFIER_IS_LAT%% (the Limit Ad Tracking setting)

Implementing the iOS SDK is not required when the app is used to show a video without the need to control it from the app and/or using the player control bar to control the player. Additionally, 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.

Learn more about how to embed an inarticle ad in iOS UIWebview.

2.0 | Setting up the project

To get started, install cocoa pods by running:

gem install cocoapods

Next, run the following to get started with our example application:

pod try BlueBillywigPlayerSDK

Alternatively download our iOS Blue Billywig component. The component library download includes a documented example code. In the section below we will expand on how to use this component.

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

pod init

Next, add the following to the pod file:

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 and use the initWithPublication:@”[your publication name]” vhost:@”[your publication vhost]” method with the correct publication name 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:@“demo.bbvms.com"];

Create a BBPlayerSetup object to set the specific options for the player and specify a playout (read more about playouts):

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

It is recommended to apply a 100% width and 100% height in the playout settings (read more about playout dimensions). This makes it possible to size the player by sizing the webview.

It is also recommended to disable the fullscreen button (read more about disabling control bar buttons). Some devices can only play fullscreen video in the native player which might cause confusion when also using controls provided by our video player.

Now, either add a UIView to the storyboard and use 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 and add/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/personalized ads can be realized 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

Extra steps are necessary to enable the fullscreen player option at all times. First make sure that the playout 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

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

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 September 13, 2021

Was this article helpful?

Related Articles