Integrate the SDK

If you only need the player component to build features such as short-form video series, this topic explains how to integrate the ApsaraVideo Player SDK for Android. If you also need to create short videos, we recommend using the ApsaraVideo MediaBox SDK for Android. Using both SDKs separately may cause class duplication and lead to compilation failures.

Environment requirements

Use the latest version of Android Studio. Download URL: Android Studio.
Android version: 4.3 or later.
ABI compatibility: armv7 or arm64 architecture.
Limitation: ApsaraVideo Player SDK for Android does not support simulators. You must run your application on a physical device.

Prerequisites

Register for a player license and obtain the license file AliVideoCert-********.crt. For more information, see Obtain a license.
When you perform local integration of the SDK, you must first download the ApsaraVideo Player SDK for Android package. We recommend that you download the latest version.

Step 1: Integrate the SDK

Gradle integration

Note

Ensure your network can access the Alibaba Cloud Maven repository.

Add the Maven configuration.

For Gradle 7.x and later

Add the following configuration to the setting.gradle file of your project:

Groovy

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        jcenter() // jcenter() is being deprecated. We recommend that you replace it with mavenCentral().
        maven { url "https://maven.aliyun.com/repository/releases" }
    }
}

Kotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        jcenter() // jcenter() is being deprecated. We recommend that you replace it with mavenCentral().
        maven("https://maven.aliyun.com/repository/releases")
    }
}

For versions earlier than Gradle 7.x

Add the following configuration to the build.gradle file of your project:

Groovy

allprojects {
    repositories {
        google()
        mavenCentral()
        jcenter() // jcenter() is being deprecated. We recommend that you replace it with mavenCentral().
        maven { url "https://maven.aliyun.com/repository/releases" }
    }
}

Kotlin

allprojects {
    repositories {
        google()
        mavenCentral()
        jcenter() // jcenter() is being deprecated. We recommend that you replace it with mavenCentral().
        maven("https://maven.aliyun.com/repository/releases")
    }
}

Add the Player SDK dependency.
Add the Player SDK dependency to the dependencies block in your app's build.gradle file. The following code provides an example:
Note
Ensure you specify the correct SDK version number. An incorrect version causes an integration error. To view the version of the Player SDK, see ApsaraVideo Player SDK for Android release history.
Groovy
```
dependencies {
    // ApsaraVideo Player SDK for Android
    implementation 'com.aliyun.sdk.android:AliyunPlayer:7.15.0-full'
}
```
Kotlin
```
dependencies {
    // ApsaraVideo Player SDK for Android
    implementation("com.aliyun.sdk.android:AliyunPlayer:7.15.0-full")
}
```

Local integration

If you cannot download the SDK from the Maven repository due to network issues, use local integration.

Note

The following steps use Android Studio Flamingo | 2022.2.1 as an example. The process is similar for other versions.

Copy the required AAR package to the libs directory of your project. If the libs directory does not exist, create it.
In the build.gradle file of your project, add the flatDir setting to the repositories block inside the allprojects block. The following code provides an example:
```
flatDir {
   dirs 'libs'
}
```
In the build.gradle file of your app, add a dependency on the AAR file in the dependencies block. The following code provides an example:
```
dependencies {
      implementation fileTree(dir: 'libs', include: ['*.aar'])
}
```

Real-Time Streaming (RTS) integration (optional)

If you need to integrate the Real-Time Streaming (RTS) component, see Implement RTS stream pulling on Android.

Step 2: Configure the license

Important

If you use the service in regions outside the Chinese mainland, Hong Kong (China), and Macao (China), use one of the following methods to configure the international environment.

Method 1: Call the following API to update the default configuration to the international environment.

// To use the service in regions outside the Chinese mainland, Hong Kong (China), and Macao (China),
// call this API to set the international environment before any other player API calls.
// All subsequent operations will run in this environment.
// The environment cannot be changed at runtime.
AlivcBase.getEnvironmentManager().setGlobalEnvironment(AlivcEnv.GlobalEnv.ENV_SEA);

Method 2 (recommended): For player SDK V7.6.0 and later, you can configure the international environment by using the XML method.
Add a <meta-data> node to your AndroidManifest.xml file.
```
<meta-data
  android:name="com.aliyun.alivc_env"
  android:value="SEA"/>  
```
The following figure shows a configuration example:

To configure the license for Android, see Configure the license for Android.

Step 3: Configure permissions

In your app/src/main/AndroidManifest.xml file, declare the required permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Step 4: Configure obfuscation

Add the obfuscation configuration to your proguard-rules.pro file. The following code provides an example:

-keep class com.alivc.**{*;}
-keep class com.aliyun.**{*;}
-keep class com.cicada.**{*;}


-dontwarn com.alivc.**
-dontwarn com.aliyun.**
-dontwarn com.cicada.**

Step 5: Enable logging (optional)

Enabling logs helps you quickly locate and troubleshoot issues. Logs also provide data for performance optimization and user experience improvements. For information about how to obtain logs, see Obtain SDK logs.

// Enable the log switch.
Logger.getInstance(context).enableConsoleLog(true);
// Set the log level. The default level is AF_LOG_LEVEL_INFO. To troubleshoot issues, you can set it to AF_LOG_LEVEL_TRACE.
Logger.getInstance(context).setLogLevel(Logger.LogLevel.AF_LOG_LEVEL_INFO);

Project structure

File name	Description
AliyunPlayer-x.x.x-full.aar	A complete AAR package that includes the FFmpeg dynamic library.
AliyunPlayer-x.x.x-part.aar	An AAR package that does not include the FFmpeg dynamic library.
AlivcArtp-x.x.x.aar	Supports the ARTP protocol. This package is optional.
AlivcArtc-x.x.x.aar	Supports the ARTC protocol. This package is optional.

Note

If you do not integrate the short video SDK, add a dependency on the AliyunPlayer-x.xx.x-full.aar package.
If you integrate both the Player SDK and the short video SDK, use the AliyunPlayer-x.x.x-part package for the Player SDK dependency. You must also use a shared FFmpeg version by adding a dependency on the com.aliyun.video.android:AlivcFFmpeg:x.x.x package.
Using an incorrect SDK package during integration can cause FFmpeg conflicts.

FAQ

For common issues and solutions, see FAQ about ApsaraVideo Player.