@arms/rum-core 0.1.10 → 0.1.11

package/es/index.d.ts

@@ -5,6 +5,7 @@ import Shell from './model/shell';
 export * from './model/configManager';
 export * from './types/client';
 export * from './types/collector';
+export * from './types/event';
 export * from './types/processor';
 export * from './types/reporter';
 export * from './types/rum-event';

package/es/index.js

@@ -5,6 +5,7 @@ import Shell from './model/shell';
 export * from './model/configManager';
 export * from './types/client';
 export * from './types/collector';
+export * from './types/event';
 export * from './types/processor';
 export * from './types/reporter';
 export * from './types/rum-event';

package/es/model/shell.d.ts

@@ -1,6 +1,6 @@
 import { IClient, IConfiguration } from '../types/client';
 import { ICollector } from '../types/collector';
-import { RumCustomEvent, RumEvent, RumExceptionEvent, RumResourceEvent, RumViewEvent, SendEventOptions } from '../types/rum-event';
+import { loading_type, RumCustomEvent, RumEvent, RumExceptionEvent, RumResourceEvent, RumViewEvent, SendEventOptions } from '../types/rum-event';
 import { IShell } from '../types/shell';
 export default abstract class Shell implements IShell {
     client: IClient;
@@ -31,6 +31,26 @@ export default abstract class Shell implements IShell {
      */
     abstract init(configuration: IConfiguration): Promise<Shell> | Shell;
     sendEvent(payload: RumEvent, options?: SendEventOptions): void;
+    /**
+     * 手动开启一个新 view（手动 view 模式）。
+     *
+     * 与 PvCollector 自动 PV 的语义对齐：
+     * 1. 同名去重：与当前 view 名称相同时不创建新 view
+     * 2. emit VIEW_ENDED（结束上一 view）→ ctx.addView（写入新 view）
+     *    → emit VIEW_CREATED → 上报 view 事件
+     *
+     * url / referrer 属平台概念，由调用方经 options 传入（如 browser 传 location.href）。
+     * 事件基础字段（session_id / event_id / times / view）由 session.getBaseEvent 补齐，
+     * 与自动 PV 事件结构一致。
+     *
+     * @param name view 名称（如路由模板 `/user/:id`）
+     * @param options 可选字段：url / referrer / loading_type（默认 route_change）
+     */
+    startView(name: string, options?: {
+        url?: string;
+        referrer?: string;
+        loading_type?: loading_type;
+    }): void;
     /**
      * get config
      */
@@ -50,6 +70,9 @@ export default abstract class Shell implements IShell {
     sendView(payload: RumViewEvent): void;
     /**
      * 自定义异常上报
+     *
+     * @param payload 异常事件或 Error 对象。若为 RumExceptionEvent 且携带 source
+     *   字段（如 'react'），则使用该值；否则默认 'custom'。
      */
     sendException(payload: RumExceptionEvent | Error): void;
     /**

package/es/model/shell.js

@@ -1,5 +1,6 @@
 var _Shell;
 import { RumEventType } from '../types/rum-event';
+import { LifeCycleEventType } from '../types/event';
 import Client from '../model/client';
 import { isNumber, isObject } from '../utils/is';
 var Shell = /*#__PURE__*/function () {
@@ -90,6 +91,53 @@ var Shell = /*#__PURE__*/function () {
     }
   }
 
+  /**
+   * 手动开启一个新 view（手动 view 模式）。
+   *
+   * 与 PvCollector 自动 PV 的语义对齐：
+   * 1. 同名去重：与当前 view 名称相同时不创建新 view
+   * 2. emit VIEW_ENDED（结束上一 view）→ ctx.addView（写入新 view）
+   *    → emit VIEW_CREATED → 上报 view 事件
+   *
+   * url / referrer 属平台概念，由调用方经 options 传入（如 browser 传 location.href）。
+   * 事件基础字段（session_id / event_id / times / view）由 session.getBaseEvent 补齐，
+   * 与自动 PV 事件结构一致。
+   *
+   * @param name view 名称（如路由模板 `/user/:id`）
+   * @param options 可选字段：url / referrer / loading_type（默认 route_change）
+   */;
+  _proto.startView = function startView(name, options) {
+    if (!name) return;
+    var ctx = this.client.getContext();
+    if (!ctx || !ctx.session) return;
+    var views = ctx.getViews();
+    var prevView = views && views.length ? views[views.length - 1] : undefined;
+    // 同名去重：与当前 view 名称相同时不创建新 view
+    if (prevView && prevView.name === name) return;
+    if (prevView) {
+      ctx.emitter.emit(LifeCycleEventType.VIEW_ENDED, Object.assign({
+        type: 'pv'
+      }, prevView));
+    }
+    var view = {
+      id: ctx.session.getViewId(),
+      name: name,
+      loading_type: options && options.loading_type || 'route_change'
+    };
+    ctx.addView(view);
+    var base = ctx.session.getBaseEvent ? ctx.session.getBaseEvent() : {};
+    var viewEvent = Object.assign({}, base, {
+      event_type: RumEventType.VIEW,
+      type: 'pv',
+      name: name,
+      url: options && options.url,
+      referrer: options && options.referrer,
+      loading_type: view.loading_type
+    });
+    ctx.emitter.emit(LifeCycleEventType.VIEW_CREATED, viewEvent);
+    this.sendEvent(viewEvent);
+  }
+
   /**
    * get config
    */;
@@ -143,6 +191,9 @@ var Shell = /*#__PURE__*/function () {
 
   /**
    * 自定义异常上报
+   *
+   * @param payload 异常事件或 Error 对象。若为 RumExceptionEvent 且携带 source
+   *   字段（如 'react'），则使用该值；否则默认 'custom'。
    */;
   _proto.sendException = function sendException(payload) {
     if (!payload.name || !payload.message) {
@@ -151,6 +202,8 @@ var Shell = /*#__PURE__*/function () {
     var name = payload.name,
       message = payload.message,
       stack = payload.stack;
+    // 支持自定义 source（如 'react'），否则默认 'custom'
+    var source = payload.source || 'custom';
     var data = Object.assign({
       times: 1,
       name: name,
@@ -159,7 +212,7 @@ var Shell = /*#__PURE__*/function () {
     }, payload, {
       event_type: RumEventType.EXCEPTION,
       type: 'custom',
-      source: 'custom'
+      source: source
     });
     this.sendEvent(data);
   }

package/es/types/client.d.ts

@@ -150,6 +150,13 @@ export interface IConfiguration {
      * 是否开启SDK
      */
     enable?: boolean;
+    /**
+     * 手动 view 模式：开启后 SDK 不再自动采集 PV（PvCollector 跳过首屏 PV
+     * 与 history 拦截），view 生命周期由接入方通过 Shell.startView(name) 主动
+     * 控制，实现路由驱动的命名 + 计时 + 触发一体。
+     * @default false
+     */
+    trackViewsManually?: boolean;
     /**
      * 项目 id
      * v0.0.40开始，不强依赖该参数，通过Endpoint获取 service_id 确定应用

package/es/types/event.d.ts

@@ -0,0 +1,15 @@
+/**
+ * RUM 生命周期事件枚举。
+ *
+ * 由 view 生命周期驱动，采集器通过 IContext.emitter 订阅：
+ * - VIEW_CREATED：新 view 创建（首屏或路由切换），事件体为 view 事件
+ *   （含 type: 'pv'、name、loading_type 等字段）
+ * - VIEW_ENDED：上一 view 结束，事件体为 `{ type: 'pv', ...prevView }`
+ *
+ * 注：跨包使用场景（browser 等平台包从 core 导入），须保持为普通 enum：
+ * const enum 在 babel 转译链路下无法内联，跨包引用会产生运行时错误。
+ */
+export declare enum LifeCycleEventType {
+    VIEW_CREATED = "VIEW_CREATED",
+    VIEW_ENDED = "VIEW_ENDED"
+}

package/es/types/event.js

@@ -0,0 +1,16 @@
+/**
+ * RUM 生命周期事件枚举。
+ *
+ * 由 view 生命周期驱动，采集器通过 IContext.emitter 订阅：
+ * - VIEW_CREATED：新 view 创建（首屏或路由切换），事件体为 view 事件
+ *   （含 type: 'pv'、name、loading_type 等字段）
+ * - VIEW_ENDED：上一 view 结束，事件体为 `{ type: 'pv', ...prevView }`
+ *
+ * 注：跨包使用场景（browser 等平台包从 core 导入），须保持为普通 enum：
+ * const enum 在 babel 转译链路下无法内联，跨包引用会产生运行时错误。
+ */
+export var LifeCycleEventType = /*#__PURE__*/function (LifeCycleEventType) {
+  LifeCycleEventType["VIEW_CREATED"] = "VIEW_CREATED";
+  LifeCycleEventType["VIEW_ENDED"] = "VIEW_ENDED";
+  return LifeCycleEventType;
+}({});

package/lib/index.d.ts

@@ -5,6 +5,7 @@ import Shell from './model/shell';
 export * from './model/configManager';
 export * from './types/client';
 export * from './types/collector';
+export * from './types/event';
 export * from './types/processor';
 export * from './types/reporter';
 export * from './types/rum-event';

package/lib/index.js

@@ -37,6 +37,13 @@ Object.keys(_collector).forEach(function (key) {
   if (key in exports && exports[key] === _collector[key]) return;
   exports[key] = _collector[key];
 });
+var _event = require("./types/event");
+Object.keys(_event).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _event[key]) return;
+  exports[key] = _event[key];
+});
 var _processor = require("./types/processor");
 Object.keys(_processor).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/lib/model/shell.d.ts

@@ -1,6 +1,6 @@
 import { IClient, IConfiguration } from '../types/client';
 import { ICollector } from '../types/collector';
-import { RumCustomEvent, RumEvent, RumExceptionEvent, RumResourceEvent, RumViewEvent, SendEventOptions } from '../types/rum-event';
+import { loading_type, RumCustomEvent, RumEvent, RumExceptionEvent, RumResourceEvent, RumViewEvent, SendEventOptions } from '../types/rum-event';
 import { IShell } from '../types/shell';
 export default abstract class Shell implements IShell {
     client: IClient;
@@ -31,6 +31,26 @@ export default abstract class Shell implements IShell {
      */
     abstract init(configuration: IConfiguration): Promise<Shell> | Shell;
     sendEvent(payload: RumEvent, options?: SendEventOptions): void;
+    /**
+     * 手动开启一个新 view（手动 view 模式）。
+     *
+     * 与 PvCollector 自动 PV 的语义对齐：
+     * 1. 同名去重：与当前 view 名称相同时不创建新 view
+     * 2. emit VIEW_ENDED（结束上一 view）→ ctx.addView（写入新 view）
+     *    → emit VIEW_CREATED → 上报 view 事件
+     *
+     * url / referrer 属平台概念，由调用方经 options 传入（如 browser 传 location.href）。
+     * 事件基础字段（session_id / event_id / times / view）由 session.getBaseEvent 补齐，
+     * 与自动 PV 事件结构一致。
+     *
+     * @param name view 名称（如路由模板 `/user/:id`）
+     * @param options 可选字段：url / referrer / loading_type（默认 route_change）
+     */
+    startView(name: string, options?: {
+        url?: string;
+        referrer?: string;
+        loading_type?: loading_type;
+    }): void;
     /**
      * get config
      */
@@ -50,6 +70,9 @@ export default abstract class Shell implements IShell {
     sendView(payload: RumViewEvent): void;
     /**
      * 自定义异常上报
+     *
+     * @param payload 异常事件或 Error 对象。若为 RumExceptionEvent 且携带 source
+     *   字段（如 'react'），则使用该值；否则默认 'custom'。
      */
     sendException(payload: RumExceptionEvent | Error): void;
     /**

package/lib/model/shell.js

@@ -4,6 +4,7 @@ function _interopRequireDefault(e){return e&&e.__esModule?e:{"default":e}}
 exports.__esModule = true;
 exports["default"] = void 0;
 var _rumEvent = require("../types/rum-event");
+var _event = require("../types/event");
 var _client = _interopRequireDefault(require("../model/client"));
 var _is = require("../utils/is");
 var _Shell;
@@ -95,6 +96,53 @@ var Shell = exports["default"] = /*#__PURE__*/function () {
     }
   }
 
+  /**
+   * 手动开启一个新 view（手动 view 模式）。
+   *
+   * 与 PvCollector 自动 PV 的语义对齐：
+   * 1. 同名去重：与当前 view 名称相同时不创建新 view
+   * 2. emit VIEW_ENDED（结束上一 view）→ ctx.addView（写入新 view）
+   *    → emit VIEW_CREATED → 上报 view 事件
+   *
+   * url / referrer 属平台概念，由调用方经 options 传入（如 browser 传 location.href）。
+   * 事件基础字段（session_id / event_id / times / view）由 session.getBaseEvent 补齐，
+   * 与自动 PV 事件结构一致。
+   *
+   * @param name view 名称（如路由模板 `/user/:id`）
+   * @param options 可选字段：url / referrer / loading_type（默认 route_change）
+   */;
+  _proto.startView = function startView(name, options) {
+    if (!name) return;
+    var ctx = this.client.getContext();
+    if (!ctx || !ctx.session) return;
+    var views = ctx.getViews();
+    var prevView = views && views.length ? views[views.length - 1] : undefined;
+    // 同名去重：与当前 view 名称相同时不创建新 view
+    if (prevView && prevView.name === name) return;
+    if (prevView) {
+      ctx.emitter.emit(_event.LifeCycleEventType.VIEW_ENDED, Object.assign({
+        type: 'pv'
+      }, prevView));
+    }
+    var view = {
+      id: ctx.session.getViewId(),
+      name: name,
+      loading_type: options && options.loading_type || 'route_change'
+    };
+    ctx.addView(view);
+    var base = ctx.session.getBaseEvent ? ctx.session.getBaseEvent() : {};
+    var viewEvent = Object.assign({}, base, {
+      event_type: _rumEvent.RumEventType.VIEW,
+      type: 'pv',
+      name: name,
+      url: options && options.url,
+      referrer: options && options.referrer,
+      loading_type: view.loading_type
+    });
+    ctx.emitter.emit(_event.LifeCycleEventType.VIEW_CREATED, viewEvent);
+    this.sendEvent(viewEvent);
+  }
+
   /**
    * get config
    */;
@@ -148,6 +196,9 @@ var Shell = exports["default"] = /*#__PURE__*/function () {
 
   /**
    * 自定义异常上报
+   *
+   * @param payload 异常事件或 Error 对象。若为 RumExceptionEvent 且携带 source
+   *   字段（如 'react'），则使用该值；否则默认 'custom'。
    */;
   _proto.sendException = function sendException(payload) {
     if (!payload.name || !payload.message) {
@@ -156,6 +207,8 @@ var Shell = exports["default"] = /*#__PURE__*/function () {
     var name = payload.name,
       message = payload.message,
       stack = payload.stack;
+    // 支持自定义 source（如 'react'），否则默认 'custom'
+    var source = payload.source || 'custom';
     var data = Object.assign({
       times: 1,
       name: name,
@@ -164,7 +217,7 @@ var Shell = exports["default"] = /*#__PURE__*/function () {
     }, payload, {
       event_type: _rumEvent.RumEventType.EXCEPTION,
       type: 'custom',
-      source: 'custom'
+      source: source
     });
     this.sendEvent(data);
   }

package/lib/types/client.d.ts

@@ -150,6 +150,13 @@ export interface IConfiguration {
      * 是否开启SDK
      */
     enable?: boolean;
+    /**
+     * 手动 view 模式：开启后 SDK 不再自动采集 PV（PvCollector 跳过首屏 PV
+     * 与 history 拦截），view 生命周期由接入方通过 Shell.startView(name) 主动
+     * 控制，实现路由驱动的命名 + 计时 + 触发一体。
+     * @default false
+     */
+    trackViewsManually?: boolean;
     /**
      * 项目 id
      * v0.0.40开始，不强依赖该参数，通过Endpoint获取 service_id 确定应用

package/lib/types/event.d.ts

@@ -0,0 +1,15 @@
+/**
+ * RUM 生命周期事件枚举。
+ *
+ * 由 view 生命周期驱动，采集器通过 IContext.emitter 订阅：
+ * - VIEW_CREATED：新 view 创建（首屏或路由切换），事件体为 view 事件
+ *   （含 type: 'pv'、name、loading_type 等字段）
+ * - VIEW_ENDED：上一 view 结束，事件体为 `{ type: 'pv', ...prevView }`
+ *
+ * 注：跨包使用场景（browser 等平台包从 core 导入），须保持为普通 enum：
+ * const enum 在 babel 转译链路下无法内联，跨包引用会产生运行时错误。
+ */
+export declare enum LifeCycleEventType {
+    VIEW_CREATED = "VIEW_CREATED",
+    VIEW_ENDED = "VIEW_ENDED"
+}

package/lib/types/event.js

@@ -0,0 +1,20 @@
+"use strict";
+
+exports.__esModule = true;
+exports.LifeCycleEventType = void 0;
+/**
+ * RUM 生命周期事件枚举。
+ *
+ * 由 view 生命周期驱动，采集器通过 IContext.emitter 订阅：
+ * - VIEW_CREATED：新 view 创建（首屏或路由切换），事件体为 view 事件
+ *   （含 type: 'pv'、name、loading_type 等字段）
+ * - VIEW_ENDED：上一 view 结束，事件体为 `{ type: 'pv', ...prevView }`
+ *
+ * 注：跨包使用场景（browser 等平台包从 core 导入），须保持为普通 enum：
+ * const enum 在 babel 转译链路下无法内联，跨包引用会产生运行时错误。
+ */
+var LifeCycleEventType = exports.LifeCycleEventType = /*#__PURE__*/function (LifeCycleEventType) {
+  LifeCycleEventType["VIEW_CREATED"] = "VIEW_CREATED";
+  LifeCycleEventType["VIEW_ENDED"] = "VIEW_ENDED";
+  return LifeCycleEventType;
+}({});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arms/rum-core",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "arms rum javascript sdk core",
   "author": "guangli.fj <guangli.fj@alibaba-inc.com>",
   "license": "ISC",