集成准备

开发环境要求

License准备

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

步骤1：拷贝模块到项目中

将PlayerKit/目录拷贝到您的项目工程目录下（与您的Podfile同级或合适的子目录中）：

YourProject/
├── YourApp/
├── PlayerKit/                  # ← 拷贝此目录
│   ├── PlayerKit.podspec
│   ├── Source/
│   └── Resources/
└── Podfile

步骤2：配置Podfile

在Podfile中通过本地路径引用PlayerKit：

platform :ios, '9.0'

target 'YourApp' do
  use_frameworks!

  # 核心组件（必选，通过本地路径引用）
  pod 'PlayerKit', :path => './PlayerKit'

  # 底层播放器SDK（必选）
  pod 'AliPlayerSDK_iOS', '~> 7.15.0'

  # 直播RTS超低延时（可选，仅直播场景需要）
  # pod 'AliPlayerSDK_iOS_ARTC', '~> 7.15.0'
  # pod 'RtsSDK', '~> 7.12.0'
end

步骤3：安装依赖

pod install
open YourApp.xcworkspace

步骤4：配置License

播放器SDK需要有效的License授权才能正常工作。请参阅管理License完成License的获取与配置。

步骤5：全局初始化

在AppDelegate中完成框架初始化（整个应用生命周期只需调用一次）：

#import <PlayerKit/AliPlayerKit.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // （可选）全局 SDK 配置，如 setOption 等
    // [AliPlayerKit setOnGlobalInitBlock:^{
    //     // 全局配置在 setup 后仅执行一次
    // }];

    // 初始化 AliPlayerKit
    [AliPlayerKit setup];

    return YES;
}

import AliPlayerKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // （可选）全局 SDK 配置
    // AliPlayerKit.setOnGlobalInitBlock {
    //     // 全局配置在 setup 后仅执行一次
    // }

    // 初始化 AliPlayerKit
    AliPlayerKit.setup()

    return true
}

步骤6：验证集成

验证检查清单：

• pod install成功，无依赖冲突。

• License已正确配置。

• AppDelegate中调用[AliPlayerKit setup]。

• 编译通过（Cmd + B），无链接错误。

步骤1：拷贝模块到项目中

将PlayerKitScenes/目录拷贝到项目中（与PlayerKit/同级）：

YourProject/
├── YourApp/
├── PlayerKit/                  # 组件层（已拷贝）
├── PlayerKitScenes/            # ← 拷贝此目录
│   ├── PlayerKitScenes.podspec
│   ├── SceneCommon/
│   ├── SceneLongVideo/
│   ├── SceneShortVideo/
│   ├── SceneLive/
│   └── ScenePlaylist/
└── Podfile

步骤2：配置Podfile

在 Podfile 中通过本地路径引用 PlayerKitScenes：

target 'YourApp' do
  use_frameworks!

  # 核心组件（必选）
  pod 'PlayerKit', :path => './PlayerKit'
  pod 'AliPlayerSDK_iOS', '~> 7.15.0'

  # 播放场景方案（按需引入）
  pod 'PlayerKitScenes', :path => './PlayerKitScenes'

  # 或按需选择单个场景：
  # pod 'PlayerKitScenes/SceneLongVideo', :path => './PlayerKitScenes'
  # pod 'PlayerKitScenes/SceneShortVideo', :path => './PlayerKitScenes'
  # pod 'PlayerKitScenes/SceneLive', :path => './PlayerKitScenes'
  # pod 'PlayerKitScenes/ScenePlaylist', :path => './PlayerKitScenes'
end

场景模块说明：

步骤3：安装并验证

pod install

编译通过即表示场景层集成成功。

查看版本信息

• 运行时可通过 [AliPlayerKit getSdkVersion] 获取底层 SDK 版本号。

• 通过 [AliPlayerKit getPlayerKitVersion] 获取 AliPlayerKit 组件版本号。

• 查看下载播放器SDK和iOS SDK发布历史。

升级步骤

1. 确认版本兼容性。

   升级前建议查阅 SDK 发布历史与更新日志，确认目标版本是否存在 Breaking Changes。

2. 修改 Podfile 版本号。

   pod 'AliPlayerSDK_iOS', '~> x.x.x'  # 替换为目标版本
   
   # RTS（如使用直播场景）
   # pod 'AliPlayerSDK_iOS_ARTC', '~> x.x.x'
   # pod 'RtsSDK', '~> x.x.x'

3. 执行更新。

   pod update AliPlayerSDK_iOS

4. 验证升级。

   • 编译通过，无链接错误。

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

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

License相关问题

问题：播放器报License错误或播放黑屏。

请确认License已正确获取与配置，详见管理License。常见原因包括：证书文件未正确添加到工程、License Key不匹配、Bundle ID与License绑定的包名不一致、License已过期等。

依赖冲突问题

问题：pod install失败，提示依赖冲突。

排查步骤：检查项目中是否已存在SDWebImage的不同版本（PlayerKit依赖SDWebImage）；使用pod update尝试更新到兼容版本；执行pod repo update刷新本地仓库索引后重试。

初始化问题

问题：调用 [AliPlayerKit setup] 后播放异常。

排查步骤：

1. 确认在 AppDelegate 的 application:didFinishLaunchingWithOptions: 中调用。

2. 确认 License 已正确配置（详见 管理License）。

3. 通过 [AliPlayerKit isInitialized] 确认初始化成功。

4. setup 内置幂等保护（dispatch_once），重复调用不会抛异常。

5. 如需注入全局 SDK 配置，确认 setOnGlobalInitBlock: 在 setup 之前设置。

日志调试

如果遇到播放异常，可开启调试日志辅助排查：

// 开启调试模式
[AliPlayerKit setDebugModeEnabled:YES];
// 设置日志级别为 Verbose，输出最详细的日志
[AliPlayerKit setLogLevel:LogLevelVerbose];

日志系统的详细使用方式请参阅 日志系统。