本文为您介绍如何将 Android 播放器 SDK 集成至您的项目中，包括开发环境要求、前提条件、操作步骤等内容。

开发环境要求 #

• 推荐使用 Android Studio 最新版本。
• 仅支持基于 armv7 或 arm64 架构的真实设备。

  注意

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

• Android 版本需为 5.0（API 级别 21）及以上。
• 编译时需使用 JDK 11 及其以下版本。

获取 License #

视频点播通过 License 管理播放器 SDK 及其增值服务的使用权限和时间。在项目测试阶段，您可以在视频点播控制台申请免费的测试 License。您需完成创建应用、申请免费测试 License、绑定 License 与应用，详细操作步骤，请见应用管理和播放器 License。

集成步骤 #

步骤 1：添加 Maven 仓库 #

在项目根目录的 settings.gradle（Groovy）或 settings.gradle.kts（Kotlin）中，通过 dependencyResolutionManagement.repositories 配置 mavenCentral() 和火山引擎 Maven 仓库。

dependencyResolutionManagement {
    repositories {
        google()
        jcenter()    
        mavenCentral()
        maven {
            url "https://artifact.bytedance.com/repository/Volcengine/"
        }
    }
}

dependencyResolutionManagement {
    repositories {
        google()
        jcenter()      
        mavenCentral()
        maven(url = "https://artifact.bytedance.com/repository/Volcengine/")
    }
}

操作后的示意图如下：

步骤 2：添加 SDK 依赖 #

在 module 目录下 build.gradle 文件中的 dependencies 中添加播放器 SDK 依赖。播放器 SDK 分为基础版、高级版和企业版，各版本之间存在功能差异。请根据购买的 License 选择对应的版本。

根据接入地域和是否需要适配 Android 16KB 页面大小，播放器 SDK 的依赖处理方式会有所不同。各场景区别见下表，详细接入方式请参见后文对应章节。

场景一：接入国内版本

国内地域无需调整 AppLog 依赖，直接接入 SDK 即可：

dependencies {
    // 将 x.x.x.x 替换成最新版本号
    implementation "com.bytedanceapi:ttsdk-player_premium:x.x.x.x"
    // 1.40.2.8 之前的版本还需添加以下 AppLog 依赖，用于上报日志
    // implementation "com.bytedance.applog:RangersAppLog-Lite-cn:6.15.4"
    // 用于获取视频源
    implementation 'com.squareup.okhttp3:okhttp:4.2.1'
}

场景二：接入海外版本（如亚太东南 / 柔佛地域）

播放器 SDK 默认依赖的是国内版 AppLog（com.bytedance.applog:RangersAppLog-Lite-cn），用于播放日志上报。国内版 AppLog 的上报通道在海外不可用，因此当接入火山海外版本（如亚太东南 / 柔佛地域）时，必须做两件事：

1. exclude 掉 SDK 默认携带的国内版 AppLog（RangersAppLog-Lite-cn）；
2. 手动接入海外版 AppLog（RangersAppLog-Lite-global）。

需在引入播放器 SDK 时 exclude 掉国内版 AppLog，并手动接入海外版 AppLog：

def ttsdk_version = "x.x.x.x"   // 替换成实际 SDK 版本号，需 >= 1.41.1，如 "1.41.1.8"
def applog_version = "6.15.4"   // 海外版 AppLog 版本号

implementation ("com.bytedanceapi:ttsdk-player_premium:$ttsdk_version") {
    // 移除 SDK 默认依赖的国内版 AppLog
    exclude group: 'com.bytedance.applog', module: 'RangersAppLog-Lite-cn'
}
// 手动接入海外版 AppLog
implementation "com.bytedance.applog:RangersAppLog-Lite-global:$applog_version"

// 用于获取视频源
implementation 'com.squareup.okhttp3:okhttp:4.2.1'

场景三：接入海外版本 + 需要适配 Android 16KB 页面大小

若 App 需适配 Android 16KB page size 要求，需在场景二的基础上，同时升级以下两项依赖到支持 16KB 的版本：

def ttsdk_version = "x.x.x.x"   // 请选择 >= 1.47.2.8 的版本
def applog_version = "6.17.4"   // 支持 16KB 对齐的海外版 AppLog

implementation ("com.bytedanceapi:ttsdk-player_premium:$ttsdk_version") {
    // 移除 SDK 默认依赖的国内版 AppLog
    exclude group: 'com.bytedance.applog', module: 'RangersAppLog-Lite-cn'
}
// 手动接入支持 16KB 的海外版 AppLog
implementation "com.bytedance.applog:RangersAppLog-Lite-global:$applog_version"

// 用于获取视频源
implementation 'com.squareup.okhttp3:okhttp:4.2.1'

场景四：关闭播放质量数据分析（AppLog）

如果您的业务无需使用播放质量数据分析（AppLog），可按接入地域和 SDK 版本调整 AppLog 依赖。

国内版本

• 点播 SDK 1.40.2.8 之前：无需添加 AppLog 依赖，即不添加 implementation "com.bytedance.applog:RangersAppLog-xxxx"。
• 点播 SDK 1.40.2.8 及之后：播放器 SDK 默认依赖国内版 AppLog，需在引入播放器 SDK 时添加 exclude 逻辑。

def ttsdk_version = "x.x.x.x"   // 替换成实际 SDK 版本号，需 >= 1.40.2.8

implementation ("com.bytedanceapi:ttsdk-player_premium:$ttsdk_version") {
    // 移除 SDK 默认依赖的国内版 AppLog
    exclude group: 'com.bytedance.applog', module: 'RangersAppLog-Lite-cn'
}

// 用于获取视频源
implementation 'com.squareup.okhttp3:okhttp:4.2.1'

海外版本

海外版本关闭播放质量数据分析时，需 exclude SDK 默认依赖的国内版 AppLog，且不手动添加海外版 AppLog（RangersAppLog-Lite-global）。

def ttsdk_version = "x.x.x.x"   // 替换成实际 SDK 版本号

implementation ("com.bytedanceapi:ttsdk-player_premium:$ttsdk_version") {
    // 移除 SDK 默认依赖的国内版 AppLog
    exclude group: 'com.bytedance.applog', module: 'RangersAppLog-Lite-cn'
}

// 用于获取视频源
implementation 'com.squareup.okhttp3:okhttp:4.2.1'

步骤 3：添加 Java 8 支持 #

在 module 目录下的 build.gradle 文件中添加 Java 8 支持，示例代码如下：

android {
  // ...
  compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

android {
    // ...
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }
}

操作后的示意图如下：

步骤 4：声明权限 #

在 AndroidManifest.xml 文件中声明 SDK 需要的权限。

<!-- 网络访问权限，播放网络视频所必需 -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- 允许应用在后台播放时保持 CPU 唤醒，防止播放中断 -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- 获取当前网络状态，用于网络变化时的逻辑处理（如 ABR 切换、断网重试等） -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 允许应用获取 Wi-Fi 状态，有助于网络诊断 -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- == 外部存储相关权限（仅在需要播放本地文件或使用外部缓存时需要） == -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<!-- Android 11 及以上还需要声明以下权限 -->
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE"/>

步骤 5：配置混淆规则 #

在 proguard-rules.pro 文件中配置 SDK 的混淆规则。

# 点播模块
-keep class com.ss.ttm.** {*;}
-keep class com.ss.ttvideoengine.** {*;} 
-keep class com.ss.mediakit.** {*;} 
-keep class com.ss.texturerender.** {*;}
-keep class com.ss.vcbkit.** {*;}
-keep class com.bytedance.**{*;}
-keep class com.pandora.ttlicense2.**{*;}
-keep class com.pandora.common.applog.**{*;}
-keep class com.pandora.vod.VodSDK {*;} 
-keep class com.bytertc.volcbaselog.VolcBaseLogConfig{*;}
-keep class com.bytertc.volcbaselog.VolcBaseLogNative{*;}

后续操作 #

至此，您已完成播放器 SDK 的集成。接下来可使用播放器 SDK 播放视频。详情请见快速开始。

常见问题 #

我的视频存储在视频点播的海外柔佛地域，需要特殊配置吗？ #

当您的业务接入海外柔佛地域时，需要对播放器 SDK 进行专门的地域配置，主要涉及以下两个环节：

• 配置海外日志上报通道：修改 module 目录下 build.gradle 文件，确保海外用户的播放日志从海外渠道进行上报。
• 指定海外业务服务地域：在初始化 SDK 时，通过 Region 参数，明确指定视频资源所在的海外服务地域。

详细的操作步骤，请参见服务地域文档中的播放器 SDK章节。