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
• 🔧 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

Step 1: Integrating @Tencentcloud/Web-Push

【npm】

npm install @tencentcloud/web-push --save

【yarn】

yarn add @tencentcloud/web-push

Step 2: Configure the Service Worker File

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】

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

【Windows】

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

Step 3: Register for Push Services

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

import WebPush from '@tencentcloud/web-push';

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

// Register for 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);
});

API Reference

Methods

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

Type Definitions

interface RegisterPushOptions {
  SDKAppID: number;
  appKey: string;
  userID: string;
  serviceWorkerPath?: string;
  chat?: any;
}

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

interface Message {
  ID: string;
  type:
    | 'TIMTextElem'
    | 'TIMImageElem'
    | 'TIMSoundElem'
    | 'TIMVideoFileElem'
    | 'TIMFileElem'
    | 'TIMCustomElem'
    | 'TIMRelayElem'
    | 'TIMLocationElem'
    | 'TIMFaceElem';
  payload: any;
  conversationID: string;
  conversationType: 'C2C' | 'GROUP';
  to: string;
  from: string;
  flow: string;
  time: number;
  status: string;
  isRevoked: boolean;
  nick: string;
  avatar: string;
  isPeerRead: boolean;
  nameCard: string;
  atUserList: string[];
  cloudCustomData: string;
  isDeleted: boolean;
  isModified: boolean;
  needReadReceipt: boolean;
  readReceiptInfo: any;
  isBroadcastMessage: boolean;
  isSupportExtension: boolean;
  receiverList?: string[];
  revoker: string;
  sequence: number;
  progress: number;
  revokerInfo: {
    userID: string;
    nick: string;
    avatar: string;
  };
  revokeReason: string;
  hasRiskContent: boolean;
}

interface MessageReceivedResult {
  message: Message;
}

interface MessageRevokedResult {
  messageID: string;
}

interface MessageNotificationClickedResult {
  ext: string;
}

interface EventResult {
  data:
    | MessageReceivedResult
    | MessageRevokedResult
    | MessageNotificationClickedResult;
}

Event Types

• MESSAGE_RECEIVED: Received a push message
• MESSAGE_REVOKED: Message was revoked
• NOTIFICATION_CLICKED: Notification was clicked

Important Notes

Service Worker Scope

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.

HTTPS Requirement

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

Browser Permissions

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

License

MIT License