本文为您介绍如何用 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。鉴权参数说明及获取方式详见 客户端上传说明 ，具体操作代码示例如下所示：

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

设置 ServiceID

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

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

上传控制

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

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 为错误日志，详情见下表：

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

{
        "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