Skip to main content

Getting Started

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

Latest version: 1.28.6

  • 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.28.6'
    }

    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 { *; }

    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>

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