帮你快速理解、总结文档立即下载
文档中心>播放器 SDK>不含 UI 的集成方案>React Native >SDK 集成指引

SDK 集成指引

最近更新时间：2026-07-31 15:28:30

我的收藏

本页目录：

环境准备

React Native 0.84.0 或更高版本。
Node.js 22.11.0 或更高版本。
Android 平台：
Android 7.0（SDK API Level 24）及以上版本。
iOS 平台：
iOS 12.0 或更高版本。
已安装 CocoaPods 环境。如果您尚未安装，请 单击查看 安装步骤。

SDK 下载

腾讯云视立方 React Native 播放器 SDK 目前只以源码方式提供集成，您可以 点击这里 下载资源包，解压后目录：
sdk：SDK 源码包，即 react-native-superplayer 源码。
example：Example 示例工程，包含完整使用示例。

快速集成

步骤1：集成 SDK 源码

将下载的 SDK 源码放置到您的 React Native 项目目录中（例如放在项目根目录下的 packages/react-native-superplayer），然后在项目的 package.json 中以本地依赖方式引入：
{
  "dependencies": {
    "react-native-superplayer": "file:./packages/react-native-superplayer"
  }
}
配置完成后执行以下命令安装依赖：
# yarn
yarn install
iOS 端：
进入 iOS 目录安装 CocoaPods 依赖：
cd ios && pod install
Android 端：
Android 无需额外配置，Gradle 会自动处理依赖。

步骤2：添加原生配置

Android 端配置

1. 在 Android 的 AndroidManifest.xml 中增加如下配置：
<!--网络权限-->
<uses-permission android:name="android.permission.INTERNET" />
网络安全配置允许 App 发送 HTTP 请求
出于安全考虑，从 Android P 开始，Google 要求 App 的请求都使用加密链接。播放器 SDK 会启动一个 localserver 代理 HTTP 请求，如果您的应用 targetSdkVersion 大于或等于 28，可以通过 网络安全配置 来开启允许向 127.0.0.1 发送 HTTP 请求。否则播放时将出现 "java.io.IOException: Cleartext HTTP traffic to 127.0.0.1 not permitted" 错误，导致无法播放视频。配置步骤如下：
1.1 在项目中新建 res/xml/network_security_config.xml 文件，设置网络安全性配置：
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">127.0.0.1</domain>
    </domain-config>
</network-security-config>
1.2 在 AndroidManifest.xml 文件下的 application 标签增加以下属性：
<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application android:networkSecurityConfig="@xml/network_security_config"
                    ... >
        ...
    </application>
</manifest>

iOS 端配置

注意：
iOS 端目前暂不支持模拟器运行调试，建议在真机下进行开发调试。
1. 如果您的视频源使用了 http 协议，需要在 iOS 的 Info.plist 中增加如下配置：
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
2. SDK 默认集成的播放器 SDK 为高级版（Premium），依赖通过 CocoaPods 自动引入，无需手动指定版本。
3. 部分情况下（如：发布了新版本），需要强制更新 iOS 播放器依赖，可以在 iOS 目录下使用如下命令进行更新：
rm -rf Pods
rm -rf Podfile.lock
pod update
4. 画中画配置：
如果需要项目支持画中画，则进行以下配置：
4.1 引入 PiP Bundle 资源
SDK 内 PiP 模块依赖 TXVodPlayer.bundle 里的内置资源，必须在编译前手动将其加入 Xcode 工程，不要修改 bundle 名称或其内部任何资源名，否则会导致切换画中画失败。
资源下载地址：TXVodPlayer.bundle.zip
操作示意：

4.2 开通后台模式
iOS 端无论应用内还是应用外 PiP，都需要 App 声明音频/PiP 后台能力：
Xcode 选择对应的 Target → Signing & Capabilities → Background Modes，勾选“Audio, AirPlay, and Picture in Picture”。


集成播放器 License

若您已获得相关 License 授权，需在 腾讯云视立方控制台 获取 License URL 和 License Key：

若您暂未获得 License 授权，需先参见 播放器 License 获取相关授权。
集成播放器前，需要 注册腾讯云账户，注册成功后申请播放器 License，然后通过下面方式集成，建议在应用启动时进行 (iOS 可以放在首次网络权限同意之后，业务中联网成功时调用)。
如果没有集成 License，播放过程中可能会出现异常。
import { SuperPlayerEnv, LogLevel } from 'react-native-superplayer';

// 在 App 启动时配置 License
const initLicense = async () => {
  const result = await SuperPlayerEnv.setLicense(
    'your_license_url', // License URL
    'your_license_key'  // License Key
  );

  if (result.result === 0) {
    console.log('License 设置成功');
  } else {
    console.error('License 设置失败:', result.reason);
  }
};

// 可选：设置日志级别
SuperPlayerEnv.setLogLevel(LogLevel.INFO);
日志级别说明：
级别
值
说明
VERBOSE
0
输出所有级别的 log。
DEBUG
1
输出 DEBUG 及以上级别。
INFO
2
输出 INFO 及以上级别。
WARN
3
输出 WARNING 及以上级别。
ERROR
4
输出 ERROR 及以上级别。
FATAL
5
只输出 FATAL 级别。
NULL
6
不输出任何 SDK log。

深度定制开发指引

腾讯云播放器 SDK React Native 插件对原生播放器能力进行了封装。如果您要进行深度定制开发，建议采用如下方法：
基于点播播放，核心类为 TXVodPlayer，进行定制开发。项目中提供了 example 工程，可参考其中的示例代码。
播放器视图组件 SuperPlayerViewComponent 提供了视频渲染容器，您可以在此基础上构建自定义 UI 交互。

常见问题

如何提取播放器 SDK 的运行 log？

播放器 SDK 默认把运行的 log 输出到本地文件。在帮忙定位问题时，需要这些运行 log 分析问题。
Android 平台 log 保存在目录：/sdcard/Android/data/packagename/files/log/tencent/liteav
iOS 平台 log 保存在目录：sandbox 的 Documents/log
更详细的 log 提取可参考 此教程。

如何减少控制台 log 输出？

可以通过 SuperPlayerEnv.setLogLevel() 设置 log 输出级别，支持以下级别：VERBOSE(0)、DEBUG(1)、INFO(2)、WARN(3)、ERROR(4)、FATAL(5)、NULL(6)。设置为 NULL 则不输出任何 SDK log。

更多功能

您可以通过运行项目中的 example 体验完整功能，example 运行指引：
cd example
yarn install
cd ios && pod install && cd ..
# Android
yarn android
# iOS
yarn ios
中国站