@tencentcloud/web-push 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [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

package/README.md

@@ -6,6 +6,8 @@ A web-based push notification SDK built on modern Web APIs including Service Wor
 
 - 🚀 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
@@ -52,23 +54,13 @@ Include directly via `<script>` tag:
 
   // Usage is the same as ES6 modules
   webPush.registerPush({
-    SDKAppID: 1400000000,
-    appKey: 'your-app-key',
-    userID: 'test-user-001',
+    SDKAppID: 0,
+    appKey: '',
+    userID: '',
   });
 </script>
 ```
 
-Or download and use locally:
-
-```html
-<!-- Include Chat SDK -->
-<script src="./path/to/chat-sdk.js"></script>
-
-<!-- Include Web Push SDK -->
-<script src="./dist/index.umd.js"></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**.
@@ -136,22 +128,22 @@ In your homepage (for example: `index.js`), add `@tencentcloud/web-push` and reg
 </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
 
-// Register for push service
-await WebPush.registerPush({ SDKAppID, appKey, userID });
+// Register push service
+await webPush.registerPush({ SDKAppID, appKey, userID });
 
 // Listen to push messages
-WebPush.addPushListener(WebPush.EVENT.MESSAGE_RECEIVED, (message) => {
+webPush.addPushListener(webPush.EVENT.MESSAGE_RECEIVED, (message) => {
   console.log('received push message:', message);
 });
 
 // Listen to notification click
-WebPush.addPushListener(WebPush.EVENT.NOTIFICATION_CLICKED, (data) => {
+webPush.addPushListener(webPush.EVENT.NOTIFICATION_CLICKED, (data) => {
   console.log('notification clicked:', data);
 });
 ```
@@ -180,9 +172,9 @@ If you're using UMD integration, here's an example:
       const webPush = WebPushSDK.webPush;
 
       // Configuration parameters
-      const SDKAppID = 1400000000; // Your SDKAppID
-      const appKey = 'your-app-key'; // Client key
-      const userID = 'test-user-001'; // User ID
+      const SDKAppID = 0; // Your SDKAppID
+      const appKey = ''; // Client key
+      const userID = ''; // User ID
 
       // Register push service
       webPush
@@ -226,8 +218,16 @@ interface RegisterPushOptions {
   SDKAppID: number;
   appKey: string;
   userID: string;
-  serviceWorkerPath?: 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 {
@@ -235,76 +235,11 @@ 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_RECEIVED`: Received a push message (including all types: standard, html, custom)
 - `MESSAGE_REVOKED`: Message was revoked
 - `NOTIFICATION_CLICKED`: Notification was clicked
 

package/index.d.ts

@@ -1,74 +1,201 @@
+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"
+    NOTIFICATION_CLICKED = "notification_clicked",
+    CUSTOM_MESSAGE_RECEIVED = "custom_message_received"
 }
 
 export declare interface EventResult {
     data: MessageReceivedResult | MessageRevokedResult | MessageNotificationClickedResult;
 }
 
-export declare 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;
+export declare interface HtmlMessage {
+    id: string;
+    MsgType: 'html';
+    MsgContent: {
+        Placement?: Placement;
+        Duration?: number;
+        Html: string;
     };
-    revokeReason: String;
-    hasRiskContent: Boolean;
+    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: Message;
+    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>;
@@ -80,12 +207,14 @@ 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();
@@ -93,18 +222,38 @@ declare class WebPushSDK_2 implements WebPushSDK {
     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 chatLogin;
+    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 { }