@tencentcloud/web-push

v1.0.5

Published

9 days ago

Tencent Cloud Web Push SDK - Service Worker-based web push notification service

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

Step 1: Install Web Push SDK

Option 1: NPM Installation

npm install @tencentcloud/web-push --save

yarn add @tencentcloud/web-push

Option 2: CDN Integration (UMD)

Include directly via <script> tag:

<!-- Include TencentCloudChat SDK (Professional Edition) -->
<script src="https://unpkg.com/@tencentcloud/lite-chat/professional.js"></script>

<!-- Include Web Push SDK -->
<script src="https://unpkg.com/@tencentcloud/web-push/index.umd.js"></script>

<script>
  // SDK will be mounted to global variable WebPushSDK
  const webPush = WebPushSDK.webPush;

  // Usage is the same as ES6 modules
  webPush.registerPush({
    SDKAppID: 0,
    appKey: '',
    userID: '',
  });
</script>

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 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);
});

UMD Usage (Script Tag)

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:

<!DOCTYPE html>
<html>
  <head>
    <title>Web Push SDK UMD Example</title>
  </head>
  <body>
    <!-- Include TencentCloudChat SDK (Professional Edition) -->
    <script src="https://unpkg.com/@tencentcloud/lite-chat/professional.js"></script>

    <!-- Include Web Push SDK -->
    <script src="https://unpkg.com/@tencentcloud/web-push/index.umd.js"></script>

    <script>
      // Get SDK instance
      const webPush = WebPushSDK.webPush;

      // Configuration parameters
      const SDKAppID = 0; // Your SDKAppID
      const appKey = ''; // Client key
      const userID = ''; // User ID

      // Register push service
      webPush
        .registerPush({ SDKAppID, appKey, userID })
        .then((registrationID) => {
          console.log('Registration successful:', registrationID);
        })
        .catch((error) => {
          console.error('Registration failed:', error);
        });

      // 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);
      });
    </script>
  </body>
</html>

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;
  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',
}

Event Types

MESSAGE_RECEIVED: Received a push message (including all types: standard, html, custom)
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