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

开发环境要求 #

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

  warning

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

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

获取 License #

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

集成步骤 #

步骤 1：添加 Maven 仓库 #

在项目根目录下 build.gradle 文件中的 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 选择对应的版本。

dependencies {
    // ...其他依赖...
    // 将 x.x.x.x 替换成最新版本号
    implementation "com.bytedanceapi:ttsdk-player_standard: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'
}

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'
}

dependencies {
    // ...其他依赖...
    // 将 x.x.x.x 替换成最新版本号
    implementation("com.bytedanceapi:ttsdk-player_standard: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")
}

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")
}

操作后的示意图如下：

步骤 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章节。