You need to enable JavaScript to run this app.
veImageX

veImageX

请输入
  • 文档首页
    • veImageX客户端 SDK上传 SDK历史文档Android 上传 SDK 接入文档（旧版）
复制全文
我的收藏
历史文档
Android 上传 SDK 接入文档（旧版）
复制全文
我的收藏
Android 上传 SDK 接入文档（旧版）
一、阅读对象

本文档为技术文档，建议阅读者具有基本的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);
最近更新时间：2024.07.25 21:52:04
这个页面对您有帮助吗？
有用
有用
无用
无用