适用版本 #

此文档仅适用于 1.32.2.2 之前的版本。如果您使用的是 1.32.2.2 或之后的版本，请查看视频上传。

集成准备 #

环境要求 #

• Xcode 9.0 或以上版本。
• 支持 iOS 8.0 或以上版本的 iOS 设备。

TTSDK 运行 Demo #

1. Demo 工程中包含了大文件，并通过 git-lfs 管理。如果您当前没有安装 git-lfs，需先进行 git-lfs 安装。

$ brew install git-lfs
$ git lfs install

2. 将 Demo 工程拉取到本地。

$ git lfs clone https://github.com/volcengine/TTSDK-iOS.git

3. 切换至 Demo 目录，执行 pod install，并打开 Demo。

$ cd path/to/TTSDKDemo
$ pod install --repo-update
$ open TTSDKDemo.xcworkspace

添加 Podfile 依赖 #

在您工程的 Podfile 中添加依赖，并执行 pod install 即可。如下所示：

source 'https://github.com/volcengine/volcengine-specs.git'

    pod 'TTSDK', 'x.x.x.x', :subspecs => [
      'Uploader',   # 上传 //推荐使用最新稳定版，具体版本号请参考下方的ChangeLog
    ]

这里需要明确指定 subspecs => Uploader。

最新版本 SDK 获取 #

• 最新ttsdk_version 获取：详见 ChangeLog。

快速开始 #

本模块介绍如何使用上传 SDK 以最快捷的方式进行视频上传。请在完成集成准备后，再进行该步骤。
请将示例中的 <YOUR_SPACE_NAME> 替换为视频点播控制台中创建的上传空间名称。您可通过下述 Demo 实现视频上传。
详细划分为 4 个步骤，也在本章节对 4 个步骤进行了解释与说明。
视频上传 Demo

// 在调用上传之前建议先配置基本信息
    #import <TTSDK/TTVideoUploadClientTop.h>
    #import <TTSDK/TTFUConstDefination.h>
    #import <TTSDK/TTVideoUploadEventManager.h>

    // 配置基本信息  建议早配置
    NSDictionary *appInfo = @{
                              TTVideoEngineAID : @(12345),  // 示例值，替换为视频点播控制台“应用管理”中获取的实际 App ID
                              TTVideoEngineAppName : @"test_appName",// appName
                              TTVideoEngineChannel : @"test_channel",  //渠道
                              TTVideoEngineUserId  : @"user_id",  //user_id
                             };                           
    [TTVideoUploadClientTop configureAppInfo:appInfo];//设置配置信息 


    - (void)initVideoUploader{
      TTVideoUploadClientTop* clientTop = [[TTVideoUploadClientTop alloc] initWithFilePath:filePath]; //初始化上传对象，需传入视频的上传路径                                 
      
      NSMutableDictionary* jsonObject;
      NSError *jsonError = nil;
      jsonObject = [NSJSONSerialization JSONObjectWithData:authToken options:nil error:&jsonError];    //authToken为鉴权串，为服务端后台的签名sdk生成。向服务端请求获取。
      NSDictionary* result = jsonObject[@"result"];   //解析authToken，是否有这层Json以服务端返回为准
      NSDictionary* authParameter = @{
                                      TTFileUploadAccessKey:result[@"AccessKeyID"]?:@"",  //进一步解析出需要的签名信息
                                      TTFileUploadSecretKey:result[@"SecretAccessKey"]?:@"",
                                      TTFileUploadSessionToken:result[@"SessionToken"]?:@"",
                                      TTFileUploadExpiredTime:result[@"ExpiredTime"]?:@"",
                                      TTFileUploadRegionName:@"cn-north-1"       // 根据实际地区填写
                                      };        
      [clientTop setAuthorizationParameter:authParameter]; 
       
      NSDictionary* requestParameter = @{
                                         TTFileUploadFileTypeStr:@"video", //表示上传类型为视频
                                         TTFileUploadSpace:@"<YOUR_SPACE_NAME>",  // 参数"空间"，必需参数。
                                         }; 
      [clientTop setRequestParameter:requestParameter];
      
      NSDictionary* config = @{
                               TTFileUploadFileRetryCount:@1,  //文件重试次数
                               TTFileUploadSocketNum:@1,     //socket数量
                               TTFileUploadTraceId:@"asdf"   //traceId  排查日志用
                               };
      [clientTop setUploadConfig:config];
       
      NSString* hostName = @"vod.volcengineapi.com";  
      [clientTop setVideoHostName:hostName];   //设置网关域名
      
      [clientTop setSeverParameter:@"key1=value1&key2=value2"]; //希望透传的参数
       
      clientTop.delegate = self;    //设置delegate，用来接收上传的回调  
     }

对于简单使用场景，使用上传 SDK 完成文件（视频）上传，需要以下 4 个步骤：

• 初始化上传 SDK 环境；
• 创建视频上传对象 TTVideoUploadClientTop；
• 获取鉴权 authToken；
• TTVideoUploadClientTop 实例设置上传数据源及其他配置。

1. 初始化上传 SDK 环境

初始化操作很轻量，建议放到 appDelegate didFinishLaunchingWithOptions中执行保障初始化顺序。
需要的参数列举如下：

// 配置基本信息  建议早配置
NSDictionary *appInfo = @{
                          TTVideoEngineAID : @(12345),  // 示例值，替换为视频点播控制台“应用管理”中获取的实际 App ID
                          TTVideoEngineAppName : @"test_appName",// appName
                          TTVideoEngineChannel : @"test_channel",  //渠道
                          TTVideoEngineUserId  : @"user_id",  //user_id
                         };                           
[TTVideoUploadClientTop configureAppInfo:appInfo];//设置配置信息 

2. 创建视频上传对象 TTVideoUploadClientTop

#import <TTSDK/TTVideoUploadClientTop.h>

    TTVideoUploadClientTop* clientTop = [[TTVideoUploadClientTop alloc] initWithFilePath:filePath]; //初始化上传对象，需传入视频的上传路径

3. 获取鉴权 authToken

此处获取的鉴权参数 authToken，用于第四步进行上传的鉴权配置。
返回的 responseJson 示例如下：

{
    "result": {
        "AccessKeyID": "XXXXXX",
        "SecretAccessKey": "XXXXXX",
        "SessionToken": "XXXXXX",
        "ExpiredTime": "XXXXXX",
        "CurrentTime": "XXXXXX"
    }
}

NSMutableDictionary* jsonObject;
    NSError *jsonError = nil;
    jsonObject = [NSJSONSerialization JSONObjectWithData:authToken options:nil error:&jsonError];    //authToken为鉴权串，为服务端后台的签名sdk生成。向服务端请求获取。
    NSDictionary* result = jsonObject[@"result"];   //解析authToken，是否有这层Json以服务端返回为准

4. TTVideoUploadClientTop 实例设置上传数据源及其他配置。

NSMutableDictionary* jsonObject;
NSError *jsonError = nil;
jsonObject = [NSJSONSerialization JSONObjectWithData:authToken options:nil error:&jsonError];    //authToken为鉴权串，为服务端后台的签名sdk生成。向服务端请求获取。
NSDictionary* result = jsonObject[@"result"];   //解析authToken，是否有这层Json以服务端返回为准
  
NSDictionary* authParameter = @{
                                  TTFileUploadAccessKey:result[@"AccessKeyID"]?:@"",  //进一步解析出需要的签名信息
                                  TTFileUploadSecretKey:result[@"SecretAccessKey"]?:@"",
                                  TTFileUploadSessionToken:result[@"SessionToken"]?:@"",
                                  TTFileUploadExpiredTime:result[@"ExpiredTime"]?:@"",
                                  TTFileUploadRegionName:@"cn-north-1"       // 根据实际地区填写
                                  };        
[clientTop setAuthorizationParameter:authParameter]; 
   
NSDictionary* requestParameter = @{
                                   TTFileUploadFileTypeStr:@"video", //表示上传类型为视频
                                   TTFileUploadSpace:@"<YOUR_SPACE_NAME>",  // 参数"空间"，必需参数。
                                   }; 
[clientTop setRequestParameter:requestParameter];
  
NSDictionary* config = @{
                         TTFileUploadFileRetryCount:@1,  //文件重试次数
                         TTFileUploadSocketNum:@1,     //socket数量
                         TTFileUploadTraceId:@"asdf"   //traceId  排查日志用
                         };
[clientTop setUploadConfig:config];
   
NSString* hostName = @"vod.volcengineapi.com";  
[clientTop setVideoHostName:hostName];   //设置网关域名
  
[clientTop setSeverParameter:@"key1=value1&key2=value2"]; //希望透传的参数

基础功能接入 #

在快速开始章节中，我们完成 TTVideoUploadClientTop 实例的创建，本章节介绍如何使用 TTVideoUploadClientTop 实例进行上传。

• 开始上传

[clientTop start]//开始上传

• 暂停上传

[clientTop stop]//暂停上传

• 释放 TTVideoUploadClientTop 实例

[clientTop close]//停止上传并释放TTVideoUploadClientTop实例

• 上传信息获取

//上传完成会执行回调 1、上传成功，err为空且videoInfo不为空。videoInfo中有返回的视频相关信息，如下所示
    //                2、上传失败，err不为空且videoInfo为空。失败原因分析需要用到下面的质量监控日志分析
    - (void)uploadDidFinish:(nullable TTVideoUploadInfoTop *)videoInfo error:(nullable NSError *)error;

    //progress表示上传进度
    - (void)uploadProgressDidUpdate:(NSInteger)progress;

TTVideoUploadInfoTop 结构

其中 sourceInfo 包含的源视频元信息：

其中 encryptionInfo 包含的信息：

其中 Extra 包含的详细信息：

• 质量埋点获取

当您遇到上传的问题时，可以通过质量埋点上报的方式，提供相应日志，推进问题快速处理。
目前可在视频上传完成、视频上传失败、用户停止视频上传（调用函数 stop()）这三个时机进行质量埋点上报。

//1、可在上传完成后或者调用stop后获取 使用示例  
    NSArray* logArrary = [[TTVideoUploadEventManager sharedManager] popAllEvents]; //即可获取日志信息


    //2、也可以实现下面的回调，在event日志更新时即可操作，非必需实现 
    //实现方法
    - (void)eventManagerDidUpdate:(TTVideoUploadEventManager *)eventManager {
         NSArray *dics = [eventManager popAllEvents];
         for (NSDictionary *dict in dics) {
                NSMutableDictionary *tmpDict = [NSMutableDictionary dictionaryWithDictionary:dict];
                [tmpDict setValue:@(uniqueKey) forKey:@"log_id"];   //此上报需要三方sdk 如applog等
                [BDTrackerProtocol trackLogDataEvent:tmpDict];   //此上报需要三方sdk 如applog等
            }
        }
    [TTVideoUploadEventManager sharedManager].delegate =  self;  //注册回调

• AppLog 日志上报
  • 上传 SDK 对日志上报的三方库 applog 的接口调用为反射调用。工程接入了 applog，上传 SDK 即可自动上报日志。没有接入 applog，需要您拿到质量监控的日志自行处理。上传 SDK 基于 applog 3.3.9 版本的接口开发，目前已验证适配版本 3.3.9、5.3.0。
  • 如果之前已经接入了 applog，直接接入上传 SDK 即可，若是上述 applog 版本则可兼容，对于其他版本的 applog 接口是否兼容，需要实际验证。

高级功能接入 #

视频抽帧作为封面 #

• 进行视频上传时，可设置视频截图的时间点，将该时间点的视频截图作为上传视频的封面。

在快速开始章节的第四个步骤TTVideoUploadClientTop设置上传数据源及其他配置中增加相应的配置选项，即可接入该功能。

NSDictionary *params = @{@"TTFileUploadCoverTime":@1.0f   //设置截封面的时间，不设置默认为第一个非黑帧
                            }; 
    [clientTop setProcessActionType: TTVideoUploadActionTypeSnapshot parameter: params]; //截图 非必选

增值服务接入 #

素材上传 #

iOS素材上传SDK 。