集成 iOS 观播 SDK

观播 SDK 提供看直播、发评论、参与抽奖等功能。本文介绍如何将观播 SDK 集成到您的 iOS App 中。

前提条件

• 您已开通定制版套餐。详见计费说明。
• iOS 9.0 及以上版本的真机或模拟器。

  说明

  • 如使用静态库版本 TTSDK，则需使用 iOS 11.0 及以上版本的真机或模拟器。
  • 如使用 Apple silicon 的 Mac，则需使用 Rosetta 模拟器。
• 安装 Xcode，建议使用最新版本。
• 安装 CocoaPods，建议使用 1.11.0 或更高版本。可参考 Getting Started with CocoaPods。
• CPU 架构：armv7、arm64、x86_64（如使用静态库版本 TTSDK，则不支持 armv7）。
• 获取直播 License 文件和点播 License 文件、创建 SDK 应用时填写的 App 英文名称以及应用创建后生成的 App ID。详见获取 License。

集成步骤

步骤一：添加依赖

1. 在项目的 Podfile 文件中添加依赖。

   说明

   如果您的项目尚未使用过 CocoaPods，在项目的根目录下，执行 pod init && pod install，可以得到 Podfile 文件。

   source 'https://github.com/cocoapods/Specs.git'
   source 'https://github.com/volcengine/volcengine-specs.git'
   # 您 App Target 的名字
   target 'XXXX' do
     # 只集成观播 SDK
     # 如需优化包体积，请将 1.34.0 替换为 1.34.0-static-ttsdk 使用静态库版本的 TTSDK。在使用静态库版本 TTSDK 的基础上，可使用 ViewerWithoutRTC 作为 subspecs 集成不包含超低延时直播以及观众连麦功能的观播 SDK，从而进一步优化包体积
     pod'BDLive', '1.34.0'
   
     # 同时集成开播 SDK 和观播 SDK
     # 如需优化包体积，请将 1.34.0 替换为 1.34.0-static-ttsdk 使用静态库版本的 TTSDK。在使用静态库版本 TTSDK 的基础上，可将 LiveStreaming 替换为 LiveStreamingWithoutRTC 集成不包含超低延时直播以及录屏直播功能的开播 SDK，将 Viewer 替换为 ViewerWithoutRTC 集成不包含超低延时直播以及观众连麦功能的观播 SDK，从而进一步优化包体积
     pod'BDLive', '1.34.0', :subspecs => [
       'LiveStreaming',
       'Viewer',
     ]  
   end
   

2. 打开终端窗口，并 cd 到您的项目目录。执行 pod install 命令安装依赖。

步骤二：环境配置

在 Xcode 的 App Target 下，完成以下操作：

1. 打开 info.plist 文件，添加参数 SSAppID，并设置参数值为在 SDK 应用创建后生成的 App ID。

2. 在 info.plist 文件中，通过以下任一方式添加权限：

   • 单击 + 添加 Privacy - Photo Library Additions Usage Description、Privacy - Photo Library Usage Description、Privacy - Calendars Usage Description、Privacy - Microphone Usage Description 和 Privacy - Camera Usage Description 作为 Key，选择 String 作为 Type，并输入在系统弹出授权对话框时的提示信息作为 Value。
   • 以 Source Code 的方式打开 info.plist 文件，并添加以下 key 和 string。您可以自定义 string 的值作为在系统弹出授权对话框时的提示信息。

     <!-- 相册写入权限 -->
     <key>NSPhotoLibraryAddUsageDescription</key> 
     <string>App 需要获取您的相册写入权限，用于保存图片到相册</string>
     <!-- 相册访问权限 --> 
     <key>NSPhotoLibraryUsageDescription</key> 
     <string>App 需要获取您的相册访问权限，用于发送图片评论</string>
     <!-- 日历写入权限 -->
     <key>NSCalendarsUsageDescription</key>
     <string>用于直播预约提醒能力</string>
     <!-- 麦克风权限 -->
     <key>NSMicrophoneUsageDescription</key>
     <string>App 需要获取您的麦克风权限，用于连麦</string>
     <!-- 相机权限 -->
     <key>NSCameraUsageDescription</key> 
     <string>App 需要获取您的相机权限，用于连麦</string>
     

3. （可选）如果需要 App 在后台运行时继续播放音频或者需要使用画中画功能，需要完成以下步骤：

   1. 单击 Signing & Capabilities 页签下的 + Capability，并双击添加 Background Modes。
      
   2. 在 Background Modes 区域，选择 Audio, AirPlay, and Picture in Picture 复选框。
      

4. （可选）如果您的项目使用了 Bitcode，需要关闭 Bitcode。
   

   1. 单击 Build Settings 页签。
   2. 在 Build Options 区域，将 Enable Bitcode 置为 No。

5. 设置全屏播放直播、预告或回放时支持的屏幕方向。

   1. 单击 General 页签。
   2. 在 Deployment Info 区域，分别选择 iPhone Orientation 和 iPad Orientation 的 Portrait 和 Landscape Right 复选框。
      

   说明

   • 如需观众在全屏模式中可以根据设备朝向实现屏幕的左右自动旋转，必须满足以下条件：
     • 观众设备的竖排方向锁定已关闭。有关如何关闭竖排方向锁定，详见苹果官网文档。
     • 您在 Deployment Info 区域同时选择了 Landscape Left 和 Landscape Right 复选框。
   • 为避免观众点击全屏按钮后的全屏动画显示异常，请确保已勾选 Landscape Right 复选框。
   • 对于观播 SDK 1.28.2 及以上版本，如需禁用全屏模式，可以通过以下代码示例隐藏播放器内的全屏按钮。禁用全屏模式后，您可以在 Deployment Info 区域仅选择 Portrait 复选框。
     [BDLLiveEngine sharedInstance].liveRoomConfiguration.playerConfig.common.enterFullScreenEnable = NO;

步骤三：导入 License

将直播 License 文件和点播 License 文件添加到 Xcode 的 App Target 中。勾选 Copy items if needed，并单击 Finish。

步骤四：初始化 TTSDK

在 Xcode 的 App Target 下，打开 AppDelegate.m 文件初始化 TTSDK。

#import <TTSDKFramework/TTSDKManager.h> // 如需使用静态库版本的 TTSDK，请替换为 #import <TTSDK/TTSDKManager.h>
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [self initTTSDK];
    return YES;
}

- (void)initTTSDK {
    TTSDKConfiguration *configuration = [TTSDKConfiguration defaultConfigurationWithAppID:@"APP_ID"]; // 将 APP_ID 替换为在 SDK 应用创建后生成的 App ID
    configuration.appName = @"APP_NAME"; // 将 APP_NAME 替换为创建 SDK 应用时填写的 App 英文名称
    configuration.channel = @"CHANNEL_NAME"; // 将 CHANNEL_NAME 替换为 App 的渠道名称，例如 App Store
    configuration.bundleID = @"BUNDLE_ID"; // 将 BUNDLE_ID 替换为 App 的唯一标识（Bundle Identifier）
    
    // 分别设置点播 License 和直播 License
    // 点播 License
    configuration.licenseFilePath = [[NSBundle mainBundle] pathForResource:@"VOD_LICENSE_NAME" ofType:@"lic"]; // 将 VOD_LICENSE_NAME 替换为点播 License 文件的名称
    [TTSDKManager startWithConfiguration:configuration];
    
    // 直播 License
    configuration.licenseFilePath = [[NSBundle mainBundle] pathForResource:@"LIVE_LICENSE_NAME" ofType:@"lic"]; // 将 LIVE_LICENSE_NAME 替换为直播 License 文件的名称
    [TTSDKManager startWithConfiguration:configuration];
}

步骤五：创建进入直播间所需的 Activity

在 Xcode 的 App Target 中，打开定义如何进入与离开直播间的文件并添加以下代码。

#import <BDLive/BDLive.h>

BDLActivity *activity = [[BDLActivity alloc] init];
activity.activityId = @(ACTIVITY_ID); // 将 ACTIVITY_ID 替换为直播间的活动 ID。
activity.token = @"TOKEN"; // 将 TOKEN 替换为进入该直播间所需的授权 Token。
activity.authMode = BDLActivityAuthModePublic; // 直播间鉴权模式。此处以公开模式为例。观众无需登录即可观看直播、查看评论等。
activity.nickName = @"NICKNAME"; // 将 NICKNAME 替换为观众昵称。可选，用于在公开模式下预设观众昵称。
activity.isPortrait = YES; // 是否为竖屏直播间。此处以竖屏直播间为例。

步骤六：进入与离开直播间

在 Xcode 的 App Target 中，打开定义如何进入与离开直播间的文件并添加相关方法。
以下示例代码展示了进入与离开完整直播间的方法。

...
// 进入直播间。
[[BDLLiveEngine sharedInstance] joinLiveRoomWithActivity:activity];
// 离开直播间。
- (void)leaveLiveRoom {
    [[BDLLiveEngine sharedInstance] leaveLiveRoom];
}

优化包体积

自 SDK 1.31.0 版本开始，您可以按需完成以下操作优化 SDK 的包体积。

1. 使用静态库版本的 TTSDK。
   您必须同时完成以下操作：
   • 在添加依赖时，在版本号后添加 -static-ttsdk。详见步骤一：添加依赖。
   • 在初始化 TTSDK 时，将 #import <TTSDKFramework/TTSDKManager.h> 替换为 #import <TTSDK/TTSDKManager.h>。详见步骤四：初始化 TTSDK。
2. （可选）集成不包含超低延时直播以及观众连麦功能的观播 SDK。
   在添加依赖时，将 Viewer 替换为 ViewerWithoutRTC。详见步骤一：添加依赖。
   示例代码如下所示：

   ...   
     # 只集成观播 SDK
     pod'BDLive', '1.34.0-static-ttsdk', :subspecs => [
       'ViewerWithoutRTC', 
     ]
   
     # 同时集成开播 SDK 和观播 SDK
     pod'BDLive', '1.34.0-static-ttsdk', :subspecs => [
       'LiveStreamingWithoutRTC', # 集成不包含超低延时直播以及录屏直播功能的开播 SDK
       'ViewerWithoutRTC', 
     ]
   end
   

常见问题

为什么我可以正常观看预告和回放，却加载不出直播内容？

确保您创建 SDK 应用时填写的 Bundle ID（项目包名）以及应用创建后生成的 App ID 分别与初始化 TTSDK 时传入的 Bundle ID 和 App ID 相同，同时保证您初始化 TTSDK 时传入的 Bundle ID 和项目配置的 BundleID 一致，否则会出现鉴权失败的问题。

通过 Xcode 15 使用静态库版本的 TTSDK时，编译出现 duplicate symbol 错误怎么办？

Xcode 15 的已知问题导致。详见苹果开发者论坛。
您可以在 Xcode 的 App Target 下，单击 Build Settings > Other Linker Flags，并添加 -ld64。