You need to enable JavaScript to run this app.
导航
iOS 上传 SDK 接入文档(旧版)
最近更新时间:2024.07.25 21:52:04首次发布时间:2021.02.23 10:42:28
一、阅读对象

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

二、支持系统

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

三、开发环境

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

四、集成方式

TTSDK 运行 Demo

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

  1. 将 Demo 工程拉取到本地。
$ git lfs clone https://github.com/volcengine/TTSDK-iOS.git

  1. 切换至 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 
]

说明

veImageX 推荐您使用最新稳定版本,请点击TTSDK获取最新版本号地址。

这里需要明确指定 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 中执行保障初始化顺序。

需要的参数列举如下:

参数类型释义官网链接
TTVideoEngineAIDIntApp IDSDK 用于打点监控上报的最小单元,请登录控制台我的应用获取。
TTVideoEngineAppNameStringApp 英文名例如:xigua
TTVideoEngineChannelString渠道例如:huawei、oppo
TTVideoEngineUserIdStringuser_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];

说明

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

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;}
参数类型释义
TTFileUploadAccessKeyNSString服务端鉴权参数:临时ak
TTFileUploadSecretKeyNSString服务端鉴权参数:临时sk
TTFileUploadSessionTokenNSString服务端鉴权参数:token
TTFileUploadExpiredTimeNSString服务端鉴权参数:过期时间
TTFileUploadRegionNameNSString地区,region取值范围为:"cn-north-1"、"us-east-1"、"ap-singapore-1" ,分别对应不同的服务背后的存储集群。
TTFileUploadSpaceNSStringServiceID,见下说明
TTFileUploadFileTypeStrNSString上传的文件类型,赋值为"image",表示上传类型为图片
TTFileUploadFileRetryCountint文件重试次数
TTFileUploadSocketNumintsocket数量
TTFileUploadTraceIdNSStringtraceId 排查日志用
setImageHostNameNSString域名

说明:

  1. 请参考ServiceID 获取获取服务 ID,创建的每个服务都有一个唯一的服务ID,作为唯一标识符,其背后对应云存储的空间和集群。
  2. 域名与region的映射关系
业务域名地域
国内业务imagex.volcengineapi.comcn-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,资源uriNSString
fileIndex文件索引NSInteger
errCode错误码NSInteger
mediaInfoDict媒体信息NSDictionary

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

td {white-space:pre-wrap;border:1px solid #dee0e3;}
字段名数据类型描述
fileNameString图片文件名
ImageUriString图片uri
ImageWidthInteger图片的宽
ImageHeightInteger图片的高
ImageMd5String图片的MD5值
ImageFormatString图片格式
ImageSizeInteger图片大小
FrameCntInteger图片帧数
DurationInteger图片时长,仅当原图为动图时有值
  • 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,无需额外调用

高级功能接入

指定文件存储路径

说明

  1. 上传 n 张图片时,需要分别为 n 张图片配置 veImageX 服务的的存储路径(imagePathKeys的数组长度与上传的图片数量保持一致)。
  2. 文件存储路径:不支持以/开头或结尾,不支持/连续出现,存储路径最大长度为180。
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 及 文件类型说明解释说明。