Web

本文介绍如何在 Web 应用中集成 Web Push 服务，实现网页推送通知功能。
前置条件
开通服务
登录 Chat 控制台 > App 推送 > 接入设置 开通 Push 服务，并获取 SDKAppID 和 AppKey，如图所示：
﻿
环境要求
运行环境： Node.js v12 版本及以上。
浏览器：需支持 Service Worker​ 和 Push API。主流要求为 Chrome 50+、Firefox 44+、Edge 17+​ 。
安全协议：生产环境必须使用 HTTPS。本地开发（ http://localhost）可使用。
浏览器支持
说明：
iframe、webview、浏览器隐私模式等特殊环境下，Web Push 不可用。
更多兼容性情况可在 浏览器兼容性查询工具 查询 Notification。
浏览器类型
浏览器最低版本要求
Chrome
50+
Edge
17+
Firefox
44+
Opera
25+
Safari
16+
集成步骤
步骤1：集成 @tencentcloud/web-push 
npm
yarn
npm install @tencentcloud/web-push --save
yarn add @tencentcloud/web-push
步骤2：配置 Service Worker 文件
集成 @tencentcloud/web-push 后，需要将 Service Worker（sw.js）复制到您项目的根目录。网站部署后，确保该文件可以通过 https://your-domain.com/sw.js 的路径被访问到。否则浏览器将无法注册 Service Worker。
说明：
sw.js 文件必须放在网站的根目录才能正常工作，这是浏览器的安全限制。
sw.js 只有在 HTTPS 连接（或本地开发环境 localhost）下才能被注册成功。请确保您的生产环境网站支持 HTTPS。
public 目录的作用：在现代前端项目（例如 Vue, React, Next.js 等）中，public 目录是一个特殊目录，它的内容在构建时不会被编译或改名。放置在 public 目录的文件会原封不动地被复制到网站的根目录。
注意：
将 sw.js 放在 src 或其他目录，它可能会被打包工具（Webpack/Vite）编译、改名（例如变成 sw.123abcde.js），从而无法被正确注册。
如果您的项目没有 public 目录（例如老式 HTML 项目），请直接将 sw.js 放在 index.html 所在的同级目录下，确保构建输出后位于根目录即可。
macOS
Windows
cp node_modules/@tencentcloud/web-push/dist/sw.js public/sw.js
copy node_modules\@tencentcloud\web-push\dist\sw.js public\sw.js
步骤3：注册推送
在您的主页面（例如：index.js）中，引入 @tencentcloud/web-push 并注册。
参数
类型
说明
SDKAppID
Number
推送服务 Push 的 SDKAppID。参考：前置条件 > 开通服务 获取  SDKAppID。
appKey
String
推送服务 Push 的客户端密钥。参考：前置条件 > 开通服务 获取  AppKey。
userID
String
注册推送用户的 userID。用户的唯一标识符，由您定义，只能包含大小写字母（a-z，A-Z）、数字（0-9）、下划线和连字符。
import WebPush from '@tencentcloud/web-push';
﻿
const SDKAppID = 0; // 您的 SDKAppID
const appKey = ''; // 客户端密钥
const userID = ''; // 用户 ID
// 注册推送服务
WebPush.registerPush({ SDKAppID, appKey, userID }).then((data) => {
    console.log('registerPush ok', data);
});
﻿
// 监听推送消息
WebPush.addPushListener(WebPush.EVENT.MESSAGE_RECEIVED, (message) => {
  console.log('收到推送消息:', message);
});
﻿
// 监听通知点击
WebPush.addPushListener(WebPush.EVENT.NOTIFICATION_CLICKED, (data) => {
  console.log('通知被点击:', data);
});
步骤4：测试推送功能
测试推送前，请按照下列步骤操作：
1. 打开浏览器控制台，检查是否有registerPush ok。
2. 通过 服务端 API > 单发推送 功能，发送您的第一条推送消息。
3. API 调用成功后（通常返回成功的状态码），请查看设备通知栏是否正常收到通知。
成功接收到的推送通知如下图所示：
﻿
推送结果回调
开启推送服务后，推送结果会以回调的方式，将结果转发给后台，详见：
﻿全员/标签/单发推送回调﻿
﻿其它推送回调﻿
常见问题
推送接收失败排查
1. 确认通知权限已开启。
操作系统允许浏览器发送通知。
macOS：系统偏好设置 > 通知，开启对应浏览器的通知权限。
Windows：设置 > 隐私 > 通知，开启对应浏览器的通知权限。
在浏览器中允许网站发送通知。
﻿
2. 确认网站是通过 https 访问（本地 localhost 除外）。
生产环境： https://
本地开发： http://localhost
3. 确认 sw.js 配置成功。
本地环境：启动您的项目后，在浏览器中访问 http://localhost:端口号/sw.js。如果能看到 JavaScript 代码，代表配置成功。
生产环境：在浏览器中访问 https://your-domain.com/sw.js， 如果能看到 JavaScript 代码，代表配置成功。
4. 确认浏览器是否支持 WebPush。参考：前置条件 > 浏览器支持。
5. 确认浏览器环境可以正常访问国际网络。
6. 利用推送服务提供的 推送排查工具，详细诊断发送状态和可能失败的原因。
registerPush 报错：“error: {"message": invalid webpush domain, "code": 70109} ” 问题排查
生产环境：网站的主域名与 控制台 配置的域名不一致。 
本地环境：网站的域名不是 http://localhost。
浏览器类型	浏览器最低版本要求
Chrome	50+
Edge	17+
Firefox	44+
Opera	25+
Safari	16+
参数	类型	说明
SDKAppID	Number	推送服务 Push 的 SDKAppID。参考：前置条件 > 开通服务获取 SDKAppID。
appKey	String	推送服务 Push 的客户端密钥。参考：前置条件 > 开通服务获取 AppKey。
userID	String	注册推送用户的 userID。用户的唯一标识符，由您定义，只能包含大小写字母（a-z，A-Z）、数字（0-9）、下划线和连字符。