集成小程序上传 SDK

本文为您介绍如何集成小程序上传 SDK，支持微信小程序、抖音小程序。

适用版本

此文档适用于 TTSDK 2.0.0 及以上的版本，其他版本请参考历史版本小程序上传 SDK。

接入准备

获取上传签名

上传前需要从服务端获取上传 stsToken 签名，签名算法服务端接入，具体请参考：服务端 SDK > 生成上传凭证 > 生成临时上传密钥。

添加域名白名单

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

• request 合法域名：

  • https://vod.volcengineapi.com
  • https://mcs.zijieapi.com
  • https://tob-upload-x.volcvod.com
  • https://tob-upload-y.volcvod.com
  • https://tob-upload-x-d.volcvod.com
  • https://tob-upload-y-d.volcvod.com

  截图示例如下所示：

  

• uploadFile 合法域名：

  • https://tob-upload-x.volcvod.com
  • https://tob-upload-y.volcvod.com
  • https://tob-upload-x-d.volcvod.com
  • https://tob-upload-y-d.volcvod.com

  截图示例如下所示：

  

Demo 示例

引入 npm 包

npm install tt-uploader-miniprogram

快速开始

import TTUploader from 'tt-uploader-miniprogram';

// 1. 初始化 uploader
const uploader = new TTUploader({
  userId: 'volcengine-user1',  //建议设置能识别用户的唯一标识 ID，用于上传出错时排查问题，不要传入非 ASCII 编码。
  appId: 8888,                 //在视频点播控制台应用管理中创建的 AppID，视频点播的质量监控等都是以这个参数来区分业务方的，务必正确填写。
  videoConfig: {
    spaceName: 'your spaceName' //在视频点播中创建的点播空间名。
  }
});

// 2. 设置监听事件
uploader.on('error', (info) => {
    console.log('上传失败', info)
})
uploader.on('progress', (infor) => {
    console.log('上传进度：', infor.percent)
});
uploader.on('complete', (info) => {
    console.log('上传成功', info)
})

// 3. 添加上传文件
const key = uploader.addFile({
   path: '',      // 文件临时路径，从 chooseMedia 回调中获取。
   size: 1234,    // 文件大小，从 chooseMedia 回调中获取。
   // 从服务端获取到的签名 token，见上方【获取上传签名说明】说明
   stsToken: {
       "CurrentTime":"2023-03-31T07:47:14.866Z",
       "ExpiredTime":"2023-05-30T07:47:14.866Z",
       "SessionToken":"STS2eyJU******MTlmZWEzNzBlNWQ4ZmU3NjAwMTljIn0=",
       "AccessKeyId":"AKTPZDM1ODg3MG******zODEyYmZiNTU5ODg",
       "SecretAccessKey":"aNXEA8uvCBF7tqtoolAxJ******l7KTZcaxyOWQbuPqg=="
   }, 
   type : 'media',       // 上传文件类型，三个可选值：（默认值）media(视频或者音频)，image(图片)，object（普通文件）
});

// 4. 开始上传
uploader.start(key)

详细配置及 API 说明

初始化配置

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

const uploader = new TTUploader({
    userId: 'xxx',
    appId: 8888,
    
    //视频/普通文件上传必传字段
    videoConfig: {
        spaceName: 'your space name'
    },
    useFileExtension: true,
    uploadTimeout: 1000 * 60 * 30,
    gatewayTimeout: 1000 * 60 * 5
});

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

addFile(fileOption)

添加视频文件，传入的 fileOption 配置如下表所示。

Action 对象的结构如下表所示。

processAction

processAction 目前支持的 action 如下表所示。

各个 action 的输入参数如下表所示。

addFile 方法中 type 参数的取值和 Category 对应关系如下表所示。

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

const key = uploader.addFile({
    file: file, // 上传的文件对象
    stsToken: {},
    type: 'media',
    processAction: [
        {
            Name: 'GetMeta'
        },
        {
            Name: 'Snapshot',
            Input: {
                SnapshotTime: 2
            }
        }
    
    ]
});
console.log(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事件回调的参数如下所示：

视频上传

对于视频上传的返回结果，默认情况下只会返回 Vid，如果想获取详细的视频 meta 信息、封面图，请在上传时添加配置。

普通文件上传

error 事件

error 事件回调的参数如下所示：

错误码

详见上传 SDK 错误码。