You need to enable JavaScript to run this app.
导航

iOS 素材上传 SDK(历史版本)

最近更新时间2023.10.27 16:27:03

首次发布时间2021.08.11 11:03:16

适用版本

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

简介

ttuploader 是 iOS 端使用的通用上传 SDK。已支持素材上传功能

素材上传对应的类为TTMateUploadClientTop

上报信息的结构体为TTMateUploadInfoTop

质量统计类为TTVideoUploadEventManager

快速开始

本模块介绍如何使用上传SDK以最快捷的方式进行素材上传。请在参考视频上传完成集成准备后,再进行该步骤。iOS视频上传SDK

您可直接通过下述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:@"xxx",  // 参数"空间名称",必需参数 
                                     }; 
  [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的校验,使用时,需要注意相应的映射关系

FileType (string)Category (string)
mediavideo、audio
imageimage、dynamic_img
objectsubtitle、font

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

  • 创建素材上传对象TTMateUploadClientTop
  • 获取鉴权authToken
  • TTMateUploadClientTop实例设置上传数据源及其他配置
  1. 创建视频上传对象TTMateUploadClientTop
#import <TTSDK/TTMateUploadClientTop.h>

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

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

  1. 获取鉴权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以服务端返回为准
  1. TTMateUploadClientTop实例设置上传数据源及其他配置
参数
类型
释义
accessKey
NSString *
服务端鉴权参数:临时ak
secretKey
NSString
服务端鉴权参数:临时sk
sessionToken
NSString
服务端鉴权参数:token
expirationTime
NSDate
服务端鉴权参数:过期时间
regionNameNSString地区
mSpacechar空间
mObjectTypechar上传的素材类型,赋值为"media",表示素材类型为视频
mSeverParameterchar额外的要带上的上传参数
mFileRetryCountint文件重试次数
mSocketNumintsocket数量
mHostchar网关域名
mRecordTypeint标识上传类型为素材上传,必传
mCategorychar标识素材上传资源的类别
mTitlechar标识素材名称
mTagschar标识素材标签
mDescriptionchar *标识素材描述
mFormatchar标识素材格式

说明: 【空间】相关说明请参考空间管理

素材上传,设置配置时,需要关注以下几点

  1. mRecordType 必须设置为2,标识此时为素材上传
  2. mFileType 与 mCategory 存在以下映射关系,素材上传时,会进行mFileType与mCategory的校验,使用时,需要注意相应的映射关系
FileType (string)Category (string)
mediavideo、audio
imageimage、dynamic_img
objectsubtitle、font
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:@"xxx",  // 参数"空间名称",必需参数 
                                     }; 
  [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结构

成员变量
含义
说明
mid
素材的mid
NSString
callbackArgs
希望透传的参数
NSString 取值范围0~100
sourceInfo
返回的素材信息
NSDictionary

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

成员变量
含义
StoreUri
存储资源的uri
callbackArgs
希望透传的参数
Md5
Md5
Width
视频/图片的宽
Height
视频/图片的高
Size
视频/图片文件大小
Format
素材格式(视频格式,图片格式,object类型的素材不返回format)
Duration
时长
Bitrate
码率
FileType
文件类型
  • 质量埋点获取

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

目前可在素材上传完成、素材上传失败、用户停止素材上传(调用函数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接口是否兼容,需要实际验证