本文档为技术文档，建议阅读者具有基本的Android开发能力。

系统支持Android2.3 及以上开发版本。

推荐开发者使用 Android Studio 作为自己的开发工具，本开发文档也是基于 Android Studio开发环境下进行编写的。

项目 build.gradle 下加上

allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url "https://artifact.bytedance.com/repository/Volcengine/" // volc public maven repo
        }
    }
}

module build.gradle下简单添加依赖即可

android {
    defaultConfig {
        // APPLOG_SCHEME 为 AppLog SDK 必须参数，填任意值均可
        manifestPlaceholders.put("APPLOG_SCHEME", "online")
    }
}

dependencies {

//... your own dependencies...

def ttsdk_version = "x.x.x.x" //填写所需具体版本,最新版本号地址https://search.maven.org/artifact/com.bytedanceapi/ttsdk-ttuploader

implementation "com.bytedanceapi:ttsdk-ttuploader:$ttsdk_version"

implementation "com.bytedanceapi:ttsdk-ttcommon:$ttsdk_version"

// 埋点上报 applog sdk 依赖引入 用于上传质量监控。

def applog_version = "6.9.5" //固定版本号，为applog依赖，无特殊要求无需改动，若已经对接applog也可使用最新

implementation "com.bytedance.applog:RangersAppLog-Lite-cn:$applog_version"

//

}

最新版本 SDK 获取

最新ttsdk_version 获取：详见 ChangeLog

ttuploader是Android端使用的通用上传SDK。ImageX图片上传使用对象TTImageUploader，对应的监听类为TTImageUploaderListenerTop。另外还有质量统计类：UploadEventManager。

鉴权方式为STS2.

图片上传最多可以一次上传9张。

快速开始

本模块介绍如何使用上传SDK以最快捷的方式进行图片上传。请在完成集成准备后，再进行该步骤。

您可直接通过下述Demo，快速实现图片上传。

图片上传Demo

import com.ss.ttuploader.TTImageInfoTop;
import com.ss.ttuploader.TTImageUploaderConfig;
import com.ss.ttuploader.TTImageUploaderListenerTop;
import com.ss.ttuploader.TTImageUploaderTop;

Context mContext = this.getApplicationContext();

// 下面填写的参数仅供释义，请填写您自己的参数
Map<String, Object> appinfoMap = new HashMap<>();
appinfoMap.put("appname", "your app name");
appinfoMap.put("appid", 123); // your app id
appinfoMap.put("appchannel", "xiaomi_appstore"); // 设为test_channel不会展示日志
appinfoMap.put("region", "cn-north-1");
appinfoMap.put("appversion", BuildConfig.VERSION_NAME);

//初始化上传SDK配置
TTImageUploaderTop.setAppInfo(mContext, appinfoMap);   //初始化上传配置，建议早配置

//imageX上传对象的初始化和配置
TTImageUploaderTop uploaderTop = null;
try {                                           
    uploaderTop = new TTImageUploaderTop();              //初始化上传对象
} catch (Exception e) {
    e.printStackTrace();
    return null;
}   

TTImageUploaderConfig config = new TTImageUploaderConfig();
JSONObject sts = null;
try {
    sts = new JSONObject(authParam);    //authParam为鉴权串，从步骤3中获取。
    config.mSecretAccessKey = (String)sts.get("SecretAccessKey");
    config.mAccessKeyId = (String)sts.get("AccessKeyID");
    config.mSessionToken = (String)sts.get("SessionToken");
    config.mExpiredTime = (String)sts.get("ExpiredTime");
} catch (JSONException e) {
    e.printStackTrace();
}

config.mFilePathNames = new String[1];           //设置上传图片路径，一次最多9张
config.mFilePathNames[0] = "xxxxx";
config.mFileNames = new String[1];
config.mFileNames[0] = "xxxxx";
config.mFileCount = 1;
config.mSpace = "xxxx";     //账号对应serviceID
config.mRegion = "cn-north-1";   //地区，必须参数
config.mFileType = "image";       //设置文件类型为图片
config.mImageHostName = "imagex.volcengineapi.com";   //设置imagex的网关地址
config.mSocketNum = 1;             //上传使用的socket数量
config.mFileRetryCount = 3;          //文件重试次数
uploaderTop.setUploadConfig(config);

//注册回调
uploaderTop.setListener(new TTImageUploaderListenerTop() {
    @Override
    public void onNotify(int what, long parameter, TTImageInfoTop info) {
        if (what == TTImageUploaderTop.MsgIsComplete) {

        }
        else if(what == TTImageUploaderTop.MsgIsUpdateProgress){
            
        }
        else if(what == TTImageUploaderTop.MsgIsSingleImageComplete) {
            
        }
        else if (what == TTImageUploaderTop.MsgIsSingleImageFail) {
            
        }
    }
}); 

对于简单使用场景，使用上传SDK完成图片上传，需要以下4个步骤：

1. 初始化上传SDK环境

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

需要的参数列举如下：

Context mContext = this.getApplicationContext();

// 下面填写的参数仅供释义，请填写您自己的参数
Map<String, Object> appinfoMap = new HashMap<>();
appinfoMap.put("appname", "your app name");
appinfoMap.put("appid", 123); // your app id
appinfoMap.put("appchannel", "xiaomi_appstore"); // 设为test_channel不会展示日志
appinfoMap.put("region", "cn-north-1");
appinfoMap.put("appversion", BuildConfig.VERSION_NAME);

//初始化上传SDK配置
TTImageUploaderTop.setAppInfo(mContext, appinfoMap);   //初始化上传配置，建议早配置

2. 创建图片上传对象TTImageUploaderTop

import com.ss.ttuploader.TTImageUploaderTop;

//imageX上传对象的初始化和配置
TTImageUploaderTop uploaderTop = null;
try {                                           
    uploaderTop = new TTImageUploaderTop();              //初始化上传对象
} catch (Exception e) {
    e.printStackTrace();
    return null;
}  

note：需要关注下TTImageUploaderTop实例的生命周期，如设置为局部变量时，会导致TTImageUploaderTop实例析构销毁时，无法继续进行上传操作

3. 获取鉴权authParam

此处获取的鉴权参数authParam，用于第四步进行上传的鉴权配置

ex:
JSONObject responseJson 如下：
{
    "result":{
        "AccessKeyID":"XXXXXX",
        "SecretAccessKey":"XXXXXX",
        "SessionToken":"XXXXXX",
        "ExpiredTime":"XXXXXX",
        "CurrentTime":"XXXXXX"
    }
}

String authParam = responseJson.getString("result");

4. TTImageUploaderTop实例设置上传数据源及其他配置

serviceID相关说明请参考图片服务管理

import com.ss.ttuploader.TTImageUploaderConfig;

TTImageUploaderConfig config = new TTImageUploaderConfig();

JSONObject sts = null;
try {
    sts = new JSONObject(authParam);    //authParam为鉴权串，从步骤3中获取。
    config.mSecretAccessKey = (String)sts.get("SecretAccessKey");
    config.mAccessKeyId = (String)sts.get("AccessKeyID");
    config.mSessionToken = (String)sts.get("SessionToken");
    config.mExpiredTime = (String)sts.get("ExpiredTime");
} catch (JSONException e) {
    e.printStackTrace();
}

config.mFilePathNames = new String[1];           //设置上传图片路径，一次最多9张
config.mFilePathNames[0] = "xxxxx";
config.mFileNames = new String[1];
config.mFileNames[0] = "xxxxx";
config.mFileCount = 1;
config.mSpace = "xxxx";     //账号对应serviceID
config.mRegion = "cn-north-1";   //地区，必须参数
config.mFileType = "image";       //设置文件类型为图片
config.mImageHostName = "imagex.volcengineapi.com";   //设置imagex的网关地址
config.mSocketNum = 1;             //上传使用的socket数量
config.mFileRetryCount = 3;          //文件重试次数
uploaderTop.setUploadConfig(config);

基础功能接入

在快速开始章节中，我们完成TTImageUploaderTop实例的创建，本章节介绍如何使用TTImageUploaderTop实例进行上传

• 开始上传

uploaderTop.start();//开始上传

• 暂停上传

uploaderTop.stop();//暂停上传

• 释放TTImageUploaderTop实例

uploaderTop.close();//停止上传并释放TTVideoUploaderTop实例

• 图片上传信息获取

对应的监听类为TTImageUploaderListenerTop

//注册回调
uploaderTop.setListener(new TTImageUploaderListenerTop() {
    @Override
    public void onNotify(int what, long parameter, TTImageInfoTop info) {
        if (what == TTImageUploaderTop.MsgIsComplete) {
            //全部图片上传任务完成
            
        }
        else if(what == TTImageUploaderTop.MsgIsUpdateProgress){
            //图片上传进度，parameter表示最新进度位置
            
        }
        else if(what == TTImageUploaderTop.MsgIsSingleImageComplete) {
            //单张图片上传任务完成
            
        }
        else if (what == TTImageUploaderTop.MsgIsSingleImageFail) {
            //单张图片上传任务失败
        }
    }
}); 

note：

当对应事件发生时，可获取该事件下的相应事件信息，如下表所示

TTImageInfoTop结构

• 质量埋点获取

当您遇到上传的问题时，可以通过质量埋点上报的方式，提供相应日志，推进问题快速处理

目前可在图片上传完成（ MsgIsComplete ）、用户停止图片上传（调用函数stop()）这两个时机进行质量埋点上报

（建议客户针对具体场景和问题，在相应时机下提供埋点日志）

JSONArray jsonArray= UploadEventManager.instance.popAllImageEvents();

获得一个JSONArray，里面包含了此次上传的所有日志。

注意 pop 日志之后，jsonArray会清空，如果一次上传行为，第二次 pop 的话，会是一个空 jsonArray。

• Debug日志获取

当您遇到上传的问题时，可以打开Debug日志开关，获取详细日志信息，推进问题快速处理

时机：建议在调用上传之前配置Debug日志开关（在创建图片上传对象之前）
TTVideoUploaderTop.setEnableDebug(1);

高级功能接入

指定文件存储路径

note:

1. 上传n张图片时，需要分别为n张图片配置ImageX的存储路径（imagePathKeys的数组长度与上传的图片数量保持一致）
2. 文件存储路径：不支持以/开头或结尾，不支持/连续出现，存储路径最大长度为180个字符

TTImageUploaderTop uploaderTop;
try {
        uploaderTop = new TTImageUploaderTop();
    } catch (Exception e) {
        e.printStackTrace();
    }
        
TTImageUploaderConfig config = new TTImageUploaderConfig();
config.mFilePathNames = new String[3];
config.mFilePathNames[0] = "/mnt/sdcard/test1.jpg";
config.mFilePathNames[1] = "/mnt/sdcard/test2.jpg";
config.mFilePathNames[2] = "/mnt/sdcard/test3.jpg";
config.mStoreKeys = new String[3];
config.mStoreKeys[0] = "red";
config.mStoreKeys[1] = "yellow";
config.mStoreKeys[2] = "blue";
uploaderTop.setUploadConfig(config);