Android SDK 4 Example Code Quick Start

The following process describes how to quickly build the OpenTV player app for Android using the example code.

Prerequisites

The following development tools need to be installed; the number in square brackets is the earliest supported version of the software and verified by Nagra.

Java SDK - Download the JDK [Java v8] from http://www.oracle.com/technetwork/java/javase/downloads/index.html.
Android Studio - Version 4.2 or higher version is used in this guide; download from http://developer.android.com/sdk/index.html.
Gradle version 6.7.1 and Gradle plug-in 4.2.2 for Android (can be installed through Android Studio).
A device running Android 4.4 or higher, connected to the PC via USB cable and recognised by the Android SDK.

The app requires a physical Android device with USB debugging enabled as per Android's guidelines (http://developer.android.com/tools/device.html); it will not work on an emulator.

NAGRA supplies the following files as part of your release:

The SDK package
The Operator Vault file (opvault.json) - specific for each customer

Overview of the example code

The example code archive (zip) is a collection of code snippets, each demonstrating one aspect of the SDK capabilities. The code is arranged so that each example can be built and run on an Android device. Each example code folder in the zip file contains an independent Android application project. The following examples are provided:

basic-playback Basic playback functionality with no encryption.
dynamic-ads-ima Demonstrates how and when ads are constructed and attached to a view utilising Google's Interactive Media Ads SDK (IMA).
preview-thumbnails Shows how to fetch and display WebVTT-based preview thumbnails.
prm-encrypted-playback Shows how to playback PRM-protected streams.
resolution-capping Shows how to limit playback resolution.
track-selection Shows how audio and subtitle tracks are selected.

Once you understand how the code works, you can use it in your own applications.

Specific streams and head-end addresses used to demonstrate the various functionalities may not be accessible in your own environment.

Building each example code

Example project structure

Each example is in a separate folder, containing an entire Android project, including:

.\build.gradle: A Gradle script that manages the dependencies and the build process
.\libs\: A folder to contain Java libraries
.\src\main\AndroidManifest.xml: A File configuring the application and the permissions it requires
.\src\main\java\: The source code of the example
.\src\main\res\: The resources folder for the application

Additional files to make the application build and run

Each of the example projects has a dependency on one or more Java libraries (.JAR files) and other files.

All projects need the SDK library. Copy one (and only one) of the SDK libraries to the .\libs\ folder of the project; copy either the opy-sdk-android-4.24.x-integration.jar (recommended for debugging) or the opy-sdk-android-4.24.x-production.jar library provided in the SDK package.

For PRM-protected content (the prm-encrypted-playback example), more files need to be copied:

The PAK libraries opy-sdk-android-4.24.x-cpakjava.securestorageagent-3.11.2.0.jar and opy-sdk-android-4.24.x-cpak-3.11.2.0.jar need to be copied to the .\libs\ folder of the project.
Copy your Operator Vault (opvault.json) to the .\src\main\res\raw\ folder. A version of this file matching the stream and head-end in the example code will already exist there but will need to be replaced if you want to change the settings to a stream hosted at your premises.

Building and executing an example with Android Studio

Once the additional files are copied:

Open Android Studio and connect an Android device (ensuring USB debugging is enabled).
Choose Open an existing Android Studio project and select the top directory of the example you want to build.
Android initiates opening the project and updates the dependencies configured in the build.gradle file.
At the configuration box, select the application configuration, click the green Play arrow button next to it and select the target Android device.
The application builds, installs on your device and starts executing.

Building and executing an example from the command line

Once the additional files are copied:

Open the Command/Terminal window and connect an Android device (ensuring USB debugging is enabled).
Navigate to the top directory of the example you want to build.
Execute the gradle wrapper command below to build the example code.
BASH
```
gradlew "assembleDebug"
```
This will build a debug apk executable package and place it in the .\build\outputs\apk\debug\ folder. Install this package on your device using:
BASH
```
adb install -r ./build/outputs/apk/debug/<example-name>-debug.apk
```
There should now be an icon in your application list to execute the example application.