一、环境准备
·React Native 0.84.0 或更高版本。
·Node.js 22.11.0 或更高版本。
·Android 平台：
·Android 7.0（SDK API Level 24）及以上版本。
·iOS 平台：
·iOS 12.0 或更高版本。
·已安装 CocoaPods 环境。如果你尚未安装，请 单击查看 安装步骤。
二、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" }}
配置完成后执行以下命令安装依赖：
# yarnyarn install
iOS 端：
进入 iOS 目录安装 CocoaPods 依赖：
cd ios && pod install
Android 端：
Android 无需额外配置，Gradle 会自动处理依赖。
四、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 Podsrm -rf Podfile.lockpod 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 启动时配置 Licenseconst 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 exampleyarn installcd ios && pod install && cd ..# Androidyarn android# iOSyarn ios