文档中心

veImageX

Flutter 上传 SDK

快速开始

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

初始化 SDK

初始化前不会采集用户个人信息。
您可根据实际情况自主选择是否接入 SDK 的日志上报扩展功能。
- 若不接入，veImageX 控制台的上传数据监控和告警管理将无法展示相关数据。
- 若接入，为实现日志上报功能 SDK 将按照上传 SDK 相关协议收集隐私数据。
强烈建议您启用该功能模块，若您无需使用日志上报或不希望隐私数据被采集，请在初始化前时将 openAppLog 指定为 false。

EnvOptions options = EnvOptions(
  appID: '512559',
  appChannel: 'appChannel',
  appVersion: '1.0.0',
  appName: "FlutterUploadDemo",
  userUniqueId: "xxxxxxxx",
  openAppLog: true,
  autoStartAppLog: true,
  debugLogLevel: true,
  enableLocalLogPrint: true,
  enableLogCallback: true,
  useImageXCloudControl: true,
  deviceID: 'bd_flutter_upload_demo',
);

await initEnv(options);

参数获取：请在火山引擎控制台创建应用后获取。

详细的参数说明如下表所示。

参数	类型	默认值	说明
appID	String	无	App ID，必填。从火山引擎控制台应用管理获取。
appChannel	String?	null	APP 渠道号，必填。该值需要您根据实际业务情况自定义，例如：小米应用商店 (xiaomi)、华为应用市场 (huawei) 等。
appVersion	String?	null	App 版本号，必填。该值需要您根据实际业务情况自定义，使用 BuildConfig.VERSION_NAME，合法版本号应包含大于等于 2 个分隔符，例如："1.3.2" 。
appName	String?	null	App 英文名，必填。从火山引擎控制台应用管理获取。
userUniqueId	String?	null	设置用户唯一ID，配合AppLog使用。详情参看：2. 设置自定义用户 ID
deviceID	String?	null	设备DeviceID，用于云控逻辑针对某设备下发对应配置
openAppLog	bool?	true	是否初始化AppLog
autoStartAppLog	bool?	true	开启AppLog（此字段只在Android端生效，推荐在用户同意隐私权限前设置为false，在用户同意隐私权限之后调用 `await Env.startAppLog();` 去打开AppLog上报能力）
debugLogLevel	bool?	false	设置Debug级别LogLevel，debug阶段建议开启，线上请置为false。
enableLocalLogPrint	bool?	false	是否打印native日志，debug阶段建议开启，线上请置为false。
enableLogCallback	bool?	false	是否开启日志回调，配合 `setLogCallback(void Function(String?, int?) callback)`接口使用
useImageXCloudControl	bool?	false	是否开启ImageX 上传云控功能

日志回调

当 enableLogCallback 设置为 true 的时候，通过设置setLogCallback(void Function(String?, int?) callback)可进行日志回调。

import 'package:volc_bd_file_upload/core/upload.dart';

// msg: 日志内容。 level: 0 - 6 ，值越大日志级别越高
await setLogCallback((msg, level) {
  print('log callback------------>: $msg, $level');
});

设置自定义用户 ID

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

// 设置用户 ID
private void initSDK(Context context, String userUniqueId) {
    // 1. 根据上节内容初始化 SDK 
    Env.init(new Config.Builder()
        // ... 省略
        .build());
    // 2. 获取 AppLog 实例设置 userUniqueId
    IAppLogInstance applog = AppLogWrapper.getAppLogInstance();
    if (applog != null && !TextUtils.isEmpty(userUniqueId)) {
        applog.setUserUniqueID(userUniqueId); 
    }
}

// 移除自定义用户 ID，您的用户注销登录时调用
private void onUserLogout() {
    IAppLogInstance applog = AppLogWrapper.getAppLogInstance();
    if (applog != null) {
        applog.setUserUniqueID(null);
    }
}

// 更新自定义用户 ID，您的用户登录成功/切换登录后调用
private void onUserLogin(String userUniqueId) {
    IAppLogInstance applog = AppLogWrapper.getAppLogInstance();
    if (applog != null) {
        applog.setUserUniqueID(userUniqueId);
    }
}
java

Future<void> initUploaderEnv() async {
    // 初始化
    EnvOptions options = EnvOptions(
      // ...
      userUniqueId: "xxxxx",
    );
    
    await initEnv(options);
}

Future<void> onUserLogin(String userUniqueId) async {
    // 当用户登录后调用此API
    await onUserLogin(userUniqueId);
}

Future<void> onUserLogout() async {
    // 当用户退出登陆时调用此API
    await onUserLogout();
}

创建实例

实现创建实例的代码示例如下所示：

import 'package:volc_bd_file_upload/bd_file_upload.dart';

ImageXUploaderOptions options = ImageXUploaderOptions options = ImageXUploaderOptions(
  accessKey: "ak",
  secretKey: "sk",
  sessionToken: "token",
  serviceID: "serviceID",
  filePaths: filePaths,
  };

BDImageXUploader uploader = await initImageXUploader(options);

设置要上传的文件

设置要上传的文件，要求List长度大于等于1。

ImageXUploaderOptions options = ImageXUploaderOptions(
...
filePaths: ["filePath1", "filePath2", "filePath3"],
}

鉴权设置

从您的 AppServer 获取鉴权参数设置给 SDK。鉴权参数说明及获取方式详见客户端上传说明，具体操作代码示例如下所示：

注意

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

ImageXUploaderOptions options = ImageXUploaderOptions(
  accessKey: "your accessKey",
  secretKey: "your secretKey",
  sessionToken: "your token",
  ...
}

设置 ServiceID

为账号对应的 ServiceID，具体说明以及获取方式您可参考图片服务管理。具体操作代码示例如下所示：

ImageXUploaderOptions options = ImageXUploaderOptions(
  ...
  serviceID: "your service ID",
}

上传控制

注意

当您不需要再次进行上传操作时，请务必调用 close() ，否则会导致内存泄漏。

具体操作代码示例如下所示：

BDImageXUploader uploader = await initImageXUploader(options);
// 开启上传
await uploader.start();

// 暂停上传
await uploader.stop();

// 终止上传 释放上传资源
await uploader.close();

设置回调

await uploader.setListener(
  ImageXUploaderInfoCallback(
     // 上传任务结束后回调
    onImageXUploadDidFinish: () async {
      print(
        '--- [ImageXUploaderInfoCallback] onImageXUploadDidFinish',
      );
      // 关闭上传对象，释放资源
     await uploader.close();
    },
    // 单张图片上传成功后回调
    onSingleImageSuccess: (uploadInfo) {
      print(
        '--- [ImageXUploaderInfoCallback] onSingleImageSuccess: ${jsonEncode(uploadInfo)}',
      );
    },
    // 单张图片上传失败后回调
    onSingleImageFail: (errorCode, errorMsg, uploadInfo) {
      print(
        '--- [ImageXUploaderInfoCallback] onSingleImageFail: $errorCode, $errorMsg, ${jsonEncode(uploadInfo)}',
      );
    },
    // 单张图片上传进度回调:[0,100]
    onSingleImageProgress: (progress, uploadInfo) {
      print(
        '--- [ImageXUploaderInfoCallback] onSingleImageProgress: $progress, ${jsonEncode(uploadInfo)}',
      );
    },
  ),
);

回调中 errorCode 为错误码，errorMsg 为错误日志，详情见下表：

参数	类型	示例值	说明
errorCode	int	4006	详情请参见上传 SDK 错误码。
errorMsg	String	"code":100026, "httpCode":200, "httpBody":{ "ResponseMetadata":{ "RequestId":"20240108***4EF5E6", "Action":"ApplyImageUpload", "Version":"2018-08-01", "Service":"imagex", "Region":"cn-north-1", "Error":{ "CodeN":100026, "Code":"InvalidSecretToken", "Message":"Invalid secret token, msg: token expired.." } } }, "stage":2001	错误信息描述（非 json 格式数据）。

回调中uploadInfo 类型为 BDImageXUploadInfo，具体参数见下表：
BDImageXUploadInfo

参数	类型	示例值	说明
tosKey	String?	`f2**9a.png`	文件存储 Key。命名规范参看 veImageX 存储 Key 通用字符规则。
fileIndex	int?	`1`	图片序号，对应传入上传图片数组的下标。
mMetaInfo	Map<dynamic, dynamic>?	`{ "FileName":"f2**9a.png", "SourceUri":"tos-cn-i-5sfo/f29a.png", "ImageUri":"tos-cn-i-5sfo/f219a.png", "ImageWidth":2718, "ImageHeight":2300, "ImageMd5":"9683", "ImageFormat":"png", "ImageSize":108886, "FrameCnt":1 } json`	文件信息，包含 FileName、SourceUri、ImageSize、ImageUri 等。参数详情参见 ImageInfo 字段说明。
aesKey	String?	`100`	上传进度，取值范围为：[0, 100]。

最近更新时间：2025.06.04 16:26:17

这个页面对您有帮助吗？

有用

无用

veImageX

初始化 SDK #

日志回调 #

设置自定义用户 ID #

创建实例 #

设置要上传的文件 #

鉴权设置 #

设置 ServiceID #

上传控制 #

设置回调 #