快速开始

本文档介绍如何用点播 SDK 以最简单快捷的方式让视频播放起来。

适用版本

此文档适用于 1.28.1.1 及之后的版本，之前版本请见 iOS 快速开始（历史版本）。

前提条件

您已完成点播 SDK 的集成准备。

示例 Demo

Github 地址：Demo-iOS。

使用流程

按照以下流程，对于简单使用场景，使用点播 SDK 在 App 中让一个视频播放。

1. 引入头文件
2. 初始化 SDK
3. 设置自定义 ID
4. 创建播放器
5. 设置显示视图
6. 设置播放源
7. 释放播放器
8. 接入 Debug 工具

1. 引入头文件

根据您的集成方式选择头文件引入方式。

• 动态库：如果您接入了 TTSDKFramework 动态库，则参考以下示例代码添加头文件依赖：

  #import <TTSDKFramework/TTSDKFramework.h>
  

• 静态库：如果您接入了 TTSDK 静态库，则参考以下示例代码添加头文件依赖：

  #import <TTSDK/TTSDKManager.h>
  #import <TTSDK/TTVideoEngineHeader.h>
  

2. 初始化 SDK

初始化操作是轻量的，建议在 appDelegate didFinishLaunchingWithOptions 中执行，保障初始化顺序。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 初始化 TTSDK
    [self initTTSDK];
    
    return YES;
}


- (void)initTTSDK {
#ifdef DEBUG
    // 建议开发的过程中打开 logcat 日志，获取更多播放信息
    [TTVideoEngine setLogFlag:TTVideoEngineLogFlagAll];
#endif

    // 请在火山引擎点播后台申请的 AppID
    NSString *appId = @"you app id"; 
    // 请将火山引擎点播后台申请的 License 拖动到主工程目录下
    // 请务必将“ttlicense.lic”名字换成实际 License 文件名字
    NSString *licenseName = @"ttlicense.lic";
    TTSDKConfiguration *configuration = [TTSDKConfiguration defaultConfigurationWithAppID:appId licenseName:licenseName];
    
    // 设置最大缓存 Size，默认 100M，可根据自身业务场景调整，超过缓存大小按照 LRU 规则清理
    TTSDKVodConfiguration *vodConfig = [[TTSDKVodConfiguration alloc] init];
    vodConfig.cacheMaxSize = 300 * 1024 *1024; // 建议设置大小 300M
    configuration.vodConfiguration = vodConfig;

    [TTSDKManager startWithConfiguration:configuration]; 
}

详细的参数说明如下表所示。

3. 设置自定义 ID

初始化点播 SDK 后，您可以设置自定义 ID，用于实现单点追查功能，即进行用户级和播放会话级的全链路问题定位和追踪。详细的代码示例如下所示。

- (void)initTTSDK {
    // 初始化 TTSDK
    NSString *appId = @"xxx"; // 您的用户 appid
    [TTSDKManager startWithConfiguration:configuration];
    
    // TTSDK 初始化后设置 uuid 
    [TTSDKManager setCurrentUserUniqueID:<#userid#>]；
}


// 您的用户登录成功/切换用户
- (void)onUserLogin {
    [TTSDKManager setCurrentUserUniqueID:<#userid#>];
}

// 您的用户注销登录
- (void)onUserLogout {
    [TTSDKManager clearUserUniqueID];
}

自定义 ID 配置完成后，您可登录视频点播控制台，选择左侧导航栏质量平台 > 单点追查，进入单点追查页面，查询单点追查数据。详细操作说明请见单点追查。

4. 创建播放器

参考以下示例代码创建 TTVideoEngine 播放器实例。

// 初始化播放器实例并以属性持有
self.engine = [[TTVideoEngine alloc] initWithOwnPlayer:YES];

5. 设置显示视图

参考以下示例代码设置显示画面的视图。

// TTVideoEngine 提供了显示画面的视图 view ，需要被添加的父视图和设置框架 frame 
[self.view addSubview:self.engine.playerView];

6. 设置播放源

TTVideoEngine 支持播放本地视频，也支持网络流媒体视频。针对不同的使用场景，我们提供了相应的播放源设置接口。

// vid 方式播放，需要同时设置 playAuthToken 和 resolution
NSString *vid = @"vid";
NSString *playAuthToken = @"play auth token";
TTVideoEngineResolutionType resolution = TTVideoEngineResolutionTypeFullHD; // 指定视频播放分辨率档位
TTVideoEngineVidSource *vidSource = [[TTVideoEngineVidSource alloc] initWithVid:vid playAuthToken:playAuthToken resolution:resolution];
[self.engine setVideoEngineVideoSource:vidSource];
[self.engine play];
    

// 设置播放源信息
NSString *videoUrl = @"you video url";
/// cacheKey为该url对应的唯一标识，建议使用url md5值
NSString *cacheKey = [videoUrl md5]; 
TTVideoEngineUrlSource *urlSource = [[TTVideoEngineUrlSource alloc] initWithUrl:videoUrl cacheKey:cacheKey];
[self.engine setVideoEngineVideoSource:urlSource];
[self.engine play];
    

NSString *localVideoPath = @"file://xxx.xx";
[self.engine setLocalURL:localVideoPath];
[self.engine play];
    

7. 释放播放器

视频播放结束或者离开视频播放页面时，需及时停止播放，并释放 TTVideoEngine 实例。

// 移除视图
[self.engine.playerView removeFromSuperview];
// 停止播放，销毁 engine 实例，engine 实例不能再次被使用。
[self.engine closeAysnc];
self.engine = nil;

8. 接入 Debug 工具

为了提升接入和调试效率，您可以根据需要进行接入可视化的 Debug 工具，直观方便地观察 SDK 相关信息。Debug 工具支持查看播放日志、视频信息和初始化信息。在接入过程中，Debug 工具会展示当前播放视频的详细信息，以及在异常或错误状态下的相应提示。详细操作请参见接入 Debug 工具。

至此，您已经掌握了如何播放一个视频并且停止播放视频的方法。虽然只有简单的开始播放与结束播放，还不能满足产品需求，但我们已经基本掌握了点播 SDK 的核心使用方式。下面我们演示如何实现更多的播放功能。详情请见功能实现。