@tencentcloud/web-push 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+## [1.0.5] - 2025-02-02
+
+### Added
+
+- Support for webpushInfo ext pass-through fields
+
+## [1.0.4] - 2025-01-27
+
+### Added
+
+- **Online Push Popup Feature**: Real-time in-app message popup display to enhance user experience
+- **Multiple Message Type Support**: Standard (standard template), HTML (custom HTML), Custom (fully customizable)
+- **Log Level Control**: Added `logLevel` parameter to registerPush, supporting 5 levels of log control
+
+## [1.0.2] - 2025-01-16
+
+- ✨ Added UMD build support for direct `<script>` tag integration
+- 📚 Enhanced UMD usage documentation and examples
+
+## [1.0.1] - 2025-12-19
+
+- Optimize subscription logic
+- Optimized state persistence logic, only persisting VAPID public key while resetting temporary states each session
+
+## [1.0.0] - 2025-12-17
+
+### Added
+
+- 🎉 Initial release
+- ✨ Service Worker-based push notification support
+- ✨ Complete TypeScript type definitions
+- ✨ Event-driven message handling mechanism
+- ✨ Built-in analytics functionality
+- ✨ Local state persistence
+- ✨ VAPID authentication support
+- ✨ Cross-platform push notification support
+
+### Features
+
+- 📱 Support for message received, notification clicked, and message revoked events
+- 🔧 Flexible device identifier management
+- 📊 Automatic message delivery and click rate statistics
+- 🎯 Seamless integration with Chat SDK
+- 💾 Automatic state recovery
+- 🔒 Secure push subscription management
+
+### API Interface
+
+- `registerPush()` - Register push service
+- `unRegisterPush()` - Unregister push service
+- `addPushListener()` - Add event listener
+- `removePushListener()` - Remove event listener
+
+### Browser Support
+
+- Chrome 50+
+- Firefox 44+
+- Safari 16+
+- Edge 17+
+
+### Development Tools
+
+- Vite build tool
+- TypeScript support
+- Jest unit testing
+- ESLint code linting
+- Complete example application

package/README.md

@@ -1,50 +1,58 @@
-# Web Push SDK
+# Tencent Cloud Web Push SDK
 
-基于 Web 技术栈的推送服务 SDK，核心使用 Service Worker、Push API 和 Notification API 实现网页推送功能。
+A web-based push notification SDK built on modern Web APIs including Service Worker, Push API, and Notification API.
 
-## 特性
+## Features
 
-- 🚀 基于现代 Web 标准 API
-- 📱 支持跨平台推送通知
-- 💬 **在线推送弹窗**：应用内消息实时弹窗显示
-- 🎨 **自定义弹窗样式**：支持位置、样式、行为全方位自定义
-- 🔧 TypeScript 支持
-- 📊 内置数据统计功能
-- 🎯 事件驱动架构
-- 💾 本地状态持久化
-- 🔒 安全的 VAPID 认证
+- 🚀 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
 
-### 方式一：NPM 安装
+### Step 1: Install Web Push SDK
+
+**Option 1: NPM Installation**
+
+```bash
+npm install @tencentcloud/web-push --save
+```
+
+or
 
 ```bash
-npm install @tencentcloud/web-push
+yarn add @tencentcloud/web-push
 ```
 
-### 方式二：CDN 引入（UMD）
+**Option 2: CDN Integration (UMD)**
 
-通过 `<script>` 标签直接引入使用：
+Include directly via `<script>` tag:
 
 ```html
-<!-- 引入 TencentCloudChat SDK (专业版) -->
+<!-- Include TencentCloudChat SDK (Professional Edition) -->
 <script src="https://unpkg.com/@tencentcloud/lite-chat/professional.js"></script>
 
-<!-- 引入 Web Push SDK -->
+<!-- Include Web Push SDK -->
 <script src="https://unpkg.com/@tencentcloud/web-push/index.umd.js"></script>
 
 <script>
-  // SDK 会自动挂载到全局变量 WebPushSDK
+  // SDK will be mounted to global variable WebPushSDK
   const webPush = WebPushSDK.webPush;
 
-  // 使用方式与 ES6 模块相同
+  // Usage is the same as ES6 modules
   webPush.registerPush({
     SDKAppID: 0,
     appKey: '',
@@ -53,23 +61,23 @@ npm install @tencentcloud/web-push
 </script>
 ```
 
-### 步骤2：配置 Service Worker 文件
+### Step 2: Configure the Service Worker File
 
-集成 `@tencentcloud/web-push` 后，需要将 **Service Worker（sw.js）**复制到您项目**的根目录**。网站部署后，确保该文件可以通过 `https://your-domain.com/sw.js` 的路径被访问到。否则浏览器将无法注册 **Service Worker**。
+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:**
 >
-> - sw.js 文件**必须放在网站的根目录**才能正常工作，这是浏览器的安全限制。
-> - sw.js 只有在 **HTTPS 连接（或本地开发环境 localhost）**下才能被注册成功。请确保您的生产环境网站支持 **HTTPS**。
+> - 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**.
 
-**public 目录的作用**：在现代前端项目（如 Vue, React, Next.js 等）中，**public 目录是一个特殊目录，它的内容在构建时不会被编译或改名**。放置在 public 目录的文件会原封不动地被复制到网站的根目录。
+**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:**
 >
-> - 将 sw.js 放在 src 或其他目录，它可能会被打包工具（Webpack/Vite）编译、改名（例如变成 sw.123abcde.js），从而无法被正确注册。
-> - 如果您的项目**没有 public 目录**（例如老式 HTML 项目），请直接将 **sw.js** 放在 **index.html** 所在的同级目录下，确保构建输出后位于根目录即可。
+> - 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】
+【macOS】
 
 ```bash
 cp node_modules/@tencentcloud/web-push/dist/sw.js public/sw.js
@@ -81,17 +89,17 @@ cp node_modules/@tencentcloud/web-push/dist/sw.js public/sw.js
 copy node_modules\@tencentcloud\web-push\dist\sw.js public\sw.js
 ```
 
-## 快速开始
+### Step 3: **Register for Push Services**
 
-在您的主页面（例如：`index.js`）中，引入 `@tencentcloud/web-push` 并注册。
+In your homepage (for example: `index.js`), add `@tencentcloud/web-push` and register.
 
 <table>
 <tr>
-<td rowspan="1" colSpan="1" >参数</td>
+<td rowspan="1" colSpan="1" >Parameter</td>
 
-<td rowspan="1" colSpan="1" >类型</td>
+<td rowspan="1" colSpan="1" >Type</td>
 
-<td rowspan="1" colSpan="1" >说明</td>
+<td rowspan="1" colSpan="1" >Description</td>
 </tr>
 
 <tr>
@@ -99,7 +107,7 @@ copy node_modules\@tencentcloud\web-push\dist\sw.js public\sw.js
 
 <td rowspan="1" colSpan="1" >Number</td>
 
-<td rowspan="1" colSpan="1" >推送服务 Push 的 SDKAppID。</td>
+<td rowspan="1" colSpan="1" >The SDKAppID for the push service Push. </td>
 </tr>
 
 <tr>
@@ -107,7 +115,7 @@ copy node_modules\@tencentcloud\web-push\dist\sw.js public\sw.js
 
 <td rowspan="1" colSpan="1" >String</td>
 
-<td rowspan="1" colSpan="1" >推送服务 Push 的客户端密钥。</td>
+<td rowspan="1" colSpan="1" >The client key for the push service Push.</td>
 </tr>
 
 <tr>
@@ -115,36 +123,36 @@ copy node_modules\@tencentcloud\web-push\dist\sw.js public\sw.js
 
 <td rowspan="1" colSpan="1" >String</td>
 
-<td rowspan="1" colSpan="1" >注册推送用户的 userID。用户的唯一标识符，由您定义，只能包含大小写字母（a-z，A-Z）、数字（0-9）、下划线和连字符。</td>
+<td rowspan="1" colSpan="1" >Register the userID for push services. User's Unique Identifier, defined by you, can only include uppercase and lowercase letters (a-z, A-Z), numbers (0-9), underscores, and hyphens.</td>
 </tr>
 </table>
 
 ```javascript
 import webPush from '@tencentcloud/web-push';
 
-const SDKAppID = 0; // 您的 SDKAppID
-const appKey = ''; // 客户端密钥
-const userID = ''; // 用户 ID
+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('收到推送消息:', message);
+  console.log('received push message:', message);
 });
 
-// 监听通知点击
+// Listen to notification click
 webPush.addPushListener(webPush.EVENT.NOTIFICATION_CLICKED, (data) => {
-  console.log('通知被点击:', data);
+  console.log('notification clicked:', data);
 });
 ```
 
-### UMD 方式（Script 标签）
+### UMD Usage (Script Tag)
 
-> **重要提示**: 使用 UMD 方式时，必须先引入 TencentCloudChat SDK (专业版)，否则会出现 "Cannot read properties of undefined (reading 'create')" 错误。
+> **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.
 
-如果您使用 UMD 方式引入，可以参考以下示例：
+If you're using UMD integration, here's an example:
 
 ```html
 <!DOCTYPE html>
@@ -153,57 +161,57 @@ webPush.addPushListener(webPush.EVENT.NOTIFICATION_CLICKED, (data) => {
     <title>Web Push SDK UMD Example</title>
   </head>
   <body>
-    <!-- 引入 TencentCloudChat SDK (专业版) -->
+    <!-- Include TencentCloudChat SDK (Professional Edition) -->
     <script src="https://unpkg.com/@tencentcloud/lite-chat/professional.js"></script>
 
-    <!-- 引入 Web Push SDK -->
+    <!-- Include Web Push SDK -->
     <script src="https://unpkg.com/@tencentcloud/web-push/index.umd.js"></script>
 
     <script>
-      // 获取 SDK 实例
+      // Get SDK instance
       const webPush = WebPushSDK.webPush;
 
-      // 配置参数
-      const SDKAppID = 0; // 您的 SDKAppID
-      const appKey = 'xxx'; // 客户端密钥
-      const userID = 'xxx'; // 用户 ID
+      // 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('注册成功:', registrationID);
+          console.log('Registration successful:', registrationID);
         })
         .catch((error) => {
-          console.error('注册失败:', error);
+          console.error('Registration failed:', error);
         });
 
-      // 监听推送消息
+      // Listen to push messages
       webPush.addPushListener(webPush.EVENT.MESSAGE_RECEIVED, (message) => {
-        console.log('收到推送消息:', message);
+        console.log('Received push message:', message);
       });
 
-      // 监听通知点击
+      // Listen to notification click
       webPush.addPushListener(webPush.EVENT.NOTIFICATION_CLICKED, (data) => {
-        console.log('通知被点击:', data);
+        console.log('Notification clicked:', data);
       });
     </script>
   </body>
 </html>
 ```
 
-## API 文档
+## API Reference
 
-### 接口说明
+### Methods
 
-| API                  | 参数                                                | 描述               |
-| -------------------- | --------------------------------------------------- | ------------------ |
-| `registerPush`       | `options: RegisterPushOptions`                      | 注册推送服务       |
-| `unRegisterPush`     | -                                                   | 反注册关闭推送服务 |
-| `addPushListener`    | `eventName: EVENT, listener: Function<EventResult>` | 添加推送监听器     |
-| `removePushListener` | `eventName: EVENT, listener: Function<EventResult>` | 移除推送监听器     |
+| 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
 
 ```typescript
 interface RegisterPushOptions {
@@ -212,12 +220,12 @@ interface RegisterPushOptions {
   userID: string;
   chat?: any;
   /**
-   * 日志级别：
-   * 0 - 普通级别，日志量较多，接入时建议使用
-   * 1 - release级别，SDK 输出关键信息，生产环境时建议使用（默认）
-   * 2 - 告警级别，SDK 只输出告警和错误级别的日志
-   * 3 - 错误级别，SDK 只输出错误级别的日志
-   * 4 - 无日志级别，SDK 将不打印任何日志
+   * 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;
 }
@@ -229,26 +237,26 @@ enum EVENT {
 }
 ```
 
-### 事件类型
+### Event Types
 
-- `MESSAGE_RECEIVED`: 接收到推送消息（包括所有类型：standard、html、custom）
-- `MESSAGE_REVOKED`: 消息被撤回
-- `NOTIFICATION_CLICKED`: 通知被点击
+- `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 作用域
+### Service Worker Scope
 
-Service Worker 必须放在网站根目录下（如 `/sw.js`），这样才能控制整个网站的推送消息。如果放在子目录下，将无法正常工作。
+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 要求
+### HTTPS Requirement
 
-Web Push API 要求网站必须使用 HTTPS 协议（本地开发环境的 localhost 除外）。
+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

package/{dist/index.esm.js → index.esm.js}

@@ -1,5 +1,5 @@
 import ChatSDK from "@tencentcloud/lite-chat/professional";
-const version = "1.0.3";
+const version = "1.0.5";
 var Placement = /* @__PURE__ */ ((Placement2) => {
   Placement2[Placement2["CENTER"] = 0] = "CENTER";
   Placement2[Placement2["TOP_LEFT"] = 1] = "TOP_LEFT";