@tencentcloud/web-push 1.0.1 → 1.0.3

package/README.md

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

@@ -0,0 +1,259 @@
+export declare interface CustomMessage {
+    id: string;
+    MsgType: 'custom';
+    MsgContent: {
+        Data: string | object;
+    };
+    Ext?: string;
+}
+
+export declare enum EVENT {
+    MESSAGE_RECEIVED = "message_received",
+    MESSAGE_REVOKED = "message_revoked",
+    NOTIFICATION_CLICKED = "notification_clicked",
+    CUSTOM_MESSAGE_RECEIVED = "custom_message_received"
+}
+
+export declare interface EventResult {
+    data: MessageReceivedResult | MessageRevokedResult | MessageNotificationClickedResult;
+}
+
+export declare interface HtmlMessage {
+    id: string;
+    MsgType: 'html';
+    MsgContent: {
+        Placement?: Placement;
+        Duration?: number;
+        Html: string;
+    };
+    Ext?: string;
+}
+
+export declare type LogLevel = 0 | 1 | 2 | 3 | 4;
+
+export declare interface MessageNotificationClickedResult {
+    ext: String;
+}
+
+export declare class MessagePopup {
+    private container;
+    private popups;
+    private timers;
+    private messageHandlers;
+    private animationTimers;
+    private adjustHeightTimers;
+    private config;
+    private readonly defaultConfig;
+    constructor(config?: PopupConfig);
+    private init;
+    private createContainer;
+    private injectStyles;
+    show(message: StandardMessage | HtmlMessage): void;
+    private createStandardPopup;
+    private createHtmlPopup;
+    private addPopup;
+    private removeOldestPopup;
+    close(messageId: string): void;
+    /**
+     * 检查指定消息是否正在显示弹窗
+     * @param messageId 消息ID
+     * @returns 是否正在显示
+     */
+    hasMessage(messageId: string): boolean;
+    closeAll(): void;
+    updateConfig(newConfig: Partial<PopupConfig>): void;
+    destroy(): void;
+    /**
+     * 根据 Placement 值应用容器位置
+     * 0-中间，1-左上，2-上中，3-右上，4-右中，5-右下，6-下中，7-左下，8-左中
+     */
+    private applyPlacement;
+    /**
+     * 调整iframe高度以适应内容
+     */
+    private adjustIframeHeight;
+    /**
+     * 创建iframe的完整HTML文档
+     */
+    private createIframeHtml;
+}
+
+export declare interface MessageReceivedData {
+    content: string;
+    info: WebPushInfo;
+    extension: WebPushExt;
+}
+
+export declare interface MessageReceivedResult {
+    message: PushMessage | NotificationMessage;
+}
+
+export declare interface MessageRevokedResult {
+    messageID: String;
+}
+
+export declare interface NotificationMessage {
+    messageID: string;
+    title: string;
+    body: string;
+    icon?: string;
+    tag?: string;
+    data?: any;
+    timestamp: number;
+}
+
+export declare enum Placement {
+    CENTER = 0,// 中间
+    TOP_LEFT = 1,// 左上
+    TOP_CENTER = 2,// 上中
+    TOP_RIGHT = 3,// 右上
+    MIDDLE_RIGHT = 4,// 右中
+    BOTTOM_RIGHT = 5,// 右下
+    BOTTOM_CENTER = 6,// 下中
+    BOTTOM_LEFT = 7,// 左下
+    MIDDLE_LEFT = 8
+}
+
+declare interface PopupConfig {
+    /** 是否启用弹窗 */
+    enabled?: boolean;
+    /** 弹窗显示时长（毫秒），0 表示不自动关闭 */
+    duration?: number;
+    /** 弹窗位置 */
+    position?: 'center' | 'top-left' | 'top-center' | 'top-right' | 'right-center' | 'bottom-right' | 'bottom-center' | 'bottom-left' | 'left-center';
+    /** 最大显示数量 */
+    maxCount?: number;
+    /** 是否显示关闭按钮 */
+    showCloseButton?: boolean;
+    /** 是否允许点击弹窗 */
+    clickable?: boolean;
+    /** 自定义渲染函数 */
+    customRender?: (message: any, container: HTMLElement) => HTMLElement;
+    /** 点击回调 */
+    onClick?: (message: any, popup: HTMLElement) => void;
+    /** 关闭回调 */
+    onClose?: (message: any, popup: HTMLElement) => void;
+}
+
+export declare type PushMessage = StandardMessage | HtmlMessage | CustomMessage;
+
+export declare interface RegisterPushOptions {
+    SDKAppID: number;
+    appKey: string;
+    userID: string;
+    serviceWorkerPath?: string;
+    chat?: any;
+    /**
+     * 日志级别：
+     * 0 - 普通级别，日志量较多，接入时建议使用
+     * 1 - release级别，SDK 输出关键信息，生产环境时建议使用（默认）
+     * 2 - 告警级别，SDK 只输出告警和错误级别的日志
+     * 3 - 错误级别，SDK 只输出错误级别的日志
+     * 4 - 无日志级别，SDK 将不打印任何日志
+     */
+    logLevel?: LogLevel;
+}
+
+export declare interface StandardMessage {
+    id: string;
+    MsgType: 'standard';
+    MsgContent: {
+        Text: {
+            Title: string;
+            Desc: string;
+        };
+        Image?: {
+            URL: string;
+            LinkURL: string;
+        };
+        Close: 0 | 1;
+        Placement?: Placement;
+        Duration?: number;
+        Button?: Array<{
+            Text: string;
+            Icon?: string;
+            Url: string;
+        }>;
+    };
+    Ext?: string;
+}
+
+declare const webPush: WebPushSDK_2;
+export default webPush;
+export { webPush }
+
+export declare interface WebPushExt {
+    WebpushReportUrl: string;
+    OnlineClickExt: string;
+    TaskId: string;
+}
+
+export declare interface WebPushInfo {
+    Title: string;
+    Desc: string;
+    Icon: string;
+    Image: string;
+    URL: string;
+}
+
+export declare interface WebPushSDK {
+    registerPush(options?: RegisterPushOptions): Promise<any>;
+    unRegisterPush(): Promise<any>;
+    addPushListener(eventName: EVENT, listener: (data: EventResult) => void): any;
+    removePushListener(eventName: EVENT, listener: (data: EventResult) => void): any;
+}
+
+declare class WebPushSDK_2 implements WebPushSDK {
+    static instance: WebPushSDK_2;
+    private eventEmitter;
+    private serviceWorkerManager;
+    private messagePopup;
+    private isRegistered;
+    private registrationID;
+    private chat;
+    private SDKAppID;
+    private appKey;
+    private vapidPublicKey;
+    private pendingMessages;
+    EVENT: typeof EVENT;
+    VERSION: string;
+    constructor();
+    static getInstance(): WebPushSDK_2;
+    registerPush(options?: RegisterPushOptions): Promise<string>;
+    unRegisterPush(): Promise<boolean>;
+    addPushListener(eventName: EVENT, listener: Function): string;
+    /**
+     * 内部方法：向 Service Worker 发送日志级别配置
+     * @param logLevel 日志级别 0-4
+     */
+    private sendLogLevelToServiceWorker;
+    removePushListener(eventName: EVENT, listener: Function): boolean;
+    private checkBrowserSupport;
+    private requestNotificationPermission;
+    private pushLogin;
+    private onMessageReceived;
+    private onMessageRevoked;
+    private addChatListener;
+    private removeChatListener;
+    private getSystemPermissionMessage;
+    private showSystemPermissionAlert;
+    private getBrowserInstType;
+    private setToken;
+    private initializeBrowserCompatibility;
+    private setupVisibilityChangeListener;
+    private setupInternalListeners;
+    private pushStatistics;
+    private clearState;
+    /**
+     * 向 service-worker 发送通知消息，使用与 push 事件相同的数据格式
+     * @param webpushInfo webpush 信息，格式与 SW push 事件接收的数据一致
+     */
+    private sendNotificationToServiceWorker;
+    /**
+     * 向 service-worker 发送消息撤回请求
+     * @param messageID 要撤回的消息ID
+     */
+    private sendMessageRevokeToServiceWorker;
+}
+
+export { }