快速开始--veImageX-火山引擎

文档中心

立即注册

veImageX

iOS 上传 SDK

快速开始

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

适用版本

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

前提条件

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

1.初始化 SDK

注意

初始化不会采集用户个人信息。
若您只需要集成 veImageX 的 iOS 上传 SDK，并且不需要集成其他需要鉴权的 SDK 模块（如视频点播播放器 SDK 和视频直播 SDK），那么请在初始化时移除 licenseName 或将其传入空值。
若您需要同时集成其他需要鉴权的 SDK 模块时，请在初始化时将实际 License 文件名传入 licenseName。
您可根据实际情况自主选择是否接入 SDK 的日志上报扩展功能。
- 若不接入，veImageX 控制台的上传数据监控和告警管理将无法展示相关数据。
- 若接入，为实现日志上报功能 SDK 将按照上传 SDK 相关协议收集隐私数据。
  强烈建议您启用该功能模块，若您无需使用日志上报或不希望隐私数据被采集，请在初始化时将 shouldInitAppLog 指定为 NO。

#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。
    // 开启云控配置下发功能
    configuration.shouldUseCloudControl = YES;
    // 如果需要指定deviceID进行配置下发，则可以通过一下代码配置deviceID
    configuration.logConfiguration = [[TTSDKLogConfiguration alloc] init];
    configuration.logConfiguration.deviceID = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
    // TTSDK 初始化
    [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 实例的生命周期，如设置为局部变量，会导致离开作用域后，无法继续进行上传操作。

注意

如需使用重名文件覆盖上传，请确保您获取的 STS2 上传签名（此处以 Golang 为例）已开启重名覆盖。

#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.上传控制

开始上传

暂停上传

结束上传

SDK 内部在执行此函数的时候会新建线程，不会阻塞。具体操作代码示例如下所示：

[self.imageXUploaderClient start];

注意

当您不需要再次进行上传操作时，请务必调用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

参数	说明
storeId	TOS 存储 Key，命名规范参看 veImageX 存储 Key 通用字符规则。
fileIndex	图片序号，对应传入上传图片数组的下标。
metainfoDict	文件信息，包含 FileName、SourceUri、ImageSize、ImageUri 等。
encryInfo	图片的加密信息，字段为空，暂不支持使用。

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

(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);
}];

最近更新时间：2025.05.07 21:04:17

这个页面对您有帮助吗？

有用

无用