文档概览/
Feedback

快速跑通

本文介绍如何在 Web 应用中集成 Web Push 服务，实现网页推送通知功能。
说明：
Web Push 不支持推送 Chat 消息。

前置条件

开通服务

登录 Chat 控制台 > Web 推送 > 概览，开通 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 调用成功后（通常返回成功的状态码），请查看设备通知栏是否正常收到通知。
成功接收到的推送通知如下图所示：


推送结果回调

开启推送服务后，推送结果会以回调的方式，将结果转发给后台，详见：
全员/标签/单发推送回调
其它推送回调