实现离线推送

ZEGO 即时通讯（ZIM）支持离线推送消息的功能。例如在“单聊”或“群组聊天”时，如果您的网页被关闭，与 ZEGO 服务后台的长连接超时断开后，此时如果您已接入“离线推送”功能，ZEGO 后台会为目标用户发送离线推送的消息。

开发者可以通过集成 ZPNs SDK，与 ZIM SDK 搭配使用，实现离线推送功能。

注意

Web 平台离线推送，仅支持 Chrome 、Edge 和 Safari 浏览器。由于是基于 Google FCM 功能实现，国内访问可能受限，建议开发者搭建 VPN 使用。
Safari 浏览器有系统版本要求。PC 端：macOS 13 或更高版本的 Safari 16；移动端：iOS 16.4 或更高版本，并且需要将 Web 网站转为 PWA 后，添加到主屏幕。
Web 平台的 ZPNs SDK 需要搭配 ZIM SDK 2.3.0 或以上版本使用。

方案介绍

ZIM 实现离线推送的方案如下：

首先消息接收方（即接收离线消息的用户），开启 Google 推送通道，向 Google 推送服务器发送请求，获取 Token。
Google 推送服务器，将 Token 返回给接收方。
接收方生成 PushID，并向 ZIM 服务器发送请求，绑定用户与 PushID 的关系。

开发者需要将 ZPNs SDK 与 ZIM SDK 搭配使用，SDK 内部会自动绑定用户与 PushID 的关系，无需特殊处理。请注意，同一设备切换 userID 前，请调用 zim.logout 接口，该接口会清除 userID 绑定的 PushID。
发送方开始发送消息，消息存储到 ZIM 服务器。
ZIM 服务器会确认接收方的客户端是否在线。
如果接收方的客户端不在线，ZIM 服务器会将消息转发给 ZPNs 服务器。
ZPNs 服务器将离线消息转发给 Google 的推送服务器。
Google 的服务器将消息通过“离线推送”的方式，推送给接收方；接收方登录后（至少登录一次），即可收到离线消息。

实现流程

接入 Google 离线推送通道

请参考 Web 推送集成指南，接入 Google 离线推送通道。

集成 ZPNs SDK

请参考 ZPNs SDK，下载最新版本的 ZPNs SDK。
将 SDK 包解压至项目目录下，例如 “zego-zpns-web”。
添加 SDK 引用。
1. 编辑项目的 “index.html” 文件，添加如下代码。
```
<script src="./zego-zpns-web/index.js"></script>
```
```
<script src="./zego-zpns-web/index.js"></script>
```
1. 将 “zego-zpns-web/firebase-messaging-sw.js” 文件，拷贝到项目根目录。

注册离线推送

const appID = 0; // Your Application ID of ZEGO ZIM
ZIM.create({ appID: appID });
const zim = ZIM.getInstance();

const config = {
    // From firebaseConfig
    apiKey: '',
    authDomain: '',
    projectId: '',
    storageBucket: '',
    messagingSenderId: '',
    appId: '',
    measurementId: '',

    // From Web Push certificates
    vapidKey: '',
}

// Safari 浏览器要求：ZPNs 注册接口（接口内部有调用 Notification.requestPermission）需要由用户触发
// 此行代码需要执行在用户点击事件或手势事件里
<button onclick="login()">login</button>
function login() {
    ZPNs.getInstance().register(config, zim);
}

const appID = 0; // Your Application ID of ZEGO ZIM
ZIM.create({ appID: appID });
const zim = ZIM.getInstance();

const config = {
    // From firebaseConfig
    apiKey: '',
    authDomain: '',
    projectId: '',
    storageBucket: '',
    messagingSenderId: '',
    appId: '',
    measurementId: '',

    // From Web Push certificates
    vapidKey: '',
}

// Safari 浏览器要求：ZPNs 注册接口（接口内部有调用 Notification.requestPermission）需要由用户触发
// 此行代码需要执行在用户点击事件或手势事件里
<button onclick="login()">login</button>
function login() {
    ZPNs.getInstance().register(config, zim);
}

注销离线推送

若开发者希望某台设备不再接收离线推送，可通过调用 unregister 接口注销。注销后用户将不再能收到推送消息。

ZPNs.getInstance().unregister();

ZPNs.getInstance().unregister();

iOS Safari 将 Web 网站转为 PWA

在项目根目录（index.html目录）为 Web 网站添加 manifest.json 文件，并设置 display 为 standalone

// manifest.json 内容参考
{
    "name": "ZPNs-PWA",
    "short_name": "ZPNs-PWA",
    "start_url": "/index.html",
    "scope": "./",
    "display": "standalone",
    "background_color": "#ffffff",
    "theme_color": "#000000",
    "description": "ZPNs-PWA"
}

// manifest.json 内容参考
{
    "name": "ZPNs-PWA",
    "short_name": "ZPNs-PWA",
    "start_url": "/index.html",
    "scope": "./",
    "display": "standalone",
    "background_color": "#ffffff",
    "theme_color": "#000000",
    "description": "ZPNs-PWA"
}

Safari 访问 Web 网站后，点击底部工具栏“分享按钮”，滑动后找到“添加到主屏幕”选项，点击添加。
添加到主屏幕后，在屏幕找到该应用并打开。首次打开应用会弹出通知权限，请务必点击确认权限。

获取 payload 透传字段

离线推送发送端通过配置 ZIMPushConfig的 payload 参数（2.5.0 之前版本为 extendedData 参数）向接收端发送额外信息，接收端需使用 ZPNs SDK 时，通过厂商通道的 extras 里面的 payload 字段获取该信息。

从下载获取 2.5.0 或以上版本的 ZPNs SDK，将其中的 firebase-messaging-sw.js 文件，拷贝到您的项目的根目录。
打开 firebase-messaging-sw.js 文件，按需重写以下方法后保存。

self.onNotificationArrived = (message) => {
    // 获取 payload 字段
    console.log(message.extra ? message.extra.payload : message.extra);
}
self.onNotificationClicked = (message) => {
    // 获取 payload 字段
    console.log(message.extra ? message.extra.payload : message.extra);
}

self.onNotificationArrived = (message) => {
    // 获取 payload 字段
    console.log(message.extra ? message.extra.payload : message.extra);
}
self.onNotificationClicked = (message) => {
    // 获取 payload 字段
    console.log(message.extra ? message.extra.payload : message.extra);
}

使用 ZIM SDK 实现离线推送

请参考使用 ZIM SDK 实现离线推送。

在线调试

集成 ZPNs SDK 和获取 Push ID 后，您可以在 ZEGO 控制台在线调试 ZIM 离线推送功能，详情请参考控制台的 ZIM 离线推送调试。

说明

如需在厂商控制台自行调试离线推送功能，需先获取对应厂商的推送 Token，Token 可以从各厂商官方开发者控制台 / 平台获取，也可使用 ZIM 离线推送调试获取厂商 Token。