# 订阅消息（选接）

基于微信的通知渠道，微信小游戏为开发者提供了可以高效触达用户的订阅消息能力，以便实现服务的闭环并提供更佳的体验。开发者在游戏内，可向用户发起消息订阅。开发者需后台自行记录用户是否订阅成功及订阅成功的次数。

用户在小游戏中订阅指定的消息内容后，开发者可以在后台通过下发消息服务把一条模版消息发送给用户，用户最终在微信的“服务通知”中收到。开发者可通过场景值（1014）区分从模版消息进入游戏的用户。

用户成功订阅一次，开发者可在游戏认为场景合适的时机，向该用户发下一条模版消息。

# 一次性订阅消息

# 订阅和发送流程图

# 接口说明

用于在游戏内打开一次性订阅消息界面，返回用户订阅消息的操作结果；若用户勾选了订阅面板中的 总是保持以上选择，不再询问，模板消息会被添加到用户的游戏设置页，可通过 sdkInstance.getSetting() 接口获取用户对相关模板消息的订阅状态；当用户成功订阅一次，开发者可在游戏认为场景合适的时机，向该用户下发一条模版消息（了解更多可查看小游戏订阅消息使用指引）。

特别提醒

游戏设置页内的操作，可以理解为是消息订阅开关且会清零订阅次数，如 体力满时 的订阅：
1、点击订阅按钮2次，当体力满时会消耗1次次数，再次满时再消耗1次，第三次满时推送不成功
2、点击订阅按钮2次，当体力满时会消耗1次次数，此时右上角关闭 体力满订阅 通知，体力再次满时推送不成功，因为次数被清零了
3、点击订阅按钮2次，当体力满时会消耗1次次数，此时右上角关闭 体力满订阅 通知，在体力满之前再次开启，当满时再次推送也不会成功

总结：当有订阅次数且该订阅状态开启时会推送成功，关闭次数清零，重新开启后需重新订阅。总之，研发不用管这些逻辑细节，按照下面 code 值去做对应的操作即可。

关于一次性订阅消息的推送配置，请阅读SDK开放平台操作指南 > 订阅配置 (opens new window)（2.1.1版本新增）。

sdkInstance.subscribeMessage(options);

最低基础库版本要求

若用户客户端基础库版本低于 2.4.4，调用 sdkInstance.subscribeMessage(options) 接口将中断用户当前操作并弹出升级提示，不会报错！

# 参数说明

参数说明如下表所示：

选项	类型	必填	默认值	说明
tmplIds	string[]	是	--	需要订阅的消息模板 `id` 集合，一次调用最多可订阅 `3` 条消息；可登录《微信公众平台》后台，进入“功能 > 订阅消息”栏目中配置及查看消息模板 `id`，每个 `tmplId` 对应的模板标题需要不同，否则会被过滤
success	function	否	--	订阅成功的回调函数
fail	function	否	--	订阅失败的回调函数
complete	function	否	--	订阅完成的回调函数，成功或失败均会调用

# 返回值说明

WARNING

返回值格式：JSON 格式。

选项	类型	说明
code	number/string	订阅状态码： - `0` 表示订阅成功 - `ban` 表示被微信临时性禁用，过几天会自动解除，可以提示 `该订阅功能暂时受限，请稍后再试` - `reject` 表示用户拒绝，需引导用户右上角开启 - `其他` 表示订阅失败
data	object	订阅成功时返回用户订阅消息的操作结果，失败时返回 `null`
data[TEMPLATE_ID]	string	[TEMPLATE_ID]是动态的键，即模板 `id`，值包括 `accept`、`reject`、`ban`、`filter`，其中 `accept` 表示用户同意订阅该条 `id` 对应的模板消息，`reject` 表示用户拒绝订阅该条 `id` 对应的模板消息，`ban` 表示已被后台封禁，`filter` 表示该条 `id` 对应的模板因为标题同名被后台过滤
message	string	订阅成功或失败时的相应描述信息

# 示例代码

注：示例代码中的参数或选项均为演示数据，仅供参考，谢谢！

// 若用户客户端基础库版本低于 2.4.4，调用此接口将中断用户当前操作并弹出升级提示，不会报错！
sdkInstance.subscribeMessage({
  tmplIds: ["iGVl1bT_JiQ82cafpXAxMurVMykQW5ScT7UbekFEhJQ"], // 一次调用最多可订阅3条消息
  success: function(response) {
    console.log(response.code); // 订阅状态码，0 表示订阅成功; ban 表示被微信临时性禁用; reject 表示用户拒绝; 其他表示订阅失败;
    console.log(response.data); // 用户订阅消息的操作结果
  },
  fail: function(error) {
    console.log(error); // 订阅失败的错误信息，error.message为错误消息
  },
  complete: function(result) {
    // do something here...
  }
});

# SDK后台配置

配置说明

此部分由运营人员配置，需要SDK开放平台管理后台权限。具体配置操作说明请查看 SDK开放平台操作指南 > 订阅配置

# 游戏触发模板消息推送

游戏推送

游戏触发的推送模板消息通过上报数据平台kafka，具体上报的数据格式请参考小游戏订阅消息推送业务：数据上报说明文档

# 系统订阅消息

# 接口说明

用于在游戏内打开系统订阅消息界面，返回用户订阅消息的操作结果；当用户订阅成功，且游戏内触发相应场景时，微信平台将向用户下发服务通知（订阅一次，永久生效），无需开发者控制下发逻辑（了解更多可查看小游戏系统订阅消息使用指引）。

微信小游戏系统订阅消息由微信官方进行推送，接入前建议阅读小游戏系统订阅消息使用指引 (opens new window)。

sdkInstance.subscribeSystemMessage(options);

最低基础库版本要求

若用户客户端基础库版本低于 2.9.4，调用 sdkInstance.subscribeSystemMessage(options) 接口将中断用户当前操作并弹出升级提示，不会报错！

若参数 msgTypeList 中包含 SYS_MSG_TYPE_WHATS_NEW，则要求用户客户端基础库版本不低于 2.32.1！

# 消息触发场景

场景1 好友互动

开发者在游戏内设置与微信好友赠送礼物、偷取道具等互动行为。当有用户成功触发互动行为时，若对方已订阅“好友互动提醒”，则对方会收到对应的服务通知；每次成功互动，下发一条消息。

每次调用 wx.modifyFriendInteractiveStorage 且用户确认互动后，会产生一条服务通知。接口参数 quiet 设置为 true 的接口调用，将不会触发服务通知。

场景2 排行榜超越

场景3 好友互动