产品动态
公告
Web
本文介绍如何在 Web 应用中集成 Web Push 服务，实现网页推送通知功能。
前置条件
开通服务
环境要求
运行环境： Node.js v12 版本及以上。
浏览器：需支持 Service Worker 和 Push API。主流要求为 Chrome 50+、Firefox 44+、Edge 17+ 。
安全协议：生产环境必须使用 HTTPS。本地开发（
http://localhost）可使用。浏览器支持
浏览器类型 | 浏览器最低版本要求 |
Chrome | 50+ |
Edge | 17+ |
Firefox | 44+ |
Opera | 25+ |
Safari | 16+ |
集成步骤
步骤1：集成 @tencentcloud/web-push
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 所在的同级目录下，确保构建输出后位于根目录即可。
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 | |
appKey | String | |
userID | String | 注册推送用户的 userID。用户的唯一标识符，由您定义，只能包含大小写字母（a-z，A-Z）、数字（0-9）、下划线和连字符。 |
import WebPush from '@tencentcloud/web-push';const SDKAppID = 0; // 您的 SDKAppIDconst 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://localhost3. 确认 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。文档反馈