aegis-mp-rum-wrapper 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,82 @@
+## aegis-mp-rum-wrapper
+
+基于 `aegis-mp-sdk` 的小程序上报封装 SDK，用于在小程序中上报 RUM 日志，并在原有 Aegis 能力上增加一层业务侧埋点封装。
+
+### 安装
+
+```bash
+npm install aegis-mp-rum-wrapper aegis-mp-sdk --save
+```
+
+在小程序开发者工具中执行「构建 npm」，确保依赖可用。
+
+### 快速使用
+
+#### 1. 在小程序入口初始化用户信息
+
+```ts
+import { AegisW } from 'aegis-mp-rum-wrapper';
+
+// 初始化用户信息（示例）
+AegisW.user = {
+  openid: 'xxxx',
+  roleID: 'xxxx',
+  area: 1,
+  zone: 1,
+  channeldID: 100,       // 可选，SDK 会自动映射到 channelID
+  plat: 9,
+  serviceType: 'xxx',    // 必填
+  eventID: 'page_enter', // 必填
+  contentID: 'doc_001',
+  locale: 'zh',
+  accountType: 'wx',
+  channelUID: '600',
+  columnUID: '60055',
+  platName: 'PC',
+  ext1: '',
+  ext2: '',
+  ext3: '',
+};
+```
+
+当 `openid`、`serviceType`、`eventID` 三个字段均非空时，会自动初始化默认 Aegis 实例并开始上报。
+
+#### 2. 自定义事件上报
+
+```ts
+// 与 aegis-mp-sdk 保持一致，自定义事件填写 name 和 extX 字段
+AegisW.reportEvent({
+  name: 'vote',
+  ext1: '22',
+  ext2: '22',
+  ext3: '22',
+});
+```
+
+内部会自动把扩展业务日志打包成 JSON 串写入 `ext1`，并通过 Aegis 实例上报。
+
+### 高级用法
+
+如果需要更细粒度控制，可以使用函数式 API：
+
+```ts
+import {
+  configureWrapper,
+  setUser,
+  setRumID,
+  reportEvent,
+  getInstances,
+} from 'aegis-mp-rum-wrapper';
+```
+
+- `configureWrapper`：配置上报基础行为（如是否测速、延迟等）
+- `setUser`：更新用户信息，并在条件满足时初始化默认实例
+- `setRumID`：设置服务侧 RUM ID 并初始化服务实例
+- `reportEvent`：事件上报（与 `AegisW.reportEvent` 等价）
+- `getInstances`：获取底层 `defaultAegis` / `serviceAegis` 实例
+
+### 许可证
+
+MIT
+
+

package/dist/index.js

@@ -21,8 +21,8 @@ exports.setRumID = setRumID;
 exports.reportEvent = reportEvent;
 exports.getInstances = getInstances;
 var aegis_mp_sdk_1 = __importDefault(require("aegis-mp-sdk"));
-// rum id
-exports.GPPRumID = 'zYpo1fz400Vk86JR5Z'; // cn services
+// RUM 上报 ID（默认使用国服服务）
+exports.GPPRumID = 'zYpo1fz400Vk86JR5Z';
 var logItemTemplate = {
     report_type: 11,
     event_id: '',
@@ -66,7 +66,7 @@ var logItemTemplate = {
     content_id: '',
     source: 'fe_rum',
 };
-// 內部狀態
+// 内部状态
 var defaultAegis;
 var serviceAegis;
 var internalState = {
@@ -81,6 +81,7 @@ var internalState = {
     rumID: '',
     ready: false,
 };
+// 构建一条上报日志 JSON 字符串（写入 ext1）
 function buildReportStr(params, isPV) {
     var _a, _b, _c, _d, _e;
     var logItem = __assign({}, logItemTemplate);
@@ -124,6 +125,7 @@ function buildReportStr(params, isPV) {
     logItem.log_ts = Math.floor(Date.now() / 1000);
     return JSON.stringify(logItem);
 }
+// 初始化 Aegis 实例（isDefault=true 为默认实例，false 为服务实例）
 function initAegis(isDefault) {
     var id = internalState.id;
     var apiSpeed = internalState.reportApiSpeed;
@@ -148,7 +150,7 @@ function initAegis(isDefault) {
             ext3: internalState.user.ext3,
         }, true);
     }
-    // 小程序環境直接使用構造函數
+    // 小程序环境直接使用构造函数
     if (typeof aegis_mp_sdk_1.default === 'function') {
         return new aegis_mp_sdk_1.default({
             id: id,
@@ -171,10 +173,10 @@ function initAegis(isDefault) {
             },
         });
     }
-    console.error('[Aegis Wrapper] 找不到 aegis-mp-sdk 構造函數，請確認依賴是否正確安裝和引用');
+    console.error('[Aegis Wrapper] 找不到 aegis-mp-sdk 构造函数，请确认依赖是否正确安装和引用');
     return undefined;
 }
-// 對外暴露的 API
+// 对外暴露的配置 API
 function configureWrapper(config) {
     if (config.id)
         internalState.id = config.id;
@@ -194,7 +196,7 @@ function configureWrapper(config) {
 function setUser(user) {
     var incoming = user;
     var nextUser = __assign(__assign({}, internalState.user), user);
-    // 兼容 channeldID（文檔示例裡的字段名）到 channelID
+    // 兼容 channeldID（文档示例里的字段名）到 channelID
     if (incoming.channeldID != null && nextUser.channelID == null) {
         nextUser.channelID = incoming.channeldID;
     }
@@ -208,29 +210,30 @@ function setUser(user) {
         if (!internalState.ready) {
             internalState.ready = true;
             defaultAegis = initAegis(true);
-            console.log('[Aegis Wrapper] default aegis ready');
+            console.log('[Aegis Wrapper] default aegis 已就绪');
         }
     }
     else {
-        console.log('[Aegis Wrapper] 初始化條件不足: 需要 openid / serviceType / eventID', u);
+        console.log('[Aegis Wrapper] 初始化条件不足：需要 openid / serviceType / eventID', u);
     }
 }
 function setRumID(rumID) {
     internalState.rumID = rumID;
     serviceAegis = initAegis(false);
-    console.log('[Aegis Wrapper] service aegis rumID 已設置');
+    console.log('[Aegis Wrapper] service aegis rumID 已设置');
 }
+// 事件上报入口：兼容字符串和对象参数
 function reportEvent(params) {
-    // 先調用服務實例（如果存在）
+    // 先调用服务实例（如果存在）
     if (serviceAegis && typeof serviceAegis.reportEvent === 'function') {
         serviceAegis.reportEvent(params);
     }
     if (!defaultAegis || typeof defaultAegis.reportEvent !== 'function') {
-        console.error('[Aegis Wrapper] default aegis 尚未準備就緒，請先調用 setUser 並補全必要字段');
+        console.error('[Aegis Wrapper] default aegis 尚未准备就绪，请先调用 setUser 并补全必要字段');
         return;
     }
     if (typeof params !== 'string' && typeof params !== 'object') {
-        console.error('[Aegis Wrapper] reportEvent 參數類型錯誤，應為 string 或 object');
+        console.error('[Aegis Wrapper] reportEvent 参数类型错误，应为 string 或 object');
         return;
     }
     if (typeof params === 'object' && params.name === undefined) {
@@ -241,7 +244,7 @@ function reportEvent(params) {
     payload.ext1 = buildReportStr(payload, false);
     defaultAegis.reportEvent(payload);
 }
-// 方便調試或高級用戶直接訪問實例
+// 方便调试或高级用户直接访问底层实例
 function getInstances() {
     return {
         defaultAegis: defaultAegis,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aegis-mp-rum-wrapper",
-  "version": "0.1.0",
-  "description": "基於 aegis-mp-sdk 的小程序上報封裝 SDK，支持雙實例與自定義 RUM 日誌構造。",
+  "version": "0.1.1",
+  "description": "基于 aegis-mp-sdk 的小程序上报封装 SDK，支持双实例与自定义 RUM 日志构造。",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/src/index.ts

@@ -1,9 +1,9 @@
 import AegisCtor from 'aegis-mp-sdk';
 
-// rum id
-export const GPPRumID = 'zYpo1fz400Vk86JR5Z'; // cn services
+// RUM 上报 ID（默认使用国服服务）
+export const GPPRumID = 'zYpo1fz400Vk86JR5Z';
 
-// 封裝的用戶信息結構
+// 封装的用户信息结构
 export interface AegisUserInfo {
   openid?: string;
   roleID?: string;
@@ -29,7 +29,7 @@ export interface AegisUserInfo {
 }
 
 export interface AegisMpWrapperConfig {
-  id?: string; // 默認使用 GPPRumID
+  id?: string; // 默认使用 GPPRumID
   uin?: string;
   reportApiSpeed?: boolean;
   reportAssetSpeed?: boolean;
@@ -38,7 +38,7 @@ export interface AegisMpWrapperConfig {
   delay?: number;
 }
 
-// log item template
+// 日志字段模板
 interface LogItem {
   report_type: number;
   event_id: string;
@@ -127,7 +127,7 @@ const logItemTemplate: LogItem = {
   source: 'fe_rum',
 };
 
-// 內部狀態
+// 内部状态
 let defaultAegis: any;
 let serviceAegis: any;
 
@@ -152,6 +152,7 @@ export interface ReportParams {
   [key: string]: any;
 }
 
+// 构建一条上报日志 JSON 字符串（写入 ext1）
 function buildReportStr(params: string | ReportParams, isPV: boolean): string {
   const logItem: LogItem = { ...logItemTemplate };
 
@@ -199,6 +200,7 @@ function buildReportStr(params: string | ReportParams, isPV: boolean): string {
   return JSON.stringify(logItem);
 }
 
+// 初始化 Aegis 实例（isDefault=true 为默认实例，false 为服务实例）
 function initAegis(isDefault: boolean): any | undefined {
   let id = internalState.id;
   let apiSpeed = internalState.reportApiSpeed;
@@ -229,7 +231,7 @@ function initAegis(isDefault: boolean): any | undefined {
     );
   }
 
-  // 小程序環境直接使用構造函數
+  // 小程序环境直接使用构造函数
   if (typeof AegisCtor === 'function') {
     return new (AegisCtor as any)({
       id,
@@ -253,11 +255,11 @@ function initAegis(isDefault: boolean): any | undefined {
     });
   }
 
-  console.error('[Aegis Wrapper] 找不到 aegis-mp-sdk 構造函數，請確認依賴是否正確安裝和引用');
+  console.error('[Aegis Wrapper] 找不到 aegis-mp-sdk 构造函数，请确认依赖是否正确安装和引用');
   return undefined;
 }
 
-// 對外暴露的 API
+// 对外暴露的配置 API
 export function configureWrapper(config: AegisMpWrapperConfig): void {
   if (config.id) internalState.id = config.id;
   if (typeof config.uin === 'string') internalState.uin = config.uin;
@@ -275,7 +277,7 @@ export function setUser(user: Partial<AegisUserInfo>): void {
     ...user,
   };
 
-  // 兼容 channeldID（文檔示例裡的字段名）到 channelID
+  // 兼容 channeldID（文档示例里的字段名）到 channelID
   if (incoming.channeldID != null && nextUser.channelID == null) {
     (nextUser as any).channelID = incoming.channeldID;
   }
@@ -292,32 +294,33 @@ export function setUser(user: Partial<AegisUserInfo>): void {
     if (!internalState.ready) {
       internalState.ready = true;
       defaultAegis = initAegis(true);
-      console.log('[Aegis Wrapper] default aegis ready');
+      console.log('[Aegis Wrapper] default aegis 已就绪');
     }
   } else {
-    console.log('[Aegis Wrapper] 初始化條件不足: 需要 openid / serviceType / eventID', u);
+    console.log('[Aegis Wrapper] 初始化条件不足：需要 openid / serviceType / eventID', u);
   }
 }
 
 export function setRumID(rumID: string): void {
   internalState.rumID = rumID;
   serviceAegis = initAegis(false);
-  console.log('[Aegis Wrapper] service aegis rumID 已設置');
+  console.log('[Aegis Wrapper] service aegis rumID 已设置');
 }
 
+// 事件上报入口：兼容字符串和对象参数
 export function reportEvent(params: string | ReportParams): void {
-  // 先調用服務實例（如果存在）
+  // 先调用服务实例（如果存在）
   if (serviceAegis && typeof (serviceAegis as any).reportEvent === 'function') {
     (serviceAegis as any).reportEvent(params as any);
   }
 
   if (!defaultAegis || typeof (defaultAegis as any).reportEvent !== 'function') {
-    console.error('[Aegis Wrapper] default aegis 尚未準備就緒，請先調用 setUser 並補全必要字段');
+    console.error('[Aegis Wrapper] default aegis 尚未准备就绪，请先调用 setUser 并补全必要字段');
     return;
   }
 
   if (typeof params !== 'string' && typeof params !== 'object') {
-    console.error('[Aegis Wrapper] reportEvent 參數類型錯誤，應為 string 或 object');
+    console.error('[Aegis Wrapper] reportEvent 参数类型错误，应为 string 或 object');
     return;
   }
 
@@ -331,7 +334,7 @@ export function reportEvent(params: string | ReportParams): void {
   (defaultAegis as any).reportEvent(payload);
 }
 
-// 方便調試或高級用戶直接訪問實例
+// 方便调试或高级用户直接访问底层实例
 export function getInstances() {
   return {
     defaultAegis,
@@ -339,7 +342,7 @@ export function getInstances() {
   };
 }
 
-// 物件式封裝，支持示例中的兩種用法：
+// 面向业务侧的简单封装对象，支持示例中的两种用法：
 // 1）AegisW.user = {...}
 // 2）AegisW.reportEvent({...})
 export interface AegisWrapperFacade {