You need to enable JavaScript to run this app.
导航
Android 上传 SDK 接入文档(旧版)
最近更新时间:2024.07.25 21:52:04首次发布时间:2021.02.23 10:42:28
一、阅读对象

本文档为技术文档,建议阅读者具有基本的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 中执行,保障初始化顺序

需要的参数列举如下:

参数类型释义说明
appidIntegerApp idSDK 用于打点监控上报的最小单元,通过此将数据进行隔离上报,同时通过 AppID 可以拉取对应的云控配置比如客户端采样率、网络优化参数等。请登录控制台我的应用获取。
appnameStringApp 英文名App 的名称,用于统计使用
appchannelString渠道渠道标识,用于区分统计不同渠道来源的图片服务质量数据。比如可传入 huawei、oppo 等不同渠道标识,便于统计区分

region

String

appid 填写的地区或者国家

指存储文件、日志数据的机房所在区域。

  • 取值为cn-north-1,表示为中国。
  • 取值为ap-singapore-1,表示为新加坡。
appversionStringApp 版本App 版本号
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");

说明

SessionToken 的获取方式可参考以下文档:

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

参数类型释义是否必须设置
mSecretAccessKeyString服务端鉴权参数:临时sk
mAccessKeyIdString服务端鉴权参数:临时ak
mSessionTokenString服务端鉴权参数:token
mExpiredTimeString服务端鉴权参数:过期时间
mFilePathNamesString[]图片上传路径,一次最多9张
mFileNamesString[]图片名称
mFileCountint图片张数
mSpaceString账号对应serviceID
mRegionString地区
mFileTypeString文件类型,图片需要设置为"image"、文件需要设置为"object"、默认为"image"否,无论如何使用ImageX,配置类型为 image
mImageHostNameStringimagex的网关地址,文件上传域名
mSocketNumint上传使用的socket数量/上传的并发数
mFileRetryCountint文件重试次数
mMaxFailTimeint最大的失败时间,超过这个时间,上传就不重试了
mEnableHttpsboolean是否用https上传

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实例

说明

在上传完成、上传失败或者其他任何时候需要释放上传对象的时候,一定要调用其- (void)close和- (void)stop 其中一个,不然会引起crash或者内存泄漏。

  • 图片上传信息获取

对应的监听类为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:

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

MsgIsComplete(全部图片上传任务完成)-
MsgIsUpdateProgress
(图片上传进度)
TTImageInfoTop 结构中的 mProgress 表示进度,mFileIndex 表示图片索引。
MsgIsSingleImageComplete
(单张图片上传任务完成)
获取上传的图片信息,如资源id,媒体元信息等相关信息,信息封装在 TTImageInfoTop 中 TTImageInfoTop 结构如下表所示。
MsgIsSingleImageFail
(单张图片上传任务失败)
TTImageInfoTop 结构中的 mErrcode 同样表示错误码,mFileIndex 表示图片索引。

TTImageInfoTop结构

成员变量含义说明
mStoreUri资源id,图片的uriString
mFileIndex图片索引int
mProgress上传进度long [0~100]
mErrcode错误码long 有错误的时候会获得
mMediaInfo返回的媒体信息 (json)String imageX属性信息
mEncryptInfo上传的图片的加密信息String
  • 质量埋点获取

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

目前可在图片上传完成( 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);