iOS上传SDK开发文档

介绍

视频云以SDK形式提供上传服务，可以帮助开发者快速上传文件并进行管理。SDK包含framework、开发文档。

功能说明

上传SDK提供两种上传形式：本地文件、内存数据，根据实际业务情况使用，上传过程中可取消，设置代理接收进度、上传状态等信息

系统范围

业务流程

详细信息请参考：云存储-产品手册-编程模型。

SDK集成

配置说明

1. 上传功能提供两个framework：

   QHVCUploadKit.framework该库为静态库（Build Phases->Link Binary With Libraries-> +）

   QHVCCommonKit.framework该库为动态库（Build Phases->Embed Frameworks-> +）

1. 实际开发中#import <QHVCUploadKit/QHVCUploader.h>头文件调用相关接口。

SDK初始化

需要调用[QHVCCommonCoreEntry coreOnAppStart:appId appVer:version deviceId:deviceId model:model optionalParams:nil];接口，说明如下：

appId(也叫businessId)是为业务分配的业务ID（appId获取地址：登录视频云官网-控制台-SDK-应用管理-新建应用）【见下图】；version为业务端APP的版本号；deviceId为设备唯一标识；uid为业务方用户标识，只要保证唯一即可;options可选，通常传nil，如有特殊需求详见参数说明。

点此查看应用ID

对appId和channelID这两个参数的引入，在设计之初目的是为了每个业务有独立的ID，通过appId来获取云端的一些参数控制，特别是视频缓冲策略、P2P行为、硬解码黑白名单以及解码库类型；channelID更多的为数据统计打点的唯一标注，可以通过云点播和云直播的服务标识来获取，以此获取播放数据反馈。UserID的设计是为了业务方和视频云唯一的沟通桥梁，只要保持唯一即可，一般为用户ID的加密字符串，通过UserID可以排查到一个用户的级别的失败日志；

APPID合法性验证

需要调用 `[QHVCCommonCoreEntry validityCheck:token randNum:randNum authTime:authTime callback:^(QHVCAuthStatus ret, NSString *detail) {
}];，接口说明如下：

合法性验证需要用到appId, Access Key(简称AK)和Secret Key(简称SK)。AK、SK获取地址： 登录视频云官网-用户中心-秘钥管理【见下图】。
只有appId、Access Key以及Secret Key相匹配，才能通过鉴权，否则将无法正常使用SDK。

点此查看秘钥

==注意：此接口必须在启动APP后120秒内调用，否则将无法正常使用SDK。==

appId使用和SDK初始化时同样的内容，callback可以用来监听合法性验证结果。 计算authorization时需要使用AK、SK以及当前系统的时间戳和随机数。
为了保证AK、SK的安全，请业务接入时，务必把AK和SK存储在服务端，并且把authorization的计算也放在服务端来做。

计算authorization的示例代码如下：

    NSString *randNum = [NSString stringWithFormat:@"%u", arc4random() + 1];
    NSString *authTime = [NSString stringWithFormat:@"%lld", [QHVCToolUtils getCurrentDateByMilliscond]/1000];
    QHVCGlobalConfig* globalConfig = [QHVCGlobalConfig sharedInstance];//参数配置
    NSString *AK = globalConfig.appKey;
    NSString *SK = globalConfig.appSecret;
    NSString *paramsStr = [NSString stringWithFormat:@"appid=%@", [QHVCGlobalConfig sharedInstance].appId];
    NSString *paramsSign = [QHVCToolUtils getMD5String:[NSString stringWithFormat:@"%@%@", [QHVCToolUtils getMD5String:paramsStr], randNum]];
    NSString *authString = [NSString stringWithFormat:@"%@\n%@\n%@\n%@", AK, authTime, randNum, paramsSign];
    NSString *sign = [QHVCToolUtils hmacSha1:SK data:authString];
    NSString *token = [NSString stringWithFormat:@"%@:%@", AK, sign];

鉴权状态码：

typedef NS_ENUM(NSInteger, QHVCAuthStatus)
{
    QHVCAuthStatus_OK = 1,                //鉴权成功
    QHVCAuthStatus_FAILED = -11001,       //鉴权失败
    QHVCAuthStatus_NOT_INVOKED = -11002   //未调用鉴权接口
};

接口说明

上传相关

创建上传对象

_uploader = [[QHVCUploader alloc]init];

[_uploader setUploaderDelegate:self];

/**
 *  @功能 获取上传类型，目前有表单和分片两种形式，具体使用哪种形式由服务器返回的配置信息决定
 *  如果是分片上传，需要调用parallelQueueNum获得队列数，用于计算token
 *  如果是表单上传，无需调用parallelQueueNum，计算token不需要此参数
 *  @参数 size 待上传任务数据大小，单位：字节
 *  @返回值 详见QHVCUploadTaskType
 */
- (QHVCUploadTaskType)uploadTaskType:(uint64_t)size;
/**
 *  @功能 获取分片上传队列数，用于业务计算token
 *  @返回值 分片上传队列数
 */
- (NSInteger)parallelQueueNum;
/**
 *  @功能 分片上传续传
 *  @参数 key 通过key管理上传信息
 */
- (BOOL)setUploadRecorderKey:(NSString *)key;
/**
 *  @功能 两种上传方式，数据在本地uploadFile:，数据在内存中uploadData:
 *  @参数 filePath 待上传文件本地路径
 *  @参数 data    待上传内存数据
 *  @参数 fileName    本地文件/内存数据上传到服务器后的文件名
 *  @参数 token 表单/分片任务计算规则略有差别
 */
- (void)uploadFile:(NSString *)filePath fileName:(NSString *)fileName token:(NSString *)token;
- (void)uploadData:(NSData *)data fileName:(NSString *)fileName token:(NSString *)token;
/**
 *  @功能 取消当前上传任务
 */
- (void)cancel;
/**
 *  @功能 第三方设置上传域名，上传前设置(必填)
 *  @参数 domain 有效的域名
 * （bucket北京地区-上传地址：up-beijing.oss.yunpan.360.cn
 *  bucket上海地区-上传地址：up-shanghai.oss.yunpan.360.cn）
 */
+ (void)setUploadDomain:(NSString *)domain;
/**
 *  @功能 设置上传速度 默认不限速（根据实际业务需求选择使用）
 *  @参数 speed kbps
 */
+ (void)setUploadSpeed:(NSInteger)speed;

日志相关

开发阶段辅助开发调试，根据实际情况使用

/**
 * 打开上传日志
 * @参数 level 日志等级
 */
+ (void)openLogWithLevel:(QHVCUploadLogLevel)level;
/**
 * 设置日志输出callback
 * @参数 callback 回调block
 */
+ (void)setLogOutputCallBack:(void(^)(int loggerID, QHVCUploadLogLevel level, const char *data))callback

统计相关

//统计相关，请正确设置，利于排查线上问题，在上传前设置
/**
 *  @功能 设置统计信息
 *  @参数 info 
 @{@"channelId":@"",
 @"userId":@""
 };
 */
+ (void)setStatisticsInfo:(NSDictionary *)info;

回调

QHVCUploaderDelegate：
/**
 *  @功能 回调上传状态 成功、失败
 *  @参数 uploader
 *  @参数 status 上传状态
 */
- (void)didUpload:(QHVCUploader *)uploader status:(QHVCUploadStatus)status error:(nullable NSError *)error;
@optional
/**
 *  @功能 上传进度
 *  @参数 uploader
 *  @参数 progress 上传进度（0.0-1.0）
 */
- (void)didUpload:(QHVCUploader *)uploader progress:(float)progress;
QHVCRecorderDelegate：
/**
 *  @功能 保存持久化上传信息
 *  @参数 key 持久化记录key
 *  @参数 data 上传信息
 */
- (void)setRecorder:(NSString *)key data:(NSData *)data;
/**
 *  @功能 获取上传信息
 *  @参数 key 持久化记录key
 *  @返回值 存储的上传信息
 */
- (NSData *)fetchRecorder:(NSString *)key;
/**
 *  @功能 删除上传信息（上传成功、信息过期）
 *  @参数 key 持久化记录key
 */
- (void)deleteRecorder:(NSString *)key;

错误码说明