集成准备

开发环境配置

在使用AliPlayerKit之前，请确保您的开发环境满足以下要求：

• JDK 11

  • 配置方式：Preferences → Build, Execution, Deployment → Build Tools → Gradle → Gradle JDK。

  • 选择11（如果没有11，请升级Android Studio版本）。

• Android开发环境

  • 安装最新版本的Android Studio。

  • 配置Android SDK，最低支持API级别为21（Android 5.0）。

  • compileSdkVersion建议使用31或以上。

  • Gradle版本不低于7.0。

License准备

已获取音视频终端SDK的播放器License授权证书和License Key，详情请参见管理License。

步骤1：拷贝组件模块

将playerkit核心模块（library）目录拷贝到您的项目中：

# 将playerkit核心模块拷贝到您的项目根目录下
# 注意：仅拷贝playerkit目录，而非整个项目或playerkit-examples、playerkit-scenes等示例模块
cp -r playerkit /path/to/your/project/

步骤2：Gradle项目配置

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核心模块：提供开箱即用、可配置的播放器UI组件，覆盖基础播放与常见交互能力
    implementation project(':playerkit')
}

dependencies {
    // AliPlayerKit核心模块：提供开箱即用、可配置的播放器UI组件，覆盖基础播放与常见交互能力
    implementation(project(":playerkit"))
}

步骤3：配置License

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

步骤4：验证集成

./gradlew clean assemble --stacktrace --info

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

步骤1：拷贝场景模块

根据业务需求，拷贝所需的场景模块到您的项目中：

# scene-common包含示例视频常量，如自行实现视频源可省略
cp -r playerkit-scenes/scene-common /path/to/your/project/

# 其他场景模块按需选择
cp -r playerkit-scenes/scene-longvideo /path/to/your/project/
cp -r playerkit-scenes/scene-live /path/to/your/project/
# ...         

步骤2（可选）：处理模块依赖

场景模块的build.gradle中依赖了demo-settings和scene-common，集成时需根据实际情况调整：

dependencies {
    // ...
    // 删除此行：demo-settings仅用于Demo演示
    // implementation project(':demo-settings')
}          

dependencies {
    // ...
    // 如自行实现视频源，可注释或删除此行
    // implementation project(':scene-common')
}          

// ===== 原代码（使用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;
}

// ===== 替换后（使用您的视频源）=====
private String getVideoVid() {
    return "您的视频Vid";  // 或从您的业务接口获取
}

private String getVideoPlayAuth() {
    return "您的PlayAuth";  // 或从您的业务接口获取
}           

步骤3：Gradle项目配置

include ':scene-common'
include ':scene-longvideo'
// 按需添加其他场景模块...

include(":scene-common")
include(":scene-longvideo")
// 按需添加其他场景模块...

dependencies {
    // AliPlayerKit播放场景模块：基于AliPlayerKit核心组件，提供开箱即用的标准播放场景方案
    // 中长视频场景模块：提供中长视频播放的完整解决方案
    implementation project(':scene-longvideo')
}

dependencies {
    // AliPlayerKit播放场景模块：基于AliPlayerKit核心组件，提供开箱即用的标准播放场景方案
    // 中长视频场景模块：提供中长视频播放的完整解决方案
    implementation(project(":scene-longvideo"))
}

步骤4：验证集成

同步Gradle并编译项目，确认依赖与模块配置正确：

./gradlew clean assemble --stacktrace --info       

查看版本信息

当前AliPlayerKit依赖的SDK版本信息定义在playerkit/build.gradle文件中。

您可以通过以下链接查看相关SDK的最新版本及文档：

• 下载播放器SDK。

• Android SDK发布历史。

• Android端实现RTS拉流。

升级步骤

1. 确认版本兼容性

   升级前建议查阅SDK发布历史与更新日志，确认目标版本是否存在Breaking Changes或其他兼容性调整。

2. 修改版本号

   在playerkit/build.gradle中修改SDK版本号：

   def player_sdk_version = "x.x.x"  // 替换为目标版本
   api "com.aliyun.sdk.android:AliyunPlayer:$player_sdk_version-full"
   
   // RtsSDK版本号需与播放器版本保持一致
   def rts_sdk_version = "x.x.x"  // 替换为目标版本
   api "com.aliyun.rts.android:RtsSDK:$rts_sdk_version"            

3. 验证升级：

   • 清理并重新编译项目：

     ./gradlew clean assemble --stacktrace --info                

   • 验证核心播放功能：播放、暂停、Seek、倍速等。

   • 验证特定播放场景：如RTS超低延时直播等。

License相关问题

问题：播放器出现License错误。

解决方案：

1. 确认已正确配置License证书和Key。

2. 检查License是否已过期。

3. 确认包名与License绑定的包名一致。

4. 如未配置正确的License，集成完毕后会出现播放黑屏等异常问题。

依赖冲突问题

问题：Gradle同步失败，提示依赖冲突。

解决方案：

1. 检查项目中是否已存在相同依赖的不同版本。

2. 使用exclude排除冲突依赖。

3. 统一项目中的依赖版本。

4. 如果您的项目中已有相同第三方库，请调整playerkit模块中的版本号，以确保兼容性并避免冲突。

初始化失败问题

问题：调用AliPlayerKit.init()抛出异常。

解决方案：

1. 确认Context不为null。

2. 确认在Application.onCreate()中调用。

3. 检查是否重复调用（重复调用会被忽略，不会抛异常）。

SDK版本配置问题

问题：编译时报SDK版本不匹配错误。

解决方案：

请确保playerkit模块的配置（如compileSdkVersion、buildToolsVersion、minSdkVersion、targetSdkVersion等）与您的项目中的设置保持一致。

Namespace相关问题

问题：直接拷贝模块后，编译时出现Namespace相关的错误。

解决方案：

各模块的build.gradle中已默认声明了namespace，适配AGP 7.x及以上版本。根据您项目的AGP版本进行以下调整：

配置位置：各模块build.gradle的android {}块中

android {
    /// 集成FAQ (Integration FAQ)
    /// 关于namespace声明的注意事项：
    /// - AGP版本 ≥ 8.0（如8.3.2）：必须声明namespace
    /// - AGP版本 < 7.0（如4.0.1）：需移除namespace声明，使用AndroidManifest.xml的package属性
    /// - AGP版本7.x：namespace声明可选，建议声明以兼容未来升级
    namespace = "com.aliyun.playerkit"
    // ...
}  

模拟器不支持问题

问题：在模拟器上运行出现异常。

解决方案：

Android播放器SDK不支持模拟器，集成完成后需在真机上测试。

Repository优先级冲突

问题：Gradle在处理repository的优先级时出现冲突。

解决方案：

请优先在settings.gradle中添加repository。