Integration Preparation

Configure Your Development Environment

Before you use AliPlayerKit, make sure your development environment meets these requirements:

• JDK 11

  • You can configure the JDK in Preferences → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK.

  • Select version 11. If version 11 is not available, you must upgrade Android Studio.

• Android development environment

  • Install the latest version of Android Studio.

  • Configure the Android SDK. The minimum supported API level is 21 (Android 5.0).

  • We recommend using compileSdkVersion 31 or later.

  • Your Gradle version must be 7.0 or later.

Prepare Your License

Obtain the player license certificate and license key for the ApsaraVideo Player SDK. For more information, see Manage Licenses.

Step 1: Copy the Component Module

Copy the playerkit core module (library) directory into your project:

# Copy the playerkit core module to your project root directory
# Note: Copy only the playerkit directory—not the entire project or example modules such as playerkit-examples or playerkit-scenes
cp -r playerkit /path/to/your/project/

Step 2: Configure Your Gradle Project

repositories {
    // aliyun maven
    maven { url "https://maven.aliyun.com/repository/releases" }
}

repositories {
    // aliyun maven
    maven("https://maven.aliyun.com/repository/releases")
}

include ':playerkit'

include(":playerkit")

dependencies {
    // AliPlayerKit core module: Provides an out-of-the-box, configurable player UI component. Supports basic playback and common interactions.
    implementation project(':playerkit')
}

dependencies {
    // AliPlayerKit core module: Provides an out-of-the-box, configurable player UI component. Supports basic playback and common interactions.
    implementation(project(":playerkit"))
}

Step 3: Configure Your License

<meta-data
    android:name="com.aliyun.alivc_license.licensekey"
    android:value="Your License Key" />
<meta-data
    android:name="com.aliyun.alivc_license.licensefile"
    android:value="assets/cert/license.crt" />          

Step 4: Verify the Integration

./gradlew clean assemble --stacktrace --info

git add .
git commit -m "feat: integrate AliPlayerKit module (source commit: 2c30d92)"            

Step 1: Copy the Scenario Modules

Copy the required scenario modules into your project based on your business needs:

# scene-common includes sample video constants. Skip it if you implement your own video source.
cp -r playerkit-scenes/scene-common /path/to/your/project/

# Choose other scenario modules as needed.
cp -r playerkit-scenes/scene-longvideo /path/to/your/project/
cp -r playerkit-scenes/scene-live /path/to/your/project/
# ...         

Step 2 (Optional): Resolve Module Dependencies

The build.gradle files of the scenario modules depend on demo-settings and scene-common. Adjust these dependencies based on your needs:

dependencies {
    // ...
    // Delete this line: demo-settings is used only for demos.
    // implementation project(':demo-settings')
}          

dependencies {
    // ...
    // Comment out or delete this line if you implement your own video source.
    // implementation project(':scene-common')
}          

// ===== Original code (uses demo-settings / scene-common)=====
import com.aliyun.playerkit.example.settings.link.LinkConstants;
import com.aliyun.playerkit.example.settings.storage.SPManager;
import com.aliyun.playerkit.scenes.common.SceneConstants;

private String getVideoVid() {
    String savedVid = SPManager.getInstance().getString(LinkConstants.KEY_VIDEO_VID);
    return StringUtil.isNotEmpty(savedVid) ? savedVid : SceneConstants.LANDSCAPE_SAMPLE_VID;
}

// ===== Updated (use your video source)=====
private String getVideoVid() {
    return "Your video Vid";  // Or fetch it from your business API.
}

private String getVideoPlayAuth() {
    return "Your PlayAuth";  // Or fetch it from your business API.
}           

Step 3: Configure Your Gradle Project

include ':scene-common'
include ':scene-longvideo'
// Add other scenario modules as needed...

include(":scene-common")
include(":scene-longvideo")
// Add other scenario modules as needed...

dependencies {
    // AliPlayerKit scenario modules: Built on the AliPlayerKit core component. Provide out-of-the-box standard playback solutions.
    // Long-form video scenario module: Provides a complete solution for long-form video playback.
    implementation project(':scene-longvideo')
}

dependencies {
    // AliPlayerKit scenario modules: Built on the AliPlayerKit core component. Provide out-of-the-box standard playback solutions.
    // Long-form video scenario module: Provides a complete solution for long-form video playback.
    implementation(project(":scene-longvideo"))
}

Step 4: Verify the Integration

Synchronize Gradle and compile your project to confirm that the dependencies and module configurations are correct:

./gradlew clean assemble --stacktrace --info       

View Version Information

The current SDK versions that AliPlayerKit depends on are defined in the playerkit/build.gradle file.

You can view the latest versions and documentation for related SDKs at these links:

• Download the Player SDK.

• Android SDK Release History.

• Implement RTS Stream Pulling on Android.

Upgrade Steps

1. Check version compatibility

   Before you upgrade, review the SDK release history and update log. Check whether the target version introduces breaking changes or other compatibility adjustments.

2. Update the version number

   In the playerkit/build.gradle file, update the SDK version numbers:

   def player_sdk_version = "x.x.x"  // Replace with your target version
   api "com.aliyun.sdk.android:AliyunPlayer:$player_sdk_version-full"
   
   // RtsSDK version must match the player SDK version.
   def rts_sdk_version = "x.x.x"  // Replace with your target version
   api "com.aliyun.rts.android:RtsSDK:$rts_sdk_version"            

3. Verify the upgrade:

   • Clean and rebuild your project:

     ./gradlew clean assemble --stacktrace --info                

   • Test core playback functions: play, pause, seek, and playback speed.

   • Test specific playback scenarios, such as Real-Time Streaming (RTS) ultra-low-latency live playback.

License Issues

Issue: The player shows a license error.

Solution:

1. Confirm that you configured the license certificate and key correctly.

2. Check whether your license has expired.

3. Confirm that your app package name matches the package name that is bound to the license.

4. If you do not configure the correct license, playback fails after integration. You may see a black screen or other abnormal behavior.

Dependency Conflicts

Issue: Gradle sync fails with a dependency conflict error.

Solution:

1. Check whether your project already contains different versions of the same dependency.

2. Use exclude to remove conflicting dependencies.

3. Standardize dependency versions across your project.

4. If your project already uses the same third-party library, adjust the version number in the playerkit module to ensure compatibility and avoid conflicts.

Initialization Failed

Issue: Calling AliPlayerKit.init() throws an exception.

Solution:

1. Confirm that the Context is not null.

2. Call the method in Application.onCreate().

3. Check for duplicate calls. Duplicate calls are ignored and do not throw exceptions.

SDK Version Configuration Issues

Issue: Compilation fails with an SDK version mismatch error.

Solution:

Make sure the playerkit module’s configuration, such as compileSdkVersion, buildToolsVersion, minSdkVersion, and targetSdkVersion, matches your project’s settings.

Namespace Issues

Issue: After you copy modules, compilation fails with namespace-related errors.

Solution:

Each module’s build.gradle file declares a namespace by default to support Android Gradle Plugin (AGP) 7.x and later. Adjust this setting based on your AGP version:

Configuration location: Within the android {} block in each module's build.gradle file.

android {
    /// Integration FAQ
    /// Notes about namespace declaration:
    /// - AGP version ≥ 8.0 (for example, 8.3.2): namespace must be declared.
    /// - AGP version < 7.0 (for example, 4.0.1): remove namespace declaration. Use the package attribute in AndroidManifest.xml.
    /// - AGP version 7.x: namespace declaration is optional. We recommend declaring it to support future upgrades.
    namespace = "com.aliyun.playerkit"
    // ...
}  

Emulator Not Supported

Issue: An error occurs when running on an emulator.

Solution:

The ApsaraVideo Player SDK does not support emulators. You must test on a physical device after integration.

Repository Priority Conflict

Issue: Gradle reports a conflict while it resolves repository priorities.

Solution:

To resolve this, declare the repositories in your settings.gradle file.