Skip to main content

Getting Started

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

Latest version: 1.27.1

  • Java Sample Application: Explore the Java implementation.
  • Java API Reference: Comprehensive Java 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.

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

    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.

    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.

    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.
    }
    };

    Step 4: Listen to Playback Events

    1. Add Playback Event Listener:

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

    vdoPlayer.addPlaybackEventListener(playbackListener);

    2. Playback Listener:

    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...
    ...
    ...
    };
    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:

    VdoInitParams vdoParams = new 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.

    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 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);
    }
    });
    // ...
    }