集成小程序上传 SDK

本文为您介绍小程序版本上传 SDK，支持微信小程序、抖音小程序和 uni-app 开发框架。

适用版本

本文档仅适用于 TTSDK 2.0.0 及以上的版本，其他版本请参考小程序上传 SDK（旧版）。

前提条件

• 已开通 veImageX。

• 已创建服务，如未创建，请完成新建服务。

• 已创建应用，如未创建，请完成新建应用。

注意事项

• veImageX 同时提供了素材资源托管与图像处理两类服务，您可根据实际需要指定上传文件存储服务类型。两种服务区别如下：
  • 素材托管服务：支持任意合法资源的上传和托管；
  • 图像处理服务：支持任意合法资源的上传和托管，还支持对图像文件执行图像实时处理。
• 为了提高小程序平台大文件上传成功率，当上传文件大小大于 10M 时，SDK 将默认对大文件进行分片上传，每个分片大小默认为 5M。
• 当使用 uni-app 集成小程序上传 SDK 时，因平台限制，仅在小程序平台支持分片上传，对于 Android 和 iOS 原生平台，如您需要进行分片上传，建议您集成原生的 Android / iOS 上传 SDK，否则可能会影响大文件的上传质量。

接入准备

获取上传签名

上传前需要从服务端获取上传 STS 临时访问凭证，签名算法由服务端接入，接入方法请参考以下服务端各生成上传凭证文档：

• 生成上传凭证-Golang

• 生成上传凭证-PHP

• 生成上传凭证-Python

• 生成上传凭证-Java

• 生成上传凭证-Nodejs

添加域名白名单

把网关地址和上传地址添加到小程序的访问白名单中。

安装 SDK

使用 npm 方式引入 SDK，具体代码示例如下所示：

npm install tt-uploader-miniprogram

集成 SDK

您可参考以下代码示例，配置回调监听并快速将文件上传至指定服务 ID 对应的 veImageX 服务中。

import TTUploader from 'tt-uploader-miniprogram';
// 初始化uploader
const uploader = new TTUploader({
    userId: 'volcengine-user1',  // 必填，用户 ID。自定义，建议设置能识别用户的唯一标识 id，用于上传出错时排查问题，不要传入非 ASCII编码
    appId: 78**27,             // 必填，应用 ID。在应用服务中创建的 AppID，质量监控等以该参数来区分业务方，务必正确填写
    imageConfig: {
        serviceId: 'hj****7f' // 必填，服务 ID。请在 veImageX 控制台-服务管理查看并记录该值
    }
});
// 设置监听事件
uploader.on('error', (info) => {
    console.log('上传失败', info)
})
uploader.on('progress', (infor) => {
    console.log('上传进度：', infor.percent)
});
uploader.on('complete', (info) => {
    console.log('上传成功', info)
})
// 添加上传文件
const key = uploader.addImageFile({
   path: '',      // 文件临时路径，从 chooseMedia 回调中获取
   size: 1234,    // 文件大小，从 chooseMedia 回调中获取
   // 从服务端获取到的临时访问凭证，请参考【接入准备-获取上传签名】说明
   stsToken: {
       "CurrentTime":"2023-03-31T07:47:14.866Z",
       "ExpiredTime":"2023-05-30T07:47:14.866Z",
       "SessionToken":"STS2****In0=",
       "AccessKeyId":"AKTPZDM1***iNTU5ODg",
       "SecretAccessKey":"aNXEA8uvC***Pqg=="
   }，
   fileExtension: '.png'
});
// 开始上传
uploader.start(key)

初始化 SDK

初始化uploader实例时可配置的属性如下所示：

const uploader = new TTUploader({
    userId: 'Test1',  //必填，自定义用户 ID，用于定位某用户的日志。
    appId: 67**23,  //必填，应用 ID，用于定位某业务应用的日志。
    imageConfig: {  //必填，图片上传配置。
        serviceId: 'hi****2t'  //必填，服务 ID，用于指定文件上传所在服务。
    }
});

您可参考下表完成以下配置，各配置具体说明如下表所示：

imageConfig

功能说明

addImageFile(imageFileOption)

添加上传图片文件，返回当前文件的 key 值（上传和取消上传等使用该值）。传入的 imageFileOption 配置如下表所示：

该方法返回当前文件的 key 值时，用于开始上传和取消上传，代码示例如下所示：

const key = ttUploader.addImageFile({
    path: '',      // 上传文件临时路径
    size: ,    // 上传文件大小
    stsToken: {
        AccessKeyId: "",
        SecretAccessKey: "",
        SessionToken: "",
        ExpiredTime: "",
        CurrentTime:"",
    }，
    fileExtension: '.png'  //指定上传文件扩展名
});
console.log(key);  // 返回的文件 key 值，例如：file_1495442273603_999031

start(key)

启动上传任务。如果该上传任务被暂停，则再次调用此方法时将恢复上传。请传入上传文件的 key 值，如不传，则所有已添加的文件将开始上传。

uploader.start();

pause(key)

暂停上传，将暂存当前文件的上传信息。传入文件的 key 值，如不传，则将暂停所有文件的上传。

uploader.pause('file_1495442273603_999031');

restart(key)

恢复上传，将恢复当前被暂停的上传任务。传入文件的 key 值，如不传，则将恢复所有文件的上传。

uploader.restart();

cancel(key)

取消某一文件的上传，同时删除暂存的上传信息。传入文件的 key 值，如不传，则将取消所有文件的上传。

uploader.cancel();

事件说明

在文件上传的过程中，SDK 会依次抛出各类事件以通知外部，可根据业务需要监听这些事件，事件名称和事件描述如下表所示：

// 监听事件
uploader.on('progress', function(info) {
    console.log('上传进度:', info.percent);
});
uploader.on('complete', function(info) {
    console.log('上传成功:', info);
});
uploader.on('error', function(info) {
    console.error('上传失败:', info);
});

progress 事件

progress 事件回调参数如下表所示。

complete 事件

complete事件回调参数如下表所示。

uploadResult

error 事件

error 事件回调参数如下表所示。

错误码说明