小程序的订阅通知,可以极大提升用户的使用体验感,消息能力是小程序能力中的重要组成。
小程序的订阅通知权限申请会以卡片的形式从底部弹出,用户点击订阅消息按钮之后,微信会向开发者服务器推送消息。
消息类型
1. 一次性订阅消息
一次性订阅,相当于用户给使用的小程序门票,用户每约定一次,开发者就会有一次向用户发送消息的机会,开发者不可无限制的i向用户发送消息,每条消息可单独订阅或退订。
2. 长期订阅消息
一次性订阅消息可满足小程序的大部分服务场景需求,用户订阅一次后,开发者可长期下发多条消息。
目前长期性订阅消息仅向政务民生、医疗、交通、金融、教育等线下公共服务开放,后期将逐步支持到其他线下公共服务业务。
使用说明
1.获取模板id
在微信公众平台手动配置获取模板 ID:
登录 https://mp.weixin.qq.com 获取模板,如果没有合适的模板,可以申请添加新模板,审核通过后可使用。
2.获取下发权限
一次性订阅消息、长期订阅消息,详见接口 wx.requestSubscribeMessage
设备订阅消息,详见接口 wx.requestSubscribeDeviceMessage
3.调用接口下发订阅消息
一次性订阅消息、长期订阅消息,详见服务端接口 subscribeMessage.send,次数限制:开通支付能力的小程序下发上限是3kw/日,没开通的是1kw/日。
注意事项
-
用户勾选 “总是保持以上选择,不再询问” 之后,下次订阅调用 wx.requestSubscribeMessage 不会弹窗,保持之前的选择,修改选择需要打开小程序设置进行修改。
订阅消息事件推送
1、当用户触发订阅消息弹框后,用户的相关行为事件结果会推送至开发者所配置的服务器地址或微信云托管服务。
XML格式示例
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969440</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_popup_event]]></Event>
<SubscribeMsgPopupEvent>
<List>
<TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<SubscribeStatusString><![CDATA[accept]]></SubscribeStatusString>
<PopupScene>2</PopupScene>
</List>
<List>
<TemplateId><![CDATA[9nLIlbOQZC5Y89AZteFEux3WCXRRRG5Wfzkpssu4bLI]]></TemplateId>
<SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
<PopupScene>2</PopupScene>
</List>
</SubscribeMsgPopupEvent>
</xml>
JSON 格式示例
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
"CreateTime": "1620973045",
"MsgType": "event",
"Event": "subscribe_msg_popup_event",
"List": [ {
"TemplateId": "hD-ixGOhYmUfjOnI8MCzQMPshzGVeux_2vzyvQu7O68",
"SubscribeStatusString": "accept",
"PopupScene": "0"
}],
}
若 "List" 只有一个对象,则只返回对象本身;若 "List" 多于一个对象,则返回一个包含所有对象的数组。
参数说明
参数 | 说明 |
---|---|
ToUserName | 小程序帐号ID |
FromUserName | 用户openid |
CreateTime | 时间戳 |
TemplateId | 模板id(一次订阅可能有多个id) |
SubscribeStatusString | 订阅结果(accept接收;reject拒收) |
PopupScene | 弹框场景,0代表在小程序页面内,小程序外为空 |
MsgType | 消息类型 |
Event | 事件类型 |
参数处理
xml转map工具类
public static Map<String, String> xmlToMap(String xml) throws Exception {
Map<String, String> map = new HashMap<String, String>();
Document document = DocumentHelper.parseText(xml);
Element root = document.getRootElement();
List<Element> elements = root.elements();
for (Element element : elements) {
map.put(element.getName(), element.getText());
}
return map;
}
因为推送的是时间戳格式,转换成"yyyy-MM-dd:HH-mm-ss"格式
long timestamp = Long.parseLong(subscribeTimeStamp);//将时间戳转换为long类型
Date date = new Date(timestamp * 1000);//将时间戳转换为Date类型
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd:HH-mm-ss");//设置时间格式
String subscribeTime = sdf.format(date);//将时间戳转换为String类型
当用户在手机端服务通知里消息卡片右上角“...”管理消息时,相应的行为事件会推送至开发者所配置的服务器地址或微信云托管服务。(目前只推送取消订阅的事件,即对消息设置“拒收”)
XML 格式示例
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969440</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_change_event]]></Event>
<SubscribeMsgChangeEvent>
<List> <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<SubscribeStatusString><![CDATA[reject]]></SubscribeStatusString>
</List>
</SubscribeMsgChangeEvent>
</xml>
JSON 格式示例
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
"CreateTime": "1610968440",
"MsgType": "event",
"Event": "subscribe_msg_change_event",
"List": [ {
"TemplateId":"BEwX0BOT3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
"SubscribeStatusString": "reject"
}],
}
这里变换的只有SubscribeStatusString参数reject为拒收accept为接收
调用订阅消息接口发送消息给用户的最终结果,会推送下发结果事件至开发者所配置的服务器地址或微信云托管服务。
XML 格式示例
<xml>
<ToUserName><![CDATA[gh_123456789abc]]></ToUserName>
<FromUserName><![CDATA[otFpruAK8D-E6EfStSYonYSBZ8_4]]></FromUserName>
<CreateTime>1610969468</CreateTime>
<MsgType><![CDATA[event]]></MsgType>
<Event><![CDATA[subscribe_msg_sent_event]]></Event>
<SubscribeMsgSentEvent>
<List> <TemplateId><![CDATA[VRR0UEO9VJOLs0MHlU0OilqX6MVFDwH3_3gz3Oc0NIc]]></TemplateId>
<MsgID>1700827132819554304</MsgID>
<ErrorCode>0</ErrorCode>
<ErrorStatus><![CDATA[success]]></ErrorStatus>
</List>
</SubscribeMsgSentEvent>
</xml>
JSON 格式示例
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5PHRGBQYmeNyfG064wEFVpQ",
"CreateTime": "1620963428",
"MsgType": "event",
"Event": "subscribe_msg_sent_event",
"List": {
"TemplateId": "BEwX0BO-T3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
"MsgID": "1864323726461255680",
"ErrorCode": "0",
"ErrorStatus": "success"
}
}
"ErrorCode": "0" 表示成功