Android BO Adapter

About

This is the repository for the Android Back Office Adapter for the DIVA 5 player.

The Adapter simplifies use of the DIVA video player by providing the following services to DIVA, which are required to play videos:

• Video metadata provider - to provide required video details
• Entitlements - to check a user is entitled to play a video
• Entitlements heartbeat - constantly checks entitlement during playback
• Dictionary - for ui translations
• DIVA Player settings
• Live to VOD
• Conviva or Youbora Analytics

Using the Adapter in your Project

Add the Library

To include the Adapter in you Android project add the following dependency.

For Android projects add:

com.deltatre.diva:diva-mobile-divaboadapter:/

For Android TV projects add:

com.deltatre.diva:diva-tv-divaboadapter:/

In order to access any DIVA libraries you need to provide a 'github.properties' file in the root of your project containing your user name and your Github Personal Access Token. Ensure the PAT has been generated with package access applied (select the relevant box in GitHub)

github.usr={githubuser} github.key={personalaccesstoken}

DivaBoAdapter itself depends on DIVA libraries. The current versions of DIVA libraries required are:

com.deltatre.diva:divaplayermobile:/ (Android mobile apps) com.deltatre.diva:divaplayertv:/ (Android TV apps)

DivaBoAdapter integrates with both Conviva and Youbora analytics libraries and the following must be added to gradle repositories:

maven { url "https://npaw.jfrog.io/artifactory/youbora/" }

Initialising a DIVA Instance

The BO Adapter is initialised and returns a DIVA instance by calling DivaBoAdapter.createDivaFragment(). An example of Adapter initialisation is:

    val divaExtraParams = DivaExtraParams(
            divaListener = divaListener,
            analyticsCustomTagGenerator = this::customTagGenerator,
            analyticsCustomContentDimensionGenerator = this::customContentDimensionGenerator,
            videoMetaDataMap = this::videoMetadataMapper
        )

    DivaBoAdapter(context, lifecycleScope).createDivaFragment(
        settingsUrl,
        langCountryCode,
        videoId,
        userExternalId,
        ::getCurrentUserAccountAccessToken,
        sharedKey,
        conf,
        divaExtraParams,
        ::onError,
        onSuccessExtra = {
                Log.d("DIVA", "BO source origin: ${it.origin}")
            }){ divaFragment ->
            supportFragmentManager.navigate(R.id.mainContainer, divaFragment)
        }

Initialisation Parameters

context An Android UI Context. In an Activity it is normally this.
lifecycleScope a CoroutineScope managed by the Activity lifecycle. From an Activity this will be lifecycleScope provided by lifecycle-runtime-ktx.
settingsUrl The response from this url provides the rich information required by the BO Adapter to run the services required by DIVA. The last part of the path is the device type, which is either 'android' or 'androidtv'. langCountryCode This must have the format: 'en-US', 'ar-QA'.
videoId The external videoId to be played e.g. 'bae2c2aa-0f4e-4113-8f33-ce41b6267cc9'.
userExternalId Used in analytics. Often it takes the form of a GUID e.g. '36c19c12-df35-4f13-ae8a-78e8b1268717'.
getCurrentUserAccountAccessToken A callback method to return the current access token. Used in the entitlement request. This token may occasionally change during playback so this is a callback method and not a simple string parameter.
sharedKey Key shared between Back Office and Front End apps to allow encryption of entitlementCheck section in Settings.
divaExtraParams This object contains various parameters which may be passed through to DIVA. See DIVA documentation for details of the parameters.
onError This block (or method reference) is called if an error occurs during Adapter initialisation. It would typically display an error message and close the diva activity.
onSuccess This block (or method reference) is called after successful initialisation of DIVA. The initialised DIVA fragment is returned. Typically this block displays the fragment in the activity.

Example Apps

An example app for Android is here and for Android TV here.

Contributors

Below are notes for developers contributing to the DivaBoAdapter project, not for users of the DivaBoAdapter.

Gradle also runs tests before building

./gradlew clean ./gradlew build

Package publishing

To publish a new version of the Android BO Adapter:

1. Update PackagesVersion in packages.gradle
2. Commit and push to github on master branch
3. Run the Github Action: 'Maven Packages Publish'

The above Publish github action is automatically run if you push a tag beginning with 'v' to github e.g. 'v1.0.0'.

Snapshots may be published using the 'Maven Packages Publish SNAPSHOT' github action. Only Snapshots overwrite the previous snapshot published.

Publishing uses maven publish and GitHub packages.

./gradlew publish

or use following to publish single package module

./gradlew publishDiva_core_divaboadapterPublicationToMavenRepository ./gradlew publishDiva_mobile_divaboadapterPublicationToMavenRepository ./gradlew publishDiva_tv_divaboadapterPublicationToMavenRepository

In order to use gradle publishing you need to provide a 'github.properties' file in the root of your project containing your user name and your Personal Access Token. Ensure the PAT has been generated with package access applied (select the relevant box in GitHub)

i.e. github.usr={githubuser} github.key={personalaccesstoken}