Android player SDK guide

Introduction

With our Android component we try to make implementing parts of our video management system in your Android apps as easy as possible.

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: support@bluebillywig.com

The component places a webview with our webplayer in it and provides a bridge between Android and javascript.

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 progess 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 anwsered correctly.

Getting started with the Android Component

To get started, download our Android Blue Billywig component.

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

Setting up the project

  • We have a maven gradle import, to use this add

    dependencies {
    implementation 'com.github.bluebillywig:BlueBillywigPlayerSDK:1.4.1'
    }

    to your project build.gradle file.
    This way you can easily stay up to date with our library.

The latest version of the library can be found by visiting the Maven repository

  • Alternatively start a new project and add bbcomponent.jar from the zip file above to the lib directory.
    • Right-click on libs, select Import, select General and File System
    • Browse to the directory containing the library and select the library from the build directory inside the zip file

There is one library included which is compatible with version 4.4 (kitkat v19) and up.

Android changed the way that a webview can receive javascript events, for more security. This means there is a major difference between version 16 and 17 (and up). Unfortunately this means that the new way to receive javascript events is not backwards compatible with android revisions 16 and lower.


Add a new BBComponent object. Use the constructor of the BBComponent 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 = new BBComponent("demo", "demo.bbvms.com");

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.

BBPlayerSetup playerSetup = new BBPlayerSetup();
playerSetup.setPlayout("androidapp");

BBPlayer bbPlayer = bbComponent.createPlayer(this,"2119201",playerSetup);

The getActivity() function can be used instead of this when using Fragments, this is used when placed directly in an Activity. Add the BBPlayer to the layout by using the addView function of a layout.

Ad support

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

    playerSetup.setAdunit('<name of adunit>');

The adunit name corresponds to the adunit code and can be found in "Ad services" -> "Ad units".

Catching ad errors can be done with:

    webView.on("aderror", this, "onAdError");
    webView.on("adnotfound", this, "onAdNotFound");

Delegates

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

// This will catch onPlay events and send them to the onPlay callback function defined below
bbPlayer.on("play",this,"onPlay");

public void onPlay(){
    Log.d("MainActivity","onPlay event caught");
}

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), arguments (json string) Call any other method on the player API methods that is not in the list above.

Some examples:

//Start playing the player:
bbPlayer.play();

// Load a new clip into the player:
bbPlayer.loadClip("2337181");

// Bind to the playing event (Execute the "onPlayerPlaying" method of the parent "this" when the player throws the "playing" event):
bbPlayer.on("playing",this,"onPlayerPlaying");

Troubleshooting

Android 8+ has a restriction which does not allow cleartext messages anymore.
This will prevent the player from loading.

To circumvent this add cleartextTrafficPermitted=“true” to the app manifest file to make it work again.
For more information: https://stackoverflow.com/questions/45940861/android-8-cleartext-http-traffic-not-permitted#answer-52832240