Tencent Cloud Web Push SDK

A web-based push notification SDK built on modern Web APIs including Service Worker, Push API, and Notification API.

Features

- 🚀 Built on modern Web standard APIs
- 📱 Cross-platform push notification support
- 💬 Online Push Popup: Real-time in-app message popup display
- 🎨 Custom Popup Styles: Full customization support for position, styling, and behavior
- 🔧 TypeScript support
- 📊 Built-in analytics functionality
- 🎯 Event-driven architecture
- 💾 Local state persistence
- 🔒 Secure VAPID authentication

Browser Support

- Chrome 50+
- Firefox 44+
- Safari 16+
- Edge 17+

Integration Step

$3

Option 1: NPM Installation

``bash
npm install @tencentcloud/web-push --save
`

or

`bash
yarn add @tencentcloud/web-push
`

Option 2: CDN Integration (UMD)

Include directly via

`

$3

After integrating @tencentcloud/web-push, copy the Service Worker (sw.js) to your project's root directory. After website deployment, ensure this file can be accessed through https://your-domain.com/sw.js. Otherwise, the browser will be unable to register the Service Worker.

> Note:
>
> - The sw.js file must be placed in the website's root directory to work properly due to browser security restrictions.
> - The sw.js file can only be registered successfully under HTTPS connection (or local development environment localhost). Ensure your live production environment website supports HTTPS.

Role of the public directory: In modern front-end projects (such as Vue, React, Next.js, etc.), the public directory is a unique directory whose content will not be compiled or renamed during build. Files placed in the public directory will be copied to the website's root directory as-is.

> Note:
>
> - Place sw.js in the src or other directories, and it may be compiled or renamed (such as changed into sw.123abcde.js) by packaging tools (Webpack/Vite), thereby failing to register correctly.
> - If your project does not have a public directory (such as old-style HTML projects), place sw.js directly in the same directory as index.html to ensure it is located in the root directory after build output.

【macOS】

`bash
cp node_modules/@tencentcloud/web-push/dist/sw.js public/sw.js
`

【Windows】

`bash
copy node_modules\@tencentcloud\web-push\dist\sw.js public\sw.js
`

$3

In your homepage (for example: index.js), add @tencentcloud/web-push and register.

`javascript
import webPush from '@tencentcloud/web-push';

const SDKAppID = 0; // Your SDKAppID
const appKey = ''; // client key
const userID = ''; // user ID

// Register push service
await webPush.registerPush({ SDKAppID, appKey, userID });

// Listen to push messages
webPush.addPushListener(webPush.EVENT.MESSAGE_RECEIVED, (message) => {
console.log('received push message:', message);
});

// Listen to notification click
webPush.addPushListener(webPush.EVENT.NOTIFICATION_CLICKED, (data) => {
console.log('notification clicked:', data);
});
`

$3

> Important: When using UMD integration, you must include the TencentCloudChat SDK (Professional Edition) first, otherwise you'll encounter "Cannot read properties of undefined (reading 'create')" error.

If you're using UMD integration, here's an example:

`html












`

API Reference

$3

| API | Parameters | Description |
| -------------------- | --------------------------------------------------- | -------------------------- |
| registerPush | options: RegisterPushOptions | Register push service |
| unRegisterPush | - | Unregister push service |
| addPushListener | eventName: EVENT, listener: Function | Add push event listener |
| removePushListener | eventName: EVENT, listener: Function | Remove push event listener |

$3

`typescript
interface RegisterPushOptions {
SDKAppID: number;
appKey: string;
userID: string;
chat?: any;
/**
* Log level:
* 0 - Normal level, more logs, recommended for integration
* 1 - Release level, SDK outputs key information, recommended for production (default)
* 2 - Warning level, SDK only outputs warning and error level logs
* 3 - Error level, SDK only outputs error level logs
* 4 - No log level, SDK will not print any logs
*/
logLevel?: LogLevel;
}

enum EVENT {
MESSAGE_RECEIVED = 'message_received',
MESSAGE_REVOKED = 'message_revoked',
NOTIFICATION_CLICKED = 'notification_clicked',
}
`

$3

- MESSAGE_RECEIVED: Received a push message (including all types: standard, html, custom)
- MESSAGE_REVOKED: Message was revoked
- NOTIFICATION_CLICKED: Notification was clicked

Important Notes

$3

Service Workers must be placed in the website's root directory (e.g., /sw.js`) to control push messages across the entire website. Placing them in subdirectories will not function correctly.

$3

The Web Push API requires websites to use the HTTPS protocol (except for local development environments using localhost).

$3

Users need to authorize notification permissions upon first use. Please guide users to authorize permissions at appropriate times.

License

MIT License