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

适用版本

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

前提条件

您已完成上传 SDK 的集成准备。

日志调试

开启日志调试

在实际开发过程中，为了便于调试以及排查问题，建议您打开 logcat 日志。

BDUploadLog.turnOn(LOG_DEBUG, 1);
BDUploadUtil.setEnableNativeLog(true);

日志回调

若您已具备回捞日志能力，那么您可通过以下接口获取线上日志以分析问题。

BDUploadLog.turnOn(LOG_DEBUG, 1);
BDUploadUtil.setEnableNativeLog(true); 

/**
  * 设置日志打印类型，取值如下所示：
   * LOG_PRINT_NONE：本地不打印日志，也不回调日志
  * LOG_PRINT_LOCAL：仅打印日志
  * LOG_PRINT_CALL_BACK：仅回调日志
  * LOG_PRINT_BOTH：本地打印日志，并且回调日志
  */
BDUploadLog.setLogPrintType(LOG_PRINT_BOTH);

/**
  * 日志回调配置。当有日志信息产生时，日志会通过该接口进行回调。
  * @param level 日志级别
  * @param tag 日志 tag
  * @param msg 日志内容
  */
BDUploadLog.setALogCallback((level, tag, msg) -> {
    // 调用接入方日志回捞接口
});

集成步骤

1.初始化 SDK

初始化为轻量操作，建议您放到 Application#onCreate 中执行，来保障初始化顺序。

Env.openAppLog(false);  //若无需接入日志上报能力，请指定为 false。否则指定为 true。
Env.init(new Config.Builder()
        .setApplicationContext(context)
        .setAppID("your app id")
        .setAppName("your app English name")
        // 合法版本号应大于、等于 3 位，如："1.3.2"
        .setAppVersion(BuildConfig.VERSION_NAME)
        .setAppChannel("channel name")
        .build());

• 参数获取：请在火山引擎控制台创建应用后获取。
• 详细的参数说明如下表所示。

2.设置自定义用户 ID

1.35.1.4 及之后版本已支持。
如果您自己已有一套独立的用户 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);
    }
}

3.创建实例

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

BDImageXUploader mUploader = new BDImageXUploader();

4.设置要上传的文件

设置要上传的文件，上传 SDK 支持两种方式，您可任选其一。

/**
  * 设置文件绝对路径
 * 
  *  @param num 图片个数，最大值为 10，大于 10 报错
  *  @param path 图片绝对路径数组
  */
public void setFilePath(int num, String[] path) 

int num = 2;
String[] path = new String[num];
path[0] = "/mnt/sdcard/test0.jpg";
path[1] = "/mnt/sdcard/test1.jpg";

mUploader.setFilePath(num, path);
   

/**
  * 设置 Reader
 * 
 *  @param  reader  详见《Android 10 分区存储》
  *  @param num 图片个数，最大值为 10，大于 10 报错
  */
public void setMediaDataReader(BDMediaDataReader reader, int fileNum);
   

5.鉴权设置

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

mUploader.setTopAccessKey("xxx");
mUploader.setTopSecretKey("xxx");
mUploader.setTopSessionToken("xxx");

6.设置 ServiceID

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

mUploader.setServiceID("xxx");

7.上传控制

mUploader.start() ;
   

mUploader.stop();
   

mUploader.close()
   

8.设置回调

在 A 线程创建 Uploader 实例，如果 A 线程存在 Looper，则在 A 线程回调；否则在主线程回调。

public void setListener(BDImageXUploaderListener listener)

public interface BDImageXUploaderListener {
    // 上传进度和上传完成的回调，详见下表 onNotify 回调说明
    void onNotify(int what, long parameter, BDImageXInfo info);
    
    // 关键日志回调，接入方可将回调信息上传到接入方服务器，可通过日志排查线上问题。
    // 需要通过 mUploader.setEnableLogCallBack(true) 开启才能生效。
    // 不使用空实现即可。
    void onLog(int what, int code, String info);
    
    // 上传出错重试时回调；由接入方检查网络状态，
    // 返回 1 sdk 认为有网，进行重试；
    // 返回 0 sdk 认为无网，不再进行重试
    // 如接入方不想检查网络状态，返回 1 即可，SDK 会在重试次数、超时时间内重试。
    int imageXUploadCheckNetState(int errorCode, int tryCount);
}

onNotify回调说明如下表所示：

BDImageXInfo

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

"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