集成指南 - Uniapp推送
开源示例Demo
集成SDK与初始化
初始化GoEasy允许通知栏提醒
建议在main.js
里将goeasy对象初始化为Uniapp全局对象。allowNotification:true
表示需要支持接收通知栏提醒,该参数仅在Uni-app开发的App下有效,小程序和H5网页下会被自动忽略,不会报错。
Vue.prototype.goeasy = GoEasy.getInstance({
host: "hangzhou.goeasy.io", //若是新加坡区域:singapore.goeasy.io
appkey: "您的common key",
modules: ['pubsub'],//根据需要,传入‘pubsub’或'im’,或数组方式同时传入
allowNotification: true, // true表示支持通知栏提醒,false则表示不需要通知栏提醒
});
建立连接
APP在接收和发送消息之前,必须要先连接GoEasy,一个app中需要,且只需要
建立一个连接即可,在成功断开连接之前,不需要,也不能
反复建立连接。
this.goeasy.connect({
onSuccess: function () { //连接成功
console.log("GoEasy connect successfully.") //连接成功
},
onFailed: function (error) { //连接失败
console.log("Failed to connect GoEasy, code:" + error.code + ",error:" + error.content);
},
onProgress: function (attempts) { //连接或自动重连中
console.log("GoEasy is connecting", attempts);
}
});
订阅(接收)消息
GoEasy 采用 发布/订阅 模式, 帮助开发者能最简单的实现向单个用户、批量用户推送通知栏提醒。
在发送消息之前,APP接收端必须完成消息的订阅,否则无法接收通知栏提醒。
成功订阅后,如果发送的消息含有通知栏信息,将会按照如下规则触发:
- app在前台运行,当收到新消息时,会触发onMessage方法,但不会收到通知栏提醒。
- app在后台运行或进程被杀掉,app将会收到通知栏提醒,app拉起后,onMessage方法也会被触发。
channel从哪里来,如何创建,应该传入什么呢?
- 根据您的业务,channel可以为任意字符串,除了不能包含空格,和不建议使用中文外,没有任何限制,只需要接收端订阅和消息的发送端的channel,就可以收到提醒。
- 发送给单个用户:将用户的唯一标识符(例如:id)作为channel,向这个channel发送即可
- 发送给多个用户:所有需要接收该提醒的用户订阅同一个channel即可, 例如:人事部门的所有成员订阅同一个channel: ‘channel_hr’,当往这个channel发送消息时,所有订阅的人事部门同事都会收到。
- 一个app可以订阅多个channel,可以任意定义,channel不需要创建,可随用随弃。
var pubsub = this.goeasy.pubsub;
pubsub.subscribe({
channel: "my_channel",
onMessage: function (message) {
console.log("Channel:" + message.channel + " content:" + message.content)
},
onSuccess: function () {
console.log("Subscribe successfully.")
},
onFailed: function () {
console.log("Subscribe successfully.")
}
});
客户端发送通知栏推送
当发送一条消息时,如果希望app在后台运行时,能够收到通知栏提醒,需要指定notification的title和body。
通知栏提醒,对发送端没有平台限制,不论是小程序、H5还是服务端均可以进行发送,但只有Uniapp开发的APP在手机端可以接收通知栏推送,其他平台收到消息后,仅触发subscribe的onMessage方法,notification会被自动忽略。
为了确保能收到通知栏提醒,必须在手机的系统设置里确认,该app的通知栏提醒为“允许”状态。
客户端javascript发送:
pubsub.publish({
channel: "my_channel", //请确认与接收端一致
message: "Hello GoEasy!", //app内onMessage收到的消息内容
notification: { //定义通知栏推送
title: '您有一条新消息', //通知栏提醒标题,仅显示于通知栏
body: "Hello GoEasy!", //通知栏提醒内容,仅显示于通知栏
},
onSuccess: function () {
console.log("Publish successfully.")
},
onFailed: function (error) {
console.log("Failed to publish message, code:" + error.code + ' error:' + error.content);
}
});
监听通知栏消息点击事件
用户点击通知栏消息,除了APP被自动拉起外,开发者还可以通过监听通知栏消息的点击事件,根据消息数据,执行相应的业务逻辑,比如跳转到不同的页面,或显示不同的内容。
为了避免在APP启动后,因为监听动作未完成而导致APP无法响应点击操作,确保APP总是可以第一时间响应通知栏消息的点击事件,请务必在main.js
GoEasy初始化后,立即监听onClickNotification事件。
//当用户点击通知栏消息触发,开发者可以根据消息数据,执行不同的业逻辑,比如跳转到不同的页面,或显示不同的内容
goeasy.onClickNotification((message) => {
// message
// {
// channel: "my_channel",
// content: "hello GoEasy!"
// }
console.log('Clicked notification message - ', message);
});
测试第一条通知栏推送
再次强调
为了确保能收到通知栏提醒,必须在手机的系统设置里确认,该app的通知栏提醒为“允许”状态。
至此,我们可以开始推送我们的第一条通知栏提醒,测试步骤:
- 将Uniapp应用安装到手机上
- 在手机系统设置里确认,该app的通知栏提醒为
“允许”
状态 - 将app切换到后台运行
- 运行Uniapp应用运行到浏览器,在浏览器里执行发送代码
- 恭喜,手机端收到通知栏提醒!
IM消息推送和提醒
请参阅IM消息推送和提醒
服务端发送通知栏推送
RESTful API
URL:
http(s)://rest-hz.goeasy.io/v2/pubsub/publish
Method:
Post
参数:
名称 | 必要 | 描述 |
---|---|---|
appkey | 是 | 您的appkey |
channel | 是 | channel |
content | 是 | 您要发送的消息内容 |
notification_title | 否 | 通知栏提醒的标题 |
notification_body | 否 | 通知栏提醒的内容 |
Uniapp通知栏提醒重要提示:
如果需要向Uniapp应用发送通知栏提醒,为了确保能收到通知栏提醒,必须在手机的系统设置里确认,该app的通知栏提醒为“允许”状态。
返回值:
{
"code" : 200,
"content" : "OK"
}
集成厂商通道
为了确保APP在进程被杀掉后,仍然可以收到通知栏提醒,必须要配置厂商通道,详情请参阅GoEasy接入厂商通道教程。 GoEasy目前已集成以下厂商,其他厂商也在持续推进中:
- 苹果iOS(APNs)
- 小米
- 华为
- OPPO
- VIVO
- 魅族