本文为您介绍如何用 iOS 上传 SDK 以简单便捷的方式上传图片。

适用版本

此文档适用于 1.32.2 及以上版本，其他版本接入文档请参考 iOS 上传 SDK 接入文档（旧版）。

前提条件

• 已完成上传 SDK 的集成准备。
• AppID 请从火山引擎控制台应用管理详情页查看并获取。
• ServiceID 请参考服务管理获取。
• 从您的 AppServer 获取鉴权参数设置给 SDK。鉴权参数说明及获取方式详见客户端上传说明。

1.初始化 SDK

#import <TTSDK/TTSDKManager.h>
#import <TTSDK/BDFileUploaderHeader.h>
 
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 初始化 TTSDK
    [self initTTSDK];
    
    return YES;
}
 
- (void)initTTSDK {
    // 开启上传模块调试日志，建议 debug 阶段保持开启，便于排查问题。
#if DEBUG
    [[BDUploadUtilTool sharedInstance] enableNativeLogFunc:YES];
#endif

    // 请在火山引擎后台申请 AppID
    // NSString *appId = @"you app id";
    TTSDKConfiguration *configuration = [TTSDKConfiguration defaultConfigurationWithAppID:<#appid#> licenseName:<#licenseName#>];
    configuration.shouldInitAppLog = NO; // 若无需接入日志上报能力，请指定为 NO。否则指定为 YES。
    [TTSDKManager startWithConfiguration:configuration];
}

2.设置自定义用户 ID

1.35.2.3 及之后版本已支持。

如果您自己已有一套独立的用户 ID 体系，希望通过用户 ID 来追查单个用户的单次上传行为，则可自定义用户 ID。如需排查问题，请提交工单联系技术支持来帮助您完成上传流程的问题定位和追踪。具体操作代码示例如下所示：

- (void)initTTSDK {
    // 初始化 SDK
    NSString *appId = @"xxx"; // 您的 AppID
    [TTSDKManager startWithConfiguration:configuration];
    
    // 完成 SDK 初始化后，自定义用户 ID  
    [TTSDKManager setCurrentUserUniqueID:<#userid#>]；
}

// 您的用户登录成功/切换用户，更新自定义 ID
- (void)onUserLogin {
    [TTSDKManager setCurrentUserUniqueID:<#userid#>];
}

// 您的用户注销登录时，移除自定义 ID
- (void)onUserLogout {
    [TTSDKManager clearUserUniqueID];
}

3.初始化图片上传实例

需要关注BDImageXUploaderClient 实例的生命周期，如设置为局部变量，会导致离开作用域后，无法继续进行上传操作。

#import <TTSDK/BDFileUploaderHeader.h>

- (void)initImageXUploaderClient {
    // 1. 初始化上传实例
    // NSArray *array = @[imageFilePath1, imageFilePath2, imageFilePath3];
    // 图片个数最大值为 10，大于 10 将上传失败并报错
    BDImageXUploaderClient *imageXUploadClient = [[BDImageXUploaderClient alloc] initWithFilePaths:<#arrary#>];
    
    // 2. 设置鉴权。鉴权参数需要业务向自己的 Server 端获取    
    [imageXUploadClient setAuthorizationParameter:@{
        BDFileUploadAccessKey:accessKey,  //AK
        BDFileUploadSecretKey:secretKey,  //SK
        BDFileUploadSessionToken:sessionToken, // 服务端生成上传凭证，请参考：https://www.volcengine.com/docs/508/34566
        BDFileUploadServiceID:serviceId,  // serviceId 的获取可以参考：https://www.volcengine.com/docs/508/8086
    }];
    
    // 3. 根据业务需要, 配置上传参数 
    // 如需要配置其他参数，请参考下文上传配置参数
    [imageXUploadClient setUploadConfig:@{
        BDFileUploadSDKRetryPolicy:@(BDSDKRetryPolicyMaxRetryCount),
        BDFileUploadSocketConnectTimeout:@5,
        BDFileUploadSocketReadTimeout:@5,
        BDFileUploadSocketWriteTimeout:@5,
        BDFileUploadTotalRequestTimeout:@20,
        BDFileUploadSDKMaxRetryCount:@2,
    }];
    
    // 4. 设置上传实例的 deleagate
    //  @see {BDImageXUploaderClient.h}
    imageXUploadClient.delegate = self;
    
    // 5. 
    self.imageXUploaderClient = imageXUploadClient;
}

4.上传控制

[self.imageXUploaderClient start];
	

[self.imageXUploaderClient stop];
	

[self.imageXUploaderClient close];
	

5.上传状态监听和回调

#pragma mark - BDImageXUploadClientDelegate

/// 单张图片上传完成的回调
/// @param uploadClient 上传对象
/// @param fileIndex 图片的索引
/// @param imageInfo 上传出错，返回的值为nil
/// @param error 上传出错，error会有值
- (void)imageXUpload:(nonnull BDImageXUploaderClient*)uploadClient fileIndex:(NSInteger)fileIndex singleImage:(nullable BDUploadImageXInfo *)imageInfo error:(nullable NSError *)error {
    // 
}
 
/// 单张图片的进度
/// @param uploadClient 上传对象
/// @param fileIndex 图片的索引
/// @param progress 图片的上传进度
- (void)imageXUpload:(nonnull BDImageXUploaderClient*)uploadClient fileIndex:(NSInteger)fileIndex progressDidUpdate:(NSInteger)progress {
    
}
 
/// 上传所有的流程完成，在这里面可以进行上传对象的释放
/// @param uploadClient 上传对象
- (void)imageXUploadDidFinish:(nonnull BDImageXUploaderClient*)uploadClient {
    [uploadClient close];
}

BDUploadImageXInfo

图片上传错误码获取方法的代码示例如下所示：

(void)imageXUpload:(nonnull BDImageXUploaderClient*)uploadClient fileIndex:(NSInteger)fileIndex singleImage:(nullable BDUploadImageXInfo *)imageInfo error:(nullable NSError *)error;

错误码详情请参见上传 SDK 错误码。

6.日志回调

您可通过以下回调接口指定日志内容和日志级别，获取上传日志以分析问题。

// 日志回调配置。当有日志信息产生时，日志将通过该接口回调。
[[BDUploadUtilTool sharedInstance] setLogCallback:^(NSString *info, int level) {
    NSLog(@"custom_log:%@", info);
}];