适用版本 #

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

简介 #

ttuploader 是 iOS 端使用的通用上传 SDK。已支持素材上传功能
素材上传对应的类为TTMateUploadClientTop
上报信息的结构体为TTMateUploadInfoTop
质量统计类为TTVideoUploadEventManager

快速开始 #

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

#import <TTSDK/TTVideoUploadClientTop.h>
#import <TTSDK/TTFUConstDefination.h>
#import <TTSDK/TTVideoUploadEventManager.h>
#import <TTSDK/TTMateUploadClientTop.h>

//素材上传基于音视频上传，在素材上传时，音视频上传需要已配置完成以下config信息
/*
NSDictionary *appInfo = @{
                          TTVideoEngineAID : @(12345),  //appid
                          TTVideoEngineAppName : @"test_appName",// appName
                          TTVideoEngineChannel : @"test_channel",  //渠道
                          TTVideoEngineUserId  : @"user_id",  //user_id
                         };                           
[TTVideoUploadClientTop configureAppInfo:appInfo];//设置配置信息 
*/

//mateUploaderTop注意不要声明为局部变量进行使用
- (void)initMateUploader{
  TTMateUploadClientTop* clientTop = [[TTMateUploadClientTop 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:@"media", //表示上传类型为视频,对应FileType的设置
                                     TTFileUploadSpace:@"<YOUR_SPACE_NAME>",  // 参数"空间名称"，必需参数
                                     }; 
  [clientTop setRequestParameter:requestParameter];
  
  NSString* hostName = @"vod.volcengineapi.com";  
  [clientTop setMateHostName:hostName];   //设置网关域名
  [clientTop setSeverParameter:@"key1=value1&key2=value2"];//希望透传的参数
  [clientTop setRecordType:2]; //标识上传类型为素材上传，必传
  [clientTop setCategory:@"video"];//设置素材上传资源的类别，对应Category的设置
  [clientTop setTitle:@"testMateUpload"];
  [clientTop setTags:@"testMateTag,testMateTagOne"];
  [clientTop setDescription:@"testMateDescription"];
  [clientTop setFormat:@"mp4"];
  
  NSDictionary* config = @{
                           TTFileUploadFileRetryCount:@1,  //文件重试次数
                           TTFileUploadSocketNum:@1,     //socket数量
                           TTFileUploadTraceId:@"asdf"   //traceId  排查日志用
                           };
  [clientTop setUploadConfig:config];
 
   clientTop.delegate = self;    //设置delegate，用来接收上传的回调  
 }

note：素材上传时，会进行mFileType与mCategory的校验，使用时，需要注意相应的映射关系

对于简单使用场景，使用上传SDK完成素材上传，需要以下3个步骤：

• 创建素材上传对象TTMateUploadClientTop
• 获取鉴权authToken
• TTMateUploadClientTop实例设置上传数据源及其他配置

1. 创建视频上传对象TTMateUploadClientTop

#import <TTSDK/TTMateUploadClientTop.h>

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

note：需要关注下TTMateUploadClientTop实例的生命周期，如设置为局部变量时，会导致TTMateUploadClientTop实例析构销毁时，无法继续进行视频上传操作。

2. 获取鉴权authToken

此处获取的鉴权参数authToken，用于第四步进行上传的鉴权配置

ex:
JSONObject 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以服务端返回为准

3. TTMateUploadClientTop实例设置上传数据源及其他配置

说明： 【空间】相关说明请参考空间管理。
素材上传，设置配置时，需要关注以下几点

1. mRecordType 必须设置为2，标识此时为素材上传
2. mFileType 与 mCategory 存在以下映射关系，素材上传时，会进行mFileType与mCategory的校验，使用时，需要注意相应的映射关系

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:@"media", //表示上传类型为视频,对应FileType的设置
                                     TTFileUploadSpace:@"<YOUR_SPACE_NAME>",  // 参数"空间名称"，必需参数
                                     }; 
  [clientTop setRequestParameter:requestParameter];
  
  NSString* hostName = @"vod.volcengineapi.com";  
  [clientTop setVideoHostName:hostName];   //设置网关域名
  [clientTop setSeverParameter:@"key1=value1&key2=value2"];//希望透传的参数
  [clientTop setRecordType:2]; //标识上传类型为素材上传，必传
  [clientTop setCategory:@"video"];//设置素材上传资源的类别，对应Category的设置
  [clientTop setTitle:@"testMateUpload"];
  [clientTop setTags:@"testMateTag,testMateTagOne"];
  [clientTop setDescription:@"testMateDescription"];
  [clientTop setFormat:@"mp4"];
  
  NSDictionary* config = @{
                           TTFileUploadFileRetryCount:@1,  //文件重试次数
                           TTFileUploadSocketNum:@1,     //socket数量
                           TTFileUploadTraceId:@"asdf"   //traceId  排查日志用
                           };
  [clientTop setUploadConfig:config];

基础功能接入 #

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

• 开始上传

[clientTop start]//开始上传

• 暂停上传

[clientTop stop]//暂停上传

• 释放TTMateUploadClientTop实例

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

• 上传信息获取

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

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

TTMateUploadInfoTop结构

其中sourceInfo包含的素材元信息为：

• 质量埋点获取

当您遇到上传的问题时，可以通过质量埋点上报的方式，提供相应日志，推进问题快速处理
目前可在素材上传完成、素材上传失败、用户停止素材上传（调用函数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接口是否兼容，需要实际验证