README.md

One Mobile SDK for Android

This SDK provides easy way to integrate video playback inside your application with high customization ability, advertisement support, metrics and O2 video provider integration.

Release notes can be found here.

Introduction

SDK consists of several core classes:

• OneSDK - core class, entry point that constructs Player with O2 metrics attached and O2 playlist or video[s].

• Player - main class that handles all internal logic for playback, advertisement and metrics.

• PlayerView - content video and advertisement rendering view

• Binder - helper class that manages connection between Player and PlayerView

• PlayerFragment - easy to use fragment with PlayerView and properly constructed Binder.

Integration guide

Gradle integration

In dependencies section of modules build.gradle add reference to SDK library:

// Add SDK maven repository
allprojects {
    repositories {
        maven { url 'https://raw.github.com/aol-public/OneMobileSDK-releases-android/maven/' }
    }
}

apply plugin: 'com.android.application'

android {
    // ...
}

dependencies {
    // ...

    // AOL ONE Mobile SDK
    compile 'com.aol.one.publishers.android:sdk:2.12' // Use latest version

    // ...   
}

Javadoc can be found here. You can attach them in Android Studio manually using this guide.

Sources integration

To start using the ONE Mobile SDK, you will first need to construct an instance of OneSDK.

new OneSDKBuilder(getApplicationContext())
    .setEnvironment(environment)
    .create(new OneSDKBuilder.Callback() {
            public void onSuccess(OneSDK oneSDK) {

            }

            public void onFailure(Exception error) {

            }
        });

(Environment can be PRODUCTION -or- STAGE)

Use setExtra(JSONObject extra) to set Extra data for OneSDK request (optional parameter)

Next step will be obtaining a Player instance using PlayerBuilder

PlayerBuilder playerBuilder = sdk.createBuilder();

PlayerBuilder has many parameters that can be modified:

• vvuidGenerator
• autoplay
• modelTransformer
• prerollPodSize
• siteSection

Then create player by videoId

playerBuilder.buildForVideo(String videoId, Player.Callback callback);

-or- by an array of videoId

playerBuilder.buildForVideoList(String[] videoIds, Player.Callback callback);

-or- by playlistId

playerBuilder.buildForPlaylist(String playlistId, Player.Callback callback);

If you want to check some received data you can use

playerBuilder.requestForVideo(String videoId, VideoProvider.Callback callback);
playerBuilder.requestForVideoList(String[] videoIds, VideoProvider.Callback callback);
playerBuilder.requestForPlaylist(String playlistId, VideoProvider.Callback callback);

and then call

playerBuilder.buildFrom(VideoProviderResponse videoProviderResponse)

with VideoProviderResponse

Using Binder instance connect PlayerView to Player:

PlayerView playerView = new PlayerView(context);
Binder binder = new Binder();

binder.getPlayerView(playerView);
binder.setPlayer(player);

Snap Binder to Android UI lifecycle:

public onPause() {
    binder.onPause();
}

public onResume() {
    binder.onResume();
}

public void onDestroy() {
    playerView.dispose();
    binder.onDestroy();
}

Or you can use PlayerFragment:

PlayerFragment playerFragment = // ... Constructed PlayerFragment

playerFragment.getBinder().setPlayer(player);

For handling player errors, add ErrorListener

player.addErrorListener(new ErrorListener() {
    public void onError(ErrorState errorState) {
    }
});

You can add custom detectors of player state

player.addPlayerStateObserver(new DecileDetector(new DecileDetector.Callback() {
    //You can use any detector from package com.aol.mobile.sdk.player.listener.detector
    public void onDecileDetected(@NonNull Properties properties, int i) {
    }
}));

player.addPlayerStateObserver(new PlayerStateObserver() {
    //You can use any custom detector witch detect any state by properties
    public void onPlayerStateChanged(@NonNull Properties properties) {
    }
});

All done!

Player controls

SDK provides easy and flexibly approach for video controls and behavior customization. Key class UiProperties represent basic view model that will be rendered to user and ControlsFeedbackHandler interface implementation is responsible for controls behavior modification.

Theming of controls

PlayerControlsView introduces setMainColor and setAccentColor methods together with mainColor and accentColor xml attributes for enhanced controls coloring support.

Usage in Java:

  PlayerControlsView controls = (PlayerControlsView) playerView.getContentControls();
  controls.setMainColor(0XFFFFFF);
  controls.setAccentColor(0XB53087);

Usage in xml:

<com.aol.mobile.sdk.controls.view.PlayerControlsView
      android:id="@+id/controls"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      app:mainColor="@color/main_controls_color"
      app:accentColor="@color/accent_controls_color" />

Hiding of buttons

To hide some particular button you will need to extend PlayerControlsView and override render method:

void render(UiProperties props) {
    props.isSeekForwardButtonVisible = false;
    props.isSeekBackButtonVisible = false;
    super.render(props);
}

Snippet above will hide +/- 10 sec seek buttons. Each property can be modified to achieve required UI.

Next what you should do is set your implementation of controls to PlayerView using:

PlayerView player view = ...
playerView.setVideoControlsView(yourCustomControlsView);

Custom controls

In case when you need fully customized UI you will have to implement PlayerControls interface. You will have to properly render UiProperties inside render method like this:

public void render(UiProperties props) {
    // Render of loading indicator
    if (progressView.getVisibility() != VISIBLE && props.isLoading) {
        progressView.setVisibility(VISIBLE);
    } else {
        progressView.setVisibility(GONE);
    }
    // And all other controls
}

Also inside setListener you may be passed with listener that should be used to propagate SDK with user interaction via controls.

Behaviour modification

Interface ControlsFeedbackHandler and class DefaultFeedbackHandler are responsible for interaction of SDK with ui controls. For example if you need to override play button with custom action, you will have to extend DefaultFeedbackHandler and override onButtonClickMethod:

public class DefaultFeedbackHandler extends DefaultFeedbackHandler {
    public void onButtonClick(Player player, ControlsButton button) {
        switch(button) {
            case PLAY:
                // Do some important stuff
                break;

            default:
                super.onButtonClick(player, button);
                break;
        }
    }
}

then set your custom ControlsFeedbackHandler to Binder

binder.setFeedbackHandler(new MyDefaultFeedbackHandler());

Chromecast support

dependencies {
    // ...

    // Chromecast
    compile 'com.aol.one.publishers.android:chromecast:1.0'

    // ...   
}

Add meta-data with castId of application to Manifest.xml (https://developers.google.com/cast/docs/registration)

<manifest>
    <application>
      <!-- ...-->
        <meta-data
            android:name="com.aol.mobile.sdk.chromecast.ReceiverApplicationId"
            android:value="appCastId" />
    </application>
</manifest>