Skip to main content

Android Native SDK

Latest version: 1.17.0

Sample Android App

Javadocs

This SDK enables you to securely stream DRM-protected videos through your Android app.

Getting Started

1. Adding dependency

If you have a settings.gradle file in your project root, then you need to add the repositories in the settings.gradle inside dependencyResolutionManagement. Else, this will go in build.gradle file in project root.

repositories {
    // other repo, e.g. google() or mavenCentral()
    maven{
        url "https://github.com/VdoCipher/maven-repo/raw/master/repo"
    }
}
// use the latest available version
implementation 'com.vdocipher.aegis:vdocipher-android:1.17.0'

Note: If your project has a local dependency on a previous version of the SDK (AAR module dependency), you'll need to remove them from the project.

// remove this dependency if it exists from use of a previous version of SDK
compile project(':vdocipher')

2. Integrating player fragment

VdoCipher provides two methods for integrating player into your application:

Integrate Player With UI Controls

Drop a VdoPlayerUIFragment into your activity layout with an id. This is the fastest and easiest way to integrate the player into your application. VdoPlayerUIFragment includes a prebuilt UI for the player with ample features and functionality.

<fragment
    android:name="com.vdocipher.aegis.ui.view.VdoPlayerUIFragment"
    android:id="@+id/vdo_player_fragment"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_gravity="center"
    android:keepScreenOn="true"/>
    <!-- app:handleBackPress="false" to handle back press actions in activity's onBackPressed()-->

and receive its instance in your activity using findFragmentbyId()

playerFragment = (VdoPlayerUIFragment) getSupportFragmentManager().findFragmentById(R.id.vdo_player_fragment);
Picture in picture

With SDK version 1.17.0, the player controls now feature an option to switch into picture-in-picture mode starting Android 8.0 (API level 26), allowing users to watch a video in a small window pinned to the corner of the screen while navigating between apps or browsing content. Also, specify that your activity handles layout configuration changes so that your activity doesn't relaunch when layout changes occur during PiP mode transitions.

VdoPlayerUIFragment takes activity into picture-in-picture mode only if parent activity supports it, make sure to add android:supportsPictureInPicture="true" in manifest file at activity level to allow picture-in-picture.

<activity
        android:name=".PlayerActivity"
        android:supportsPictureInPicture="true"
        android:launchMode="singleTask"
        android:configChanges="keyboardHidden|orientation|screenSize|smallestScreenSize|screenLayout"/>

Once supportsPictureInPicture="true" is added in manifest file, make sure to call setPictureInPictureSupport(true) on VdoPlayerUIFragment to notify player that activity can go in PiP mode, in addition, you may want to hide other UI elements when the activity is in PiP mode, note that player fragment automatically handles its UI once activity goes into PiP mode.

Listen for PiP mode change events as shown below.

addOnPictureInPictureModeChangedListener(pictureInPictureModeChangedInfo ->
        {
            if (pictureInPictureModeChangedInfo.isInPictureInPictureMode()) {
                //Hide other UI elements of activity
            } else {
                //Show other UI elements of activity
            }
        });
Save offline without OTP

From SDK version 1.13.0, the save offline feature allows you to save encrypted media files locally and enjoy playback without relying heavily on the internet. Please make a note that in order to play these saved videos, a connection to the internet is still required to authenticate the playback.

During the construction of the VdoInitParams object, just call enableOfflinePlayback() on VdoInitParams.Builder() to use locally saved files instead of streaming remotely. Without enabling offline playback the player will ignore locally saved files even if they are present and start streaming remotely.

VdoInitParams vdoParams = new VdoInitParams.Builder()
    .setOtp(...)
    .setPlaybackInfo(...)
    .enableOfflinePlayback() //Enable offline playback to ensure locally saved media is used.
    .build();
Save offline with OTP

SDK version 1.17.0 allows you to pass persistent OTP (OTP that allows video download) via a callback when the video is about to be downloaded.

playerFragment.addOnSavedOfflineListener(mediaId -> {
            String persistentOtp = Utils.getPersistentOtp(mediaId); //Generate your persistent otp for video download.
            return persistentOtp; //Returning null will make video to be downloaded without license key (same as 'Save offline without OTP').
        });
note
  • VdoPlayerUIFragment method supports TV applications only SDK version 1.14.2 onwards.
  • By default first call to onBackPressed() is handled by VdoPlayerUIFragment to manage player orientation and state, then subsequent calls are passed to the attached activity. Use app:handleBackPress="false" to disable this behaviour and handle all calls in activity's onBackPressed().
  • When offline playback is enabled, if the video cannot be found locally, the player will start playing online.

Alternative: Player Without Controls

Drop a VdoPlayerSupportFragment into your activity layout with an id. By using this method, you have full control over the player's UI and functionality. Using the APIs available, you can create your own custom UI components and implement player functionality. 

<fragment
    android:name="com.vdocipher.aegis.player.VdoPlayerSupportFragment"
    android:id="@+id/vdo_player_fragment"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_gravity="center"
    android:keepScreenOn="true"/>

and receive its instance in your activity using findFragmentbyId()

playerFragment = (VdoPlayerSupportFragment) getSupportFragmentManager().findFragmentById(R.id.vdo_player_fragment);

3. Initializing Player And Starting Playback

Now get a VdoPlayer instance by calling PlayerHost.initialize() method on the playerFragment and receive the player in the onInitializationSuccess callback.

You can add callbacks for listening to playback events using VdoPlayer.addPlaybackEventListener() on the VdoPlayer object that is received in the onInitializationSuccess callback.

playerFragment.initialize(PlayerActivity.this);
...
...
@Override
public void onInitializationSuccess(PlayerHost playerHost, VdoPlayer player, boolean wasRestored) {
    Log.i(TAG, "onInitializationSuccess");
    this.player = player;

    // add a listener for playback events
    player.addPlaybackEventListener(playbackListener);
    // ...
}

Once you have a player, you can start loading media onto it for playback. You'll need a VdoInitParams object to specify which media to load along with your playback preferences.

A VdoInitParams object needs playbackInfo and either otp or signature generated from your server.

// load a media to the player
VdoInitParams vdoParams = VdoInitParams.createParamsWithOtp(otp, playbackInfo);
player.load(vdoParams);

This should be followed by onLoading and onLoaded callbacks signalling that media playback can start now.

@Override
public void onLoading(VdoInitParams vdoInitParams) {
    Log.i(TAG, "onLoading");
}

@Override
public void onLoaded(VdoInitParams vdoInitParams) {
    Log.i(TAG, "onLoaded");
    // playback can be controlled now
}

Guides

Handling orientation change

To make orientation change seamless, please override config changes for your activity by adding the following to your AndroidManifest.xml. This means that your activity won't go through the regular life-cycle events on device orientation change. If you require to change the layout, please use onConfigurationChanged callback in your activity to change the size or hide/unhide view elements.

Replace the name of activity with correct name.

<activity android:name=".PlayerActivity"
    android:configChanges="keyboardHidden|orientation|screenSize">
</activity>

Using ProGuard

If you use ProGuard in your app, you might need to add the following rule to your ProGuard file.

-keep class com.vdocipher.aegis.* { *;  }

Offline Download using SDK

The VdoCipher Android SDK offers capability to download videos to the device's local storage. Videos would then be available for offline playback. This feature is available for Android devices running Lollipop and above (API level 20+).

Steps for Offline Android download for videos »

SafetyNet implementation in your Android App for enhanced Emulator protection

Safetynet Implementation via Google APIs allow higher app based security and ensures playback only in genuine physical devices

Steps for SafetyNet integration for higher security on app side »

Block devices with ADB debugging for higher security

Some users switch on ADB debugging in phone. For higher security, it should be blocked. We have kept this optional as there will be few users who will not be able to play without switching ADB debugging off. To block playback on devices with ADB debugging turned ON, use the setAllowAdbDebugging method of VdoInitParams.Builder when making the vdoParams:

VdoInitParams vdoParams = new VdoInitParams.Builder()
  .setOtp(...)
  .setPlaybackInfo(...)
  .setAllowAdbDebugging(false)
  .build();

To ensure that such blocked users get useful message so that they can switch off ADB debugging and play the video, please handle the error code 1202 as shown in this sample code change in sample code. This will handle the error code and show a useful message to users.

You can resume video from last viewed position

If you want to play the video from last viewed position rather than the beginning of the video, then that can be configured using

enableAutoResume() method of VdoInitParams.Builder when making the vdoParams:

VdoInitParams vdoParams = new VdoInitParams.Builder()
  .setOtp(...)
  .setPlaybackInfo(...)
  .enableAutoResume()
  .build();

Also a callback can be added on the playback event using VdoPlayer.setAutoResumeCallback() of the VdoPlayer object which was received from the onInitializationSuccess callback.

playerFragment.initialize(PlayerActivity.this);
...
...
@Override
public void onInitializationSuccess(PlayerHost playerHost, VdoPlayer player, boolean wasRestored) {
    Log.i(TAG, "onInitializationSuccess");
    this.player = player;
    
    // add a listener for AutoResumeCallback event
    player.setAutoResumeCallback(new AutoResumeCallback() {
        @Override
        public void autoResumeVideo(long savedSeekPosition) {
            player.seekTo(savedSeekPosition);
        }
    });
    // ...
}