Getting Started

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

Latest version: 1.27.1

Java

Java Sample Application: Explore the Java implementation.

Java API Reference: Comprehensive Java API docs.

Kotlin

Kotlin Sample Application: Check out the Kotlin version.

Kotlin API Reference: Detailed Kotlin API docs.

Step 1: Installation

1. Add Repositories:

If your project has a settings.gradle file, add the repositories inside dependencyResolutionManagement. Otherwise, add them in the build.gradle file at the project root.

repositories {
    // other repositories, e.g., google() or mavenCentral()
     maven {
        url "https://github.com/VdoCipher/maven-repo/raw/master/repo"
    }
 }

2. Add Dependencies:

Include the VdoCipher SDK in your app's build.gradle dependencies block. Use the latest version for the best compatibility.

dependencies {
    implementation 'com.vdocipher.aegis:vdocipher-android:1.27.1'
}

3. Proguard Configuration:

If your app uses ProGuard, update the android/app/proguard-rules.pro file with the following rules:

-keep class com.vdocipher.aegis.* { *; }
-keep class androidx.media3.common.MediaLibraryInfo { *; }

4. Add Permission for Media Playback:

To enable background playback in your app, you need to declare the FOREGROUND_SERVICE_MEDIA_PLAYBACK permission in your AndroidManifest.xml file when target SDK version is set as 34 and higher.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

    <application
    ..>
    ..
    </application>
</manifest>

tip

You need to declare this permission only if you choose to change playback behavior. Please find more about different playback behaviors here.

Step 2: Player Integration

1. Add Player Fragment:

Insert a VdoPlayerUIFragment into your activity layout. This fragment provides a prebuilt player UI with rich features.

<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"/>

Want to create custom controls?

If you want to create custom controls, disable the default controls by setting app:showControls="false".

<fragment
    android:name="com.vdocipher.aegis.ui.view.VdoPlayerUIFragment"
    .....
    app:showControls="false"/>

2. Get Fragment Instance:

Retrieve the fragment instance in your activity.

Java

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

Kotlin

 val playerFragment = supportFragmentManager.findFragmentById(R.id.vdo_player_fragment) as VdoPlayerUIFragment

Step 3: Initializing the Player and Starting Playback

1. Initialize the Player:

Start by obtaining a VdoPlayer instance by calling the initialize() method on the playerFragment. You'll need to pass an InitializationListener to this method to receive the VdoPlayer instance.

Java

playerFragment.initialize(initializationListener);

Kotlin

playerFragment.initialize(initializationListener)

2. Implement the Initialization Listener:

Declare and implement the InitializationListener to handle the initialization process. In the onInitializationSuccess() callback, you’ll receive the VdoPlayer instance, which can then be used to load and play media.

Java

PlayerHost.InitializationListener initializationListener = new PlayerHost.InitializationListener() {
    @Override
    public void onInitializationSuccess(PlayerHost playerHost, VdoPlayer vdoPlayer, boolean wasRestored) {
        // Build a video initialization params object to load the player with a video
        VdoInitParams vdoInitParams = new VdoInitParams.Builder()
            .setOtp("REPLACE WITH YOUR OTP")
            .setPlaybackInfo("REPLACE WITH YOUR PLAYBACK INFO")
            .build();

        // Load the player with the VdoInitParams object
        vdoPlayer.load(vdoInitParams);
    }

    @Override
    public void onInitializationFailure(PlayerHost playerHost, ErrorDescription errorDescription) {
        // Handle player initialization failure
    }

    @Override
    public void onDeInitializationSuccess() {
        // Called when the playerFragment is detached from the parent activity and the player is deinitialized.
    }
};

Kotlin

val initializationListener = object : PlayerHost.InitializationListener {
        override fun onInitializationSuccess(playerHost: PlayerHost, vdoPlayer: VdoPlayer, wasRestored: Boolean) {
            // Build a video initialization params object to load the player with a video
            val vdoInitParams = VdoInitParams.Builder()
                .setOtp("REPLACE WITH YOUR OTP")
                .setPlaybackInfo("REPLACE WITH YOUR PLAYBACK INFO")
                .build()

            // Load the player with the VdoInitParams object
            vdoPlayer.load(vdoInitParams)
        }

        override fun onInitializationFailure(playerHost: PlayerHost, errorDescription: ErrorDescription) {
            // Handle player initialization failure
        }

        override fun onDeInitializationSuccess() {
            // Called when the playerFragment is detached from the parent activity and the player is deinitialized.
        }

}

Step 4: Listen to Playback Events

1. Add Playback Event Listener:

Add callbacks for playback events using VdoPlayer.addPlaybackEventListener().

Java

vdoPlayer.addPlaybackEventListener(playbackListener);

Kotlin

vdoPlayer.addPlaybackEventListener(playbackListener)

2. Playback Listener:

Java

private final VdoPlayer.PlaybackEventListener playbackListener = new VdoPlayer.PlaybackEventListener() {
    @Override
    public void onLoading(VdoInitParams vdoInitParams) {
        // Player is loading
    }

    ...
    ...

    @Override
    public void onLoaded(VdoInitParams vdoInitParams) {
        // Playback can be controlled now
    }

    // Additional event handling...
    ...
    ...
};

Kotlin

private val playbackListener = object : VdoPlayer.PlaybackEventListener {
    override fun onLoading(vdoInitParams: VdoInitParams) {
        // Player is loading
    }

    ...
    ...

    override fun onLoaded(vdoInitParams: VdoInitParams) {
        // Playback can be controlled now
    }
    // Additional event handling...
    ...
    ...
}

Important Notes

1. TV Support: VdoPlayerUIFragment supports TV applications from SDK version 1.14.2 onward.
2. Back Press Handling: By default, the first onBackPressed() is handled by VdoPlayerUIFragment for managing orientation and state. Subsequent calls are passed to the activity. To handle all onBackPressed() calls in the activity, set app:handleBackPress="false". Example:

<fragment
        android:id="@+id/vdo_player_ui_fragment"
        android:name="com.vdocipher.aegis.ui.view.VdoPlayerUIFragment"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:keepScreenOn="true"
        app:handleBackPress="false"/> <!-- Handle back press in activity -->

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>

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 »

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:

Java

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

Kotlin

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

Resume video from last viewed position

Play the video from the last viewed position rather than the beginning. This can be configured using the enableAutoResume() method of the VdoInitParams.Builder when creating the vdoParams.

Java

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

Kotlin

val vdoParams = 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.

Java

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

    // add a listener for AutoResumeCallback event
    vdoPlayer.setAutoResumeCallback(new AutoResumeCallback() {
        @Override
        public void autoResumeVideo(long savedSeekPosition) {
            vdoPlayer.seekTo(savedSeekPosition);
        }
    });
    // ...
}

Kotlin

playerFragment.initialize(this@PlayerActivity)
// ...
override fun onInitializationSuccess(playerHost: PlayerHost, vdoPlayer: VdoPlayer, wasRestored: Boolean) {
      Log.i(TAG, "onInitializationSuccess")
      this.vdoPlayer = vdoPlayer

      // Add a listener for AutoResumeCallback event
      vdoPlayer.setAutoResumeCallback { savedSeekPosition ->
          vdoPlayer.seekTo(savedSeekPosition)
      }
      // ...
}