IRIS.TV Android plugin Example

Project: App

The example app. Classes MainActivity and IrisBrightcoveExampleFragment provides the example usage.

Project: IRIS.TV.control

The IRIS.TV library, contains the IRIS.TV recommendation plugin, and a fragment for convenience.

Integration

To include the IRIS.TV plugin, the maven repository and library dependency must be added to the project's gradle file:

repositories {
    maven {
        url 'https://dl.bintray.com/iris-tv/IrisBrightcoveAndroid'
    }
}

dependencies {
    compile 'tv.iris.api:brightcove:1.0.8'
}

Usage

The IRIS.TV library provides a Fragment, IrisBrightcovePlayerFragment, this decends from and can replace the standard BrightcovePlayerFragment.

As with inheriting from the BrightcovePlayerFragment the developer must inflate their layout, then locate the BaseVideoView, assign to brightcoveVideoView before calling super.onCreateView. Example:

@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
    View view = inflater.inflate(R.layout.fragment_main, container, false);
    brightcoveVideoView = (BaseVideoView) view.findViewById(R.id.brightcove_video_view);
    super.onCreateView(inflater, container, savedInstanceState);
    return view;
}

There are additional abstract methods to implement to provide the fragment with access tokens needed by the IRIS.TV API. These include:

// This is your IRIS provided ID, used to identify you as a client
private final String ClientToken = "yourClientToken";

// This is your IRIS.TV API access token provided by IRIS
private final String IrisToken = "yourAccesToken";

// This is your Brightcove Cagalog Service Media API Token
private final String CatalogToken = "yourBrightcoveCatalogToken";

// This is the video reference ID from the Brightcove CMS
private final String initialVideoPlatformId = "yourVideoPlatformId";

with the methods:

@Override
protected Catalog getCatalog() {
    return new Catalog(CatalogToken);
}

@Override
protected String getIrisToken() {
    return IrisToken;
}

@Override
protected String getClientToken() {
    return ClientToken;
}

Note: If you are using Brightcove's Playback Service API instead of the Media API to create your Catalog, this repository's playback_api branch includes the necessary support. In this case, add your Playback Service Policy Key to your list of token strings and alter the above override of the getCatalog() function as follows:

@Override
protected Catalog getCatalog() {
    return new Catalog(brightcoveVideoView.getEvenEmitter(), ClientToken, PolicyKey);
}

It is recommended to use the provided catalog to look up the initial video and not add direct by url or you may experience the same video repeating rather than recommendations from IRIS.TV.

@Override
protected void startInitialVideo(Catalog catalog) {
    catalog.findVideoByID(initialVideoPlatformId, new VideoListener() {
        @Override
        public void onVideo(Video video) {
            brightcoveVideoView.add(video);
            brightcoveVideoView.start();
        }

        @Override
        public void onError(String s) {
            Log.e(TAG, "Error finding initial video in catalogue " + s);
        }
    });
}

Configuring the plugin

The plugin may be configurable in order to obtain the list of recommendation and to set the number of recommendations. By default the number of recommendations is set to 5 and the minimum and maximum number is 1 and 20 respectively.

@Override
public void setUpPlugin(IrisBrightCoveRecommendationPlugin.Builder pluginBuilder) {
    pluginBuilder.numberOfRecommendations(numberOfRecommendations)
            .addRecommendationListener(new IrisBrightCoveRecommendationPlugin.RecommendationsListener() {
                                @Override
                                public void onRecommendationsChange(List<Recommendation> recommendations) {

                                }
                            });
}

Skipping to N

The normal flow for playback is control by the player but in some cases you may need to skip to a index N from the list. In order to achieve this you need to use BaseVideoView as follow.

ClickListener listener = new ClickListener() {
    @Override
    public void itemClicked(final int position) {
        instanceOfBaseVideoView.getEventEmitter().request(IrisEventType.SKIP, new HashMap<String, Object>() {{
                        put(IrisEventType.NUMBER_TO_SKIP, position);
                    }}, new EventListener() {
                        @Override
                        public void processEvent(Event event) {
                        }
                    });
    }
};

Adjusting the controls

Controls can be adjusted in the same way as when desending from BrightcovePlayerFragment, by providing layouts called default_media_controller.xml, and/or overriding the definined strings and drawables. Note that after calling super.onCreateView(inflater, container, savedInstanceState); the controls will be findable by id for hooking up the onClick or styling.

There are two additional strings:

<string name="brightcove_controls_skip_back">&#xf048;</string>
<string name="brightcove_controls_skip">&#xf051;</string>

The skip buttons use font awesome, which is packaged with the brightcove aar. There are also the thumb up and down buttons and they use a drawables called like/dislike/like_active.

Advanced Usage

If the fragment is not suitable developers can make direct use of the IrisBrightCoveRecommendationPlugin with any BaseVideoView it is best to refer to the IrisBrightcovePlayerFragment for example usage.

Events

The IRIS.TV plugin emits and receives additional events. These are constant strings in the class IrisEventType. Please see this file or class for documentation.

Continuous Play

The IRIS.TV plugin continues ahead to the next queued video upon playback completion by default. To alter this functionality or disable continuous play, use the publicly accessible function setContinousPlay(boolean contPlay) from the IrisBrightCoveRecommendationPlugin class. The example app utilizes this function to disable continuous play until a video from the RECOMMENDED VIDEOS list is tapped, at which point continuous play is re-enabled.

Known issues

Loss of aspect ratio

During transition between videos either from a skip or a completed video, the previous video is briefly stretched to fill the player's View dimensions ignoring its aspect ratio.

Still image urls are not shown

In order to prevent a crash of the brightcove player the plugin removes any "stillImageUri" like so: video.getProperties().remove("stillImageUri"); This means they do not show.

#Typical sequence of events

Typical sequence of events