开发
API

tt.requestSubscribeMessage

基础库 1.73.0 开始支持本方法,低版本需做兼容处理。支持宿主:头条,抖音。 订阅功能介绍及使用方式见文档:订阅消息功能

调起客户端订阅消息界面,返回用户订阅消息的操作结果。当用户勾选了订阅面板中的 “总是保持以上选择,不再询问” 时,或是点击了订阅面板中 “拒绝,不再询问” 时,模板消息会被添加到用户的小程序设置页,用户可以在设置页面进行管理。

语法

tt.requestSubscribeMessage(options)

参数说明

options 为 object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
tmplIdsArray需要订阅的消息模板的 id 的集合,最多支持传入三个 tmplId1.73.0
successFuntion接口调用成功的回调函数1.73.0
completeFuntion接口调用结束的回调函数(调用成功、失败都会执行)1.73.0
failFuntion接口调用失败的回调函数1.73.0

回调成功

回调成功参数为 object 类型,属性如下:

属性类型说明
errMsgstring"requestSubscribeMessage:ok"
TEMPLATE_IDstring[TEMPLATE_ID]为模板 id,取值详见 TEMPLATE_ID

TEMPLATE_ID

说明
accept用户同意订阅该条 id 对应的模板消息
reject用户拒绝订阅该条 id 对应的模板消息
ban表示已被后台封禁
fail表示该条 id 对应的模版消息授权失败

示例:

// 以下返回值表示用户同意订阅 [YOUR_TEMPLATE_ID] 这条消息
{
  "errMsg": "requestSubscribeMessage:ok",
  "[YOUR_TEMPLATE_ID]": "accept"
}

回调失败

object 类型,属性如下:

属性名类型说明最低支持版本
errMsgstring接口调用失败错误信息1.73.0
errCodenumber接口调用失败错误码,详见错误码1.73.0

错误码

errCodeerrNoerrMsg说明
1001暂时未加no permission没有权限(白名单配置,暂无需关注)
100220000invalid params参数不合法
100320000template counts out of max bounds模版消息个数超过限制(最多 3 个)
100421101template not exist or invalid模版消息不存在或不合法
100521102template type not the same模版消息类型不一致
200121103network error网络问题
200221104service error服务错误
300121105auth deny拒绝授权
300221106login deny拒绝登录
400121107request count out of limit请求次数超过限制 (二期弹窗频控取消,不会再出现)
400221108main switch off总开关关闭
400321109templates switches all off请求模版消息开关均关闭
400421110forbidden后台封禁
暂时未加暂时未加not supported by current application宿主不支持(目前仅支持头条、抖音)
500110401Internal error: ${附加信息}内部错误

扫码体验

注意:该 demo 中的模版为「头条订阅模板」,请用 今日头条 扫码体验,如需体验其他模版,可参考 订阅消息功能-使用说明

请使用字节宿主APP扫码

代码示例

开发者工具中预览

<!-- index.ttml -->
<button type="primary" bindtap="subscribeMessage">订阅消息</button>
// index.js
Page({
  subscribeMessage() {
    tt.requestSubscribeMessage({
      tmplIds: [], // 需要填入开放平台申请的模版id,支持最多3个同类型模版
      success(res) {
        //订阅成功
        console.log("订阅成功", res);
      },
      fail(error) {
        //订阅失败
        console.log("订阅失败, 错误详情: ", error);
        tt.showToast({
          title: "订阅失败",
          icon: "fail",
        });
      },
      complete(res) {
        //订阅完成
        console.log("tt.requestSubscribeMessage API调用完成: ", res);
      },
    });
  },
});

Bug & Tip

  • Tip:只允许在以下时机中调用:bindtap 事件、支付回调函数。
  • Tip:最多一次可以传入三个模版 ID。
  • Tip:模版分为一次性模版和长期性模版,一次性模版 ID 和长期性模版 ID 不可同时使用。
点击纠错
评价此篇文档