You need to enable JavaScript to run this app.
导航
快速开始
最近更新时间:2024.10.22 17:39:03首次发布时间:2022.10.18 20:15:10

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

适用版本

此文档适用于 SDK 1.32.2 及以上版本,其他版本文档请参考 Android 上传 SDK 接入文档(旧版)

前提条件

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

日志调试

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

说明

为了减少性能开销,请务必关闭 Release 线上版本。

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 中执行,来保障初始化顺序。

注意

  • 初始化不会采集用户个人信息,也不会向抖音开放平台上报数据。

  • 您可根据实际情况自主选择是否接入 SDK 的日志上报扩展功能。

    强烈建议您启用该功能模块,若您无需使用日志上报或不希望隐私数据被采集,请在初始化前时将 openAppLog 指定为 false。

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());
  • 参数获取:请在火山引擎控制台创建应用后获取。

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

参数类型说明
AppIdStringApp ID,必填。从火山引擎控制台应用管理获取。
AppNameStringApp 英文名,必填。从火山引擎控制台应用管理获取。
AppVersionStringApp 版本号,必填。该值需要您根据实际业务情况自定义,使用 BuildConfig.VERSION_NAME,合法版本号应包含大于等于 2 个分隔符,例如:"1.3.2" 。
AppChannelStringAPP 渠道号,必填。该值需要您根据实际业务情况自定义,例如:小米应用商店 (xiaomi)、华为应用市场 (huawei) 等。

2.创建实例

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

BDImageXUploader mUploader = new BDImageXUploader();

3.设置要上传的文件

设置要上传的文件,上传 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);
	

4.鉴权设置

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

注意

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

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

5.设置 ServiceID

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

mUploader.setServiceID("xxx");

6.上传控制

SDK 内部在执行此函数的时候会新建线程,不会阻塞。具体操作代码示例如下所示:
mUploader.start() ;
	

注意

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

7.设置回调

在 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回调说明如下表所示:

消息类型返回的 what 值说明对应 parameter 含义对应 info 含义
MsgIsUpdateProgress1单张图片上传进度更新。上传进度。取值范围为[0, 100]info 里包含图片的 index 信息。详见BDImageXInfo参数说明。
MsgIsSingleImageComplete6单张图片上传完成通知。0,无意义info 里包含上传完成图片的 index 和 mImageTosKey 等信息。详见BDImageXInfo参数说明。
MsgIsSingleImageFail7图片上传失败通知。调用close()来释放上传对象。详情请见 Android 上传错误码常见错误码info 里包含图片的 index 信息。详见BDImageXInfo参数说明。

MsgIsComplete

0

整个上传流程完成通知,在单张图片上传成功或失败时均会回调。调用close()来释放上传对象。
不能从该处获取单张图片的上传信息,每张图片的上传信息应依赖于MsgIsSingleImageCompleteMsgIsSingleImageFail回调信息。

0,无意义

无需关注

BDImageXInfo

参数类型示例值说明
mImageTosKeyStringf2**9a.png文件存储 Key。
mFileIndexInteger1图片序号,对应传入上传图片数组的下标。

mMetaInfo

String

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

文件信息,包含 FileName、SourceUri、ImageSize、ImageUri 等。 参数详情参见 ImageInfo 字段说明。

mProgressLong100上传进度,取值范围为:[0, 100]。
mErrorCodeLong100026详情请参见上传 SDK 错误码
mEncryptionMetaString-图片的加密信息,字段为空,暂不支持使用。

mErrorMsg

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 格式数据)。