本文档为技术文档，建议阅读者具有基本的 iOS 开发能力。

系统要求版本为 iOS 9.0 及以上。

推荐开发者使用 Xcode11 以上作为自己的开发工具，本开发文档也是基于 Xcode 开发环境下进行编写的。

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',  # 上传 //推荐使用最新稳定版，具体版本号，例如x.x.x.x 修改为：1.20.2.2302 
]

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

添加 SDK 依赖 （推荐接入，便于统计、追踪和查询问题）

集成此依赖后，您可以在 veImageX 控制台查看对应数据能力，具体内容详情请参考上传数据监控。

pod 'RangersAppLog', '5.6.4', :subspecs =>['Core','Log','Host/CN']

如果您的 APP 之前已经对接过 RangersAppLog，则该版本号按照使用您已对接的版本号即可。

快速开始

本模块介绍如何使用上传SDK以最快捷的方式进行图片上传。您可直接通过以下 Demo，快速实现图片上传。

图片上传 Demo

在调用上传之前建议先配置上传的基本信息
/// 配置基本信息
NSDictionary *appInfo = @{
                          @"TTVideoEngineAID" : @(12345), /// appid
                          @"TTVideoEngineAppName" : @"test_appName",/// appName
                          @"TTVideoEngineChannel" : @"test_channel",
                          @"TTVideoEngineUserId"  : @"user_id",
                          };                           
[TTImageUploadClientTop configureAppInfo:appInfo];//图片的上传的配置

//note：需要关注下TTImageUploadClientTop实例的生命周期，如设置为局部变量时，会导致TTImageUploadClientTop实例析构销毁时，无法继续进行图片上传操作
TTImageUploadClientTop* clientTop;

- (void)initImageUploader{
  //初始化上传对象，需传入图片的上传地址
  clientTop = [[TTImageUploadClientTop alloc] initWithFilePaths:filePaths];

  NSMutableDictionary* jsonObject;
  NSError * jsonError = nil;
  jsonObject = [NSJSONSerialization JSONObjectWithData:authToken options:nil error:&jsonError];    //authToken签名是从app server获取，序列化为字典。
  NSDictionary* result = jsonObject[@"result"];
  NSDictionary* authParameter = @{TTFileUploadAccessKey:result[@"AccessKeyId"]:@"",
  TTFileUploadSecretKey:result[@"SecretAccessKey"]?:@"",
  TTFileUploadSessionToken:result[@"SessionToken"]?:@"",
  TTFileUploadExpiredTime:result[@"ExpiredTime"]:@"",
  TTFileUploadRegionName:@"cn-north-1"       // 根据实际地区填写
  };        
  [clientTop setAuthorizationParameter:authParameter]; 

  //设置上传的服务id名(释义见文末链接文档)和文件类型
  [clientTop setRequestParameter:@{TTFileUploadSpace:@"19tz3ytenx",TTFileUploadFileTypeStr:@"image",}];
  
  NSDictionary* config = @{
                           TTFileUploadFileRetryCount:@1,  //文件重试次数
                           TTFileUploadSocketNum:@1,     //socket数量
                           TTFileUploadTraceId:@"asdf"   //traceId  排查日志用
                           };
  [clientTop setUploadConfig:config];

  //设置域名
  [clientTop setImageHostName: @"imagex.volcengineapi.com"];
      
  // 设置delegate，用来接收上传的回调                                    
  clientTop.delegate = self;
  
 }

对于简单使用场景，使用上传 SDK 完成图片上传，需要以下4个步骤：

1. 初始化上传 SDK 环境

初始化操作很轻量，建议放到 appDelegate didFinishLaunchingWithOptions 中执行保障初始化顺序。

需要的参数列举如下：

参数	类型	释义	官网链接
TTVideoEngineAID	Int	App ID	SDK 用于打点监控上报的最小单元，请登录控制台我的应用获取。
TTVideoEngineAppName	String	App 英文名	例如：xigua
TTVideoEngineChannel	String	渠道	例如：huawei、oppo
TTVideoEngineUserId	String	user_id	用户ID

/// 配置基本信息
NSDictionary *appInfo = @{
                          @"TTVideoEngineAID" : @(12345), /// appid
                          @"TTVideoEngineAppName" : @"test_appName",/// appName
                          @"TTVideoEngineChannel" : @"test_channel",
                          @"TTVideoEngineUserId"  : @"user_id",
                          };                           
[TTImageUploadClientTop configureAppInfo:appInfo];//图片的上传的配置

2. 创建图片上传对象TTImageUploadClientTop

//初始化上传对象，需传入图片的上传地址
TTImageUploadClientTop* clientTop = [[TTImageUploadClientTop alloc] initWithFilePaths:filePaths];

3. 获取鉴权authToken

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

服务端鉴权参数获取方式如下所示：

开发语言	文档地址
Golang SDK	生成上传凭证
Python SDK	生成上传凭证
PHP SDK	生成上传凭证
Java SDK	生成上传凭证
Nodejs SDK	生成上传凭证

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

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

td {white-space:pre-wrap;border:1px solid #dee0e3;}

参数	类型	释义
TTFileUploadAccessKey	NSString	服务端鉴权参数：临时ak
TTFileUploadSecretKey	NSString	服务端鉴权参数：临时sk
TTFileUploadSessionToken	NSString	服务端鉴权参数：token
TTFileUploadExpiredTime	NSString	服务端鉴权参数：过期时间
TTFileUploadRegionName	NSString	地区，region取值范围为："cn-north-1"、"us-east-1"、"ap-singapore-1" ，分别对应不同的服务背后的存储集群。
TTFileUploadSpace	NSString	ServiceID，见下说明
TTFileUploadFileTypeStr	NSString	上传的文件类型，赋值为"image"，表示上传类型为图片
TTFileUploadFileRetryCount	int	文件重试次数
TTFileUploadSocketNum	int	socket数量
TTFileUploadTraceId	NSString	traceId 排查日志用
setImageHostName	NSString	域名

说明：

1. 请参考ServiceID 获取获取服务 ID，创建的每个服务都有一个唯一的服务ID，作为唯一标识符，其背后对应云存储的空间和集群。
2. 域名与region的映射关系

业务	域名	地域
国内业务	imagex.volcengineapi.com	cn-north-1

NSMutableDictionary* jsonObject;
  NSError * jsonError = nil;
  jsonObject = [NSJSONSerialization JSONObjectWithData:authToken options:nil error:&jsonError];    //authToken签名是从app server获取，序列化为字典。
  NSDictionary* result = jsonObject[@"result"];
  NSDictionary* authParameter = @{TTFileUploadAccessKey:result[@"AccessKeyId"]:@"",
  TTFileUploadSecretKey:result[@"SecretAccessKey"]?:@"",
  TTFileUploadSessionToken:result[@"SessionToken"]?:@"",
  TTFileUploadExpiredTime:result[@"ExpiredTime"]:@"",
  TTFileUploadRegionName:@"cn-north-1"       // 根据实际地区填写
  };        
  [clientTop setAuthorizationParameter:authParameter]; 

  //设置上传的服务id名(释义见文末链接文档)和文件类型
  //TTFileUploadSpace对应的serviceID需要调整为客户自身的ServiceID
  [clientTop setRequestParameter:@{TTFileUploadSpace:@"19tz3ytenx",TTFileUploadFileTypeStr:@"image",}];
  
  NSDictionary* config = @{
                           TTFileUploadFileRetryCount:@1,  //文件重试次数
                           TTFileUploadSocketNum:@1,     //socket数量
                           TTFileUploadTraceId:@"asdf"   //traceId  排查日志用
                           };
  [clientTop setUploadConfig:config];

  //设置域名
  [clientTop setImageHostName: @"imagex.volcengineapi.com"];

基础功能接入

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

• 开始上传

[clientTop start]//开始上传

• 暂停上传

[clientTop stop]//暂停上传

• 释放TTImageUploadClientTop实例

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

• 上传信息获取

// 上传回调
//图片上传结果回调 TTUploadImageInfoTop包含了图片序号 uri等信息。 上传组图时 其中某张图片的成功与否依赖此回调  error表示成功或失败*／
//当单张图片上传成功或失败时，可在该回调中获取相应图片信息或error信息
- (void)uploadDidFinish:(TTUploadImageInfoTop *)imageInfo error:(NSError *)error{

 }
 所有图片上传完成回调
- (void)uploadImagesDidFinish;
 
/*progress表示上传进度,fileIndex表示图片次序*/
- (void)uploadProgressDidUpdate:(NSInteger)progress fileIndex:(NSInteger) fileIndex{

}

- (int)uploadCheckIfNeedTry:(NSInteger)errCode tryCount:(NSInteger)tryCount{

}

TTUploadImageInfoTop结构

td {white-space:pre-wrap;border:1px solid #dee0e3;}

成员变量	含义	说明
storeUri	资源id，资源uri	NSString
fileIndex	文件索引	NSInteger
errCode	错误码	NSInteger
mediaInfoDict	媒体信息	NSDictionary

其中mediaInfoDict包含的图片元信息：

td {white-space:pre-wrap;border:1px solid #dee0e3;}

字段名	数据类型	描述
fileName	String	图片文件名
ImageUri	String	图片uri
ImageWidth	Integer	图片的宽
ImageHeight	Integer	图片的高
ImageMd5	String	图片的MD5值
ImageFormat	String	图片格式
ImageSize	Integer	图片大小
FrameCnt	Integer	图片帧数
Duration	Integer	图片时长，仅当原图为动图时有值

• Debug日志获取

当您遇到上传的问题时，可以打开Debug日志开关，获取详细日志信息，推进问题快速处理

时机：建议在调用上传之前配置Debug日志开关（initImageUploader之前）
[TTVideoUploadClientTop enableDebug:1];

• 质量埋点获取

当您遇到上传的问题时，可以通过质量埋点上报的方式，提供相应日志，推进问题快速处理

目前可在图片上传完成、图片上传失败、用户停止图片上传（调用函数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;  //注册回调

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

高级功能接入

指定文件存储路径

NSString* filePath1 = [[NSBundle mainBundle] pathForResource:@"test1" ofType:@"JPG"];
NSString* filePath2 = [[NSBundle mainBundle] pathForResource:@"test2" ofType:@"JPG"];
NSString* filePath3 = [[NSBundle mainBundle] pathForResource:@"test3" ofType:@"JPG"];
NSArray* filePaths = @[filePath1,filePath2,filePath3];
TTImageUploadClientTop* clientTop = [[TTImageUploadClientTop alloc] initWithFilePaths:filePaths];

NSString* imagePathKey1 = @"red";
NSString* imagePathKey2 = @"yellow";
NSString* imagePathKey3 = @"blue";
NSArray* imagePathKeys = @[imagePathKey1,imagePathKey2,imagePathKey3];

NSDictionary* config = @{
                         TTFileUploadFileRetryCount:@1,
                         TTFileUploadSliceTimeout:@40,
                         TTFileUploadSocketNum:@1,
                         TTFileUploadDeviceID:@3424321,
                         TTFileUploadTraceId:@"asdf"
                         TTFileUploadImagePathKey:imagePathKeys
                        };
                        
[clientTop setUploadConfig:config];

Note

获取图片属性信息

1. 图片上传后，默认可获取相应的 meta 信息
2. 当控制台设置为不限制上传类型时，则无法返回 meta 信息

reference

请参考serviceID 及 文件类型说明解释说明。