Support for our web based mobile SDK ended on January 1st, 2023. Technical issues will no longer be resolved nor will any security updates be released.
To implement the Blue Billywig player into your app: please visit our native player SDK documentation to get started or contact us at support@bluebillywig.com. We will gladly help you get started with our native mobile SDK.
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.
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 (version 1.4.1.39). 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"];
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
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 |
playerInView | Call when the player is in view |
playerOutView | Call when the player is out of view |
| 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:
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.