@yaoxiu/marketing-dsl 1.5.2 → 2.0.0

package/dist/report/index.cjs

@@ -1,41 +1,58 @@
 'use strict';
 
 // src/report/map.ts
-function buildExposureReport(id) {
+function pickInteractionTrack(payload) {
+  const track = payload == null ? void 0 : payload.track;
+  if (!track) return void 0;
+  return { name: track.event, params: track.params };
+}
+function buildExposureReport(id, extra) {
   if (!id) return null;
-  return { id, event: "exposure" };
+  const params = { id, event: "exposure" };
+  if (extra && (extra.name !== void 0 || extra.params !== void 0)) {
+    params.extra = extra;
+  }
+  return params;
 }
-function mapRuntimeEventToReport(id, event, payload) {
+function buildCloseReport(id, options) {
   if (!id) return null;
-  switch (event) {
-    case "track": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "click",
-        extra: { trigger: "track", name: data.event, params: data.params }
-      };
-    }
-    case "navigate": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "click",
-        extra: { trigger: "navigate", url: data.url }
-      };
-    }
-    case "close": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "close",
-        reason: data.reason
-      };
-    }
-    default:
-      return null;
+  const params = {
+    id,
+    event: "close",
+    reason: options == null ? void 0 : options.reason
+  };
+  const extra = options == null ? void 0 : options.extra;
+  if (extra && (extra.name !== void 0 || extra.params !== void 0)) {
+    params.extra = extra;
+  }
+  return params;
+}
+function buildClickExtra(payload) {
+  const { track, navigate } = payload;
+  if (track) {
+    const extra = {
+      trigger: "track",
+      name: track.event,
+      params: track.params
+    };
+    if (navigate == null ? void 0 : navigate.url) extra.url = navigate.url;
+    return extra;
   }
+  if (navigate) return { trigger: "navigate", url: navigate.url };
+  return null;
+}
+function mapRuntimeEventToReport(id, event, payload) {
+  if (!id) return null;
+  if (event !== "interaction") return null;
+  const data = payload != null ? payload : {};
+  if (data.trigger !== "action") return null;
+  if (data.closes) return null;
+  const extra = buildClickExtra(data);
+  if (!extra) return null;
+  return { id, event: "click", extra };
 }
 
+exports.buildCloseReport = buildCloseReport;
 exports.buildExposureReport = buildExposureReport;
 exports.mapRuntimeEventToReport = mapRuntimeEventToReport;
+exports.pickInteractionTrack = pickInteractionTrack;

package/dist/report/index.d.cts

@@ -1,4 +1,4 @@
-import { E as RuntimeEventName } from '../types-BgUaJUAu.cjs';
+import { G as RuntimeEventName, E as DslInteractionEvent } from '../types-Bj0xyWnx.cjs';
 
 /**
  * 营销物料上报载荷类型（上报契约的唯一数据源）。
@@ -19,23 +19,39 @@ import { E as RuntimeEventName } from '../types-BgUaJUAu.cjs';
  * - `close` 关闭：用户关掉了这条物料
  */
 type MarketingReportEvent = 'exposure' | 'click' | 'close';
+/**
+ * 运营配的埋点信息（`track` 动作的事件名与参数）
+ *
+ * 挂在 `stage.onShow` / `stage.onClose` 上的 `track` 属于「曝光埋点 / 关闭埋点」，
+ * **不算点击**，所以它们进的是 `exposure` / `close` 的 `extra`，而不是产出一条 `click`。
+ * 早期实现把这类埋点名一律映射成 `click`，直接把点击量放大了数倍。
+ */
+interface MarketingTrackExtra {
+    /** 运营在配置里写的埋点名 */
+    name?: string;
+    /** 运营在配置里写的自定义参数，原样透传 */
+    params?: Record<string, unknown>;
+}
 /**
  * 点击上报的附加信息（**只在 `event='click'` 时有值**）
  *
  * 运营在 DSL 里自定义的埋点名 / 参数一律放这里，
  * **不要塞进 `reason`** —— `reason` 的语义被「关闭原因」独占。
+ *
+ * 一次点击里同时配了埋点和跳转（`sequence: [track, navigate]`，最常见的写法）时，
+ * 只产出**一条** click：`trigger='track'`，跳转地址并进 `url`。
  */
 interface MarketingClickExtra {
     /** 点击来源：`track` = 运营配的埋点动作；`navigate` = 跳转动作 */
     trigger: 'track' | 'navigate';
     /** `trigger='track'` 时：运营在配置里写的埋点名 */
     name?: string;
-    /** `trigger='navigate'` 时：跳转目标地址 */
+    /** 跳转目标地址：`trigger='navigate'` 时必有；`trigger='track'` 时若同一次点击里还配了跳转也会带上 */
     url?: string;
     /** 运营在配置里写的自定义参数，原样透传 */
     params?: Record<string, unknown>;
 }
-/** 曝光上报入参：只有 id */
+/** 曝光上报入参：运营在 `stage.onShow` 里配了埋点时带上 `extra` */
 interface MarketingExposureReportParams {
     /** 物料 id，取自 `MarketingMaterial.id` */
     id: string;
@@ -43,8 +59,14 @@ interface MarketingExposureReportParams {
     event: 'exposure';
     /** 曝光事件无关闭原因 */
     reason?: never;
-    /** 曝光事件无点击附加信息 */
-    extra?: never;
+    /**
+     * 运营配在 `stage.onShow` 里的埋点名 / 参数，没配则不带。
+     *
+     * 【为什么并进曝光而不是单独上报】那条 `track` 记的就是「这条物料露出了」，
+     * 与曝光是同一件事，单独上报会与前台统一发的 exposure 重复计数；
+     * 但也不能直接丢掉 —— 运营配了就该在后端看得到。
+     */
+    extra?: MarketingTrackExtra;
 }
 /** 关闭上报入参：可带关闭原因 */
 interface MarketingCloseReportParams {
@@ -58,8 +80,8 @@ interface MarketingCloseReportParams {
      * `action`（配置里 close 动作未写 reason 的默认值）/ 运营自定义值。
      */
     reason?: string;
-    /** 关闭事件无点击附加信息 */
-    extra?: never;
+    /** 运营配在 `stage.onClose` 里的埋点名 / 参数，没配则不带 */
+    extra?: MarketingTrackExtra;
 }
 /** 点击上报入参：必须带 extra 说明点了什么 */
 interface MarketingClickReportParams {
@@ -76,7 +98,10 @@ interface MarketingClickReportParams {
  * 上报物料事件的入参（可辨识联合，按 `event` 区分）
  *
  * 用联合而非「三个可选字段」是为了把契约写进类型里：`reason` 只配 `close`、
- * `extra` 只配 `click`，写错直接编译不过。不该出现的字段声明成 `?: never`
+ * 点击详情（`MarketingClickExtra`，带 `trigger`）只配 `click`，写错直接编译不过。
+ * `exposure` / `close` 的 `extra` 是另一种形态（`MarketingTrackExtra`，只有 `name` / `params`），
+ * 装的是运营配在 `stage.onShow` / `onClose` 里的埋点名 —— 它们不是点击，混不进 click 那一支。
+ * 不该出现的字段声明成 `?: never`
  * 而不是省略，这样消费方（formatter / 上报层 / 调试台预览）仍能直接读
  * `params.reason`、`params.extra`，无需先做类型窄化 —— 约束留在调用侧，消费侧照旧好写。
  */
@@ -88,39 +113,44 @@ type MarketingReportParams = MarketingExposureReportParams | MarketingCloseRepor
  * 前台坑位组件与后台调试台的「上报预览」共用这一份：
  * 调试台要展示的就是**真实会发给后端的 JSON**，映射有第二份实现，
  * 前台改了口径而调试台忘了改，调试台就会骗人。
+ *
+ * 【只认 `interaction`，不认 `track` / `navigate`】
+ * 动作粒度的事件不能直接当上报口径：`sequence: [track, navigate]`（先埋点再跳转）
+ * 是最常见的写法，两个动作各报一条 → 点击量翻倍；而 `track` 还能挂在
+ * `stage.onShow` / `onClose` 上，动作粒度看不出时机 → 曝光和关闭也被算成点击。
+ * 解释器为此在**交互粒度**上多抛了一条 `interaction`（一次手势 / 一个时机一条），
+ * 上报只认它。
  */
 
 /**
  * 会产生上报的运行时事件及其载荷。
  *
- * 字段一律可选：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
+ * 字段一律可选（`Partial`）：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
  * 缺字段是允许的，不该在映射这一步炸掉。
  */
 interface MarketingReportableEventPayloads {
-    /** 埋点动作：`event` 是运营配的埋点名，`params` 是自定义参数 */
-    track: {
-        event?: string;
-        params?: Record<string, unknown>;
-    };
-    /** 跳转动作：`url` 是目标地址（跳转本身由渲染壳完成，这里只记一笔） */
-    navigate: {
-        url?: string;
-        target?: string;
-    };
-    /** 关闭：`reason` 是关闭原因 */
-    close: {
-        reason?: string;
-    };
+    /** 一次交互的汇总事件，见 {@link DslInteractionEvent} */
+    interaction: Partial<DslInteractionEvent>;
 }
 /** 会产生上报的运行时事件名 */
 type MarketingReportableEventName = keyof MarketingReportableEventPayloads;
 /**
  * 事件名 → 载荷类型。
  *
- * 不产生上报的事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）
- * 载荷为 `unknown`：调用方照常传，映射返回 `null`。
+ * 不产生上报的事件（`track` / `navigate` / `close` / `call` / `error` / `state-change` /
+ * `view-change` / `ready` / `open`）载荷为 `unknown`：调用方照常传，映射返回 `null`。
  */
 type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends MarketingReportableEventName ? MarketingReportableEventPayloads[K] : unknown;
+/**
+ * 把交互事件里的埋点动作转成上报用的 `extra`（字段名 `event` → `name`）。
+ *
+ * 给宿主组装曝光 / 关闭上报用：`trigger='show'` / `'close'` 的 interaction 不产出点击，
+ * 但运营配的埋点名不能凭空消失，由宿主并进 exposure / close 的 `extra`。
+ *
+ * @param payload interaction 事件载荷
+ * @returns 埋点信息；没配埋点时返回 `undefined`
+ */
+declare function pickInteractionTrack(payload?: Partial<DslInteractionEvent> | null): MarketingTrackExtra | undefined;
 /**
  * 曝光上报载荷。
  *
@@ -128,17 +158,36 @@ type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends Market
  * 解释器根本不知道自己被画出来了。
  *
  * @param id 物料 id，为空（未取到物料）时返回 `null`，不产生上报
+ * @param extra 运营配在 `stage.onShow` 里的埋点信息，可用 {@link pickInteractionTrack} 从
+ *   `trigger='show'` 的 interaction 事件里取；没有则不带
+ * @returns 上报载荷，或 `null`
+ */
+declare function buildExposureReport(id: string | undefined | null, extra?: MarketingTrackExtra | null): MarketingExposureReportParams | null;
+/**
+ * 关闭上报载荷。
+ *
+ * 与曝光同理由：关闭由宿主统一上报一条 —— `close` 运行时事件才是「这条物料真的关了」，
+ * 运营配不配 `stage.onClose` 都得有这条。
+ *
+ * @param id 物料 id，为空时返回 `null`
+ * @param options `reason` 取自 `close` 运行时事件；`extra` 取自 `trigger='close'` 的 interaction
  * @returns 上报载荷，或 `null`
  */
-declare function buildExposureReport(id: string | undefined | null): MarketingExposureReportParams | null;
+declare function buildCloseReport(id: string | undefined | null, options?: {
+    reason?: string;
+    extra?: MarketingTrackExtra | null;
+}): MarketingCloseReportParams | null;
 /**
  * 把一个 DSL 运行时事件映射成上报载荷。
  *
  * 口径（与 `docs/marketing/README.md` 的契约一一对应）：
- * - `track` → `click`，`extra = { trigger: 'track', name, params }`
- * - `navigate` → `click`，`extra = { trigger: 'navigate', url }`
- * - `close` → `close`，带 `reason`
- * - 其余事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）不产生上报
+ * - `interaction` 且 `trigger='action'` → 一条 `click`，`extra` 见 {@link buildClickExtra}
+ * - `interaction` 且 `trigger='show'` / `'close'` → `null`：曝光 / 关闭由宿主统一上报，
+ *   运营配在这两个时机上的埋点名走 {@link buildExposureReport} / {@link buildCloseReport} 的 `extra`
+ * - `interaction` 且 `trigger='action'` 但 `closes` 为真（手势里执行了关闭动作）→ `null`：
+ *   点关闭按钮的本质是关闭，不再算一次点击
+ * - 其余事件（`track` / `navigate` / `close` / `call` / `error` / `state-change` /
+ *   `view-change` / `ready` / `open`）不产生上报 —— 它们是动作粒度的事件，按它们上报会重复计数
  *
  * @param id 物料 id，为空时返回 `null`（拿不到 id 的上报对后端没有意义）
  * @param event 运行时事件名
@@ -147,4 +196,4 @@ declare function buildExposureReport(id: string | undefined | null): MarketingEx
  */
 declare function mapRuntimeEventToReport<K extends RuntimeEventName>(id: string | undefined | null, event: K, payload?: MarketingRuntimeEventPayload<K>): MarketingReportParams | null;
 
-export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, buildExposureReport, mapRuntimeEventToReport };
+export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, type MarketingTrackExtra, buildCloseReport, buildExposureReport, mapRuntimeEventToReport, pickInteractionTrack };

package/dist/report/index.d.ts

@@ -1,4 +1,4 @@
-import { E as RuntimeEventName } from '../types-BgUaJUAu.js';
+import { G as RuntimeEventName, E as DslInteractionEvent } from '../types-Bj0xyWnx.js';
 
 /**
  * 营销物料上报载荷类型（上报契约的唯一数据源）。
@@ -19,23 +19,39 @@ import { E as RuntimeEventName } from '../types-BgUaJUAu.js';
  * - `close` 关闭：用户关掉了这条物料
  */
 type MarketingReportEvent = 'exposure' | 'click' | 'close';
+/**
+ * 运营配的埋点信息（`track` 动作的事件名与参数）
+ *
+ * 挂在 `stage.onShow` / `stage.onClose` 上的 `track` 属于「曝光埋点 / 关闭埋点」，
+ * **不算点击**，所以它们进的是 `exposure` / `close` 的 `extra`，而不是产出一条 `click`。
+ * 早期实现把这类埋点名一律映射成 `click`，直接把点击量放大了数倍。
+ */
+interface MarketingTrackExtra {
+    /** 运营在配置里写的埋点名 */
+    name?: string;
+    /** 运营在配置里写的自定义参数，原样透传 */
+    params?: Record<string, unknown>;
+}
 /**
  * 点击上报的附加信息（**只在 `event='click'` 时有值**）
  *
  * 运营在 DSL 里自定义的埋点名 / 参数一律放这里，
  * **不要塞进 `reason`** —— `reason` 的语义被「关闭原因」独占。
+ *
+ * 一次点击里同时配了埋点和跳转（`sequence: [track, navigate]`，最常见的写法）时，
+ * 只产出**一条** click：`trigger='track'`，跳转地址并进 `url`。
  */
 interface MarketingClickExtra {
     /** 点击来源：`track` = 运营配的埋点动作；`navigate` = 跳转动作 */
     trigger: 'track' | 'navigate';
     /** `trigger='track'` 时：运营在配置里写的埋点名 */
     name?: string;
-    /** `trigger='navigate'` 时：跳转目标地址 */
+    /** 跳转目标地址：`trigger='navigate'` 时必有；`trigger='track'` 时若同一次点击里还配了跳转也会带上 */
     url?: string;
     /** 运营在配置里写的自定义参数，原样透传 */
     params?: Record<string, unknown>;
 }
-/** 曝光上报入参：只有 id */
+/** 曝光上报入参：运营在 `stage.onShow` 里配了埋点时带上 `extra` */
 interface MarketingExposureReportParams {
     /** 物料 id，取自 `MarketingMaterial.id` */
     id: string;
@@ -43,8 +59,14 @@ interface MarketingExposureReportParams {
     event: 'exposure';
     /** 曝光事件无关闭原因 */
     reason?: never;
-    /** 曝光事件无点击附加信息 */
-    extra?: never;
+    /**
+     * 运营配在 `stage.onShow` 里的埋点名 / 参数，没配则不带。
+     *
+     * 【为什么并进曝光而不是单独上报】那条 `track` 记的就是「这条物料露出了」，
+     * 与曝光是同一件事，单独上报会与前台统一发的 exposure 重复计数；
+     * 但也不能直接丢掉 —— 运营配了就该在后端看得到。
+     */
+    extra?: MarketingTrackExtra;
 }
 /** 关闭上报入参：可带关闭原因 */
 interface MarketingCloseReportParams {
@@ -58,8 +80,8 @@ interface MarketingCloseReportParams {
      * `action`（配置里 close 动作未写 reason 的默认值）/ 运营自定义值。
      */
     reason?: string;
-    /** 关闭事件无点击附加信息 */
-    extra?: never;
+    /** 运营配在 `stage.onClose` 里的埋点名 / 参数，没配则不带 */
+    extra?: MarketingTrackExtra;
 }
 /** 点击上报入参：必须带 extra 说明点了什么 */
 interface MarketingClickReportParams {
@@ -76,7 +98,10 @@ interface MarketingClickReportParams {
  * 上报物料事件的入参（可辨识联合，按 `event` 区分）
  *
  * 用联合而非「三个可选字段」是为了把契约写进类型里：`reason` 只配 `close`、
- * `extra` 只配 `click`，写错直接编译不过。不该出现的字段声明成 `?: never`
+ * 点击详情（`MarketingClickExtra`，带 `trigger`）只配 `click`，写错直接编译不过。
+ * `exposure` / `close` 的 `extra` 是另一种形态（`MarketingTrackExtra`，只有 `name` / `params`），
+ * 装的是运营配在 `stage.onShow` / `onClose` 里的埋点名 —— 它们不是点击，混不进 click 那一支。
+ * 不该出现的字段声明成 `?: never`
  * 而不是省略，这样消费方（formatter / 上报层 / 调试台预览）仍能直接读
  * `params.reason`、`params.extra`，无需先做类型窄化 —— 约束留在调用侧，消费侧照旧好写。
  */
@@ -88,39 +113,44 @@ type MarketingReportParams = MarketingExposureReportParams | MarketingCloseRepor
  * 前台坑位组件与后台调试台的「上报预览」共用这一份：
  * 调试台要展示的就是**真实会发给后端的 JSON**，映射有第二份实现，
  * 前台改了口径而调试台忘了改，调试台就会骗人。
+ *
+ * 【只认 `interaction`，不认 `track` / `navigate`】
+ * 动作粒度的事件不能直接当上报口径：`sequence: [track, navigate]`（先埋点再跳转）
+ * 是最常见的写法，两个动作各报一条 → 点击量翻倍；而 `track` 还能挂在
+ * `stage.onShow` / `onClose` 上，动作粒度看不出时机 → 曝光和关闭也被算成点击。
+ * 解释器为此在**交互粒度**上多抛了一条 `interaction`（一次手势 / 一个时机一条），
+ * 上报只认它。
  */
 
 /**
  * 会产生上报的运行时事件及其载荷。
  *
- * 字段一律可选：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
+ * 字段一律可选（`Partial`）：宿主（Vue 组件的 `$event`、调试台的手工构造）拿到的载荷未必齐全，
  * 缺字段是允许的，不该在映射这一步炸掉。
  */
 interface MarketingReportableEventPayloads {
-    /** 埋点动作：`event` 是运营配的埋点名，`params` 是自定义参数 */
-    track: {
-        event?: string;
-        params?: Record<string, unknown>;
-    };
-    /** 跳转动作：`url` 是目标地址（跳转本身由渲染壳完成，这里只记一笔） */
-    navigate: {
-        url?: string;
-        target?: string;
-    };
-    /** 关闭：`reason` 是关闭原因 */
-    close: {
-        reason?: string;
-    };
+    /** 一次交互的汇总事件，见 {@link DslInteractionEvent} */
+    interaction: Partial<DslInteractionEvent>;
 }
 /** 会产生上报的运行时事件名 */
 type MarketingReportableEventName = keyof MarketingReportableEventPayloads;
 /**
  * 事件名 → 载荷类型。
  *
- * 不产生上报的事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）
- * 载荷为 `unknown`：调用方照常传，映射返回 `null`。
+ * 不产生上报的事件（`track` / `navigate` / `close` / `call` / `error` / `state-change` /
+ * `view-change` / `ready` / `open`）载荷为 `unknown`：调用方照常传，映射返回 `null`。
  */
 type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends MarketingReportableEventName ? MarketingReportableEventPayloads[K] : unknown;
+/**
+ * 把交互事件里的埋点动作转成上报用的 `extra`（字段名 `event` → `name`）。
+ *
+ * 给宿主组装曝光 / 关闭上报用：`trigger='show'` / `'close'` 的 interaction 不产出点击，
+ * 但运营配的埋点名不能凭空消失，由宿主并进 exposure / close 的 `extra`。
+ *
+ * @param payload interaction 事件载荷
+ * @returns 埋点信息；没配埋点时返回 `undefined`
+ */
+declare function pickInteractionTrack(payload?: Partial<DslInteractionEvent> | null): MarketingTrackExtra | undefined;
 /**
  * 曝光上报载荷。
  *
@@ -128,17 +158,36 @@ type MarketingRuntimeEventPayload<K extends RuntimeEventName> = K extends Market
  * 解释器根本不知道自己被画出来了。
  *
  * @param id 物料 id，为空（未取到物料）时返回 `null`，不产生上报
+ * @param extra 运营配在 `stage.onShow` 里的埋点信息，可用 {@link pickInteractionTrack} 从
+ *   `trigger='show'` 的 interaction 事件里取；没有则不带
+ * @returns 上报载荷，或 `null`
+ */
+declare function buildExposureReport(id: string | undefined | null, extra?: MarketingTrackExtra | null): MarketingExposureReportParams | null;
+/**
+ * 关闭上报载荷。
+ *
+ * 与曝光同理由：关闭由宿主统一上报一条 —— `close` 运行时事件才是「这条物料真的关了」，
+ * 运营配不配 `stage.onClose` 都得有这条。
+ *
+ * @param id 物料 id，为空时返回 `null`
+ * @param options `reason` 取自 `close` 运行时事件；`extra` 取自 `trigger='close'` 的 interaction
  * @returns 上报载荷，或 `null`
  */
-declare function buildExposureReport(id: string | undefined | null): MarketingExposureReportParams | null;
+declare function buildCloseReport(id: string | undefined | null, options?: {
+    reason?: string;
+    extra?: MarketingTrackExtra | null;
+}): MarketingCloseReportParams | null;
 /**
  * 把一个 DSL 运行时事件映射成上报载荷。
  *
  * 口径（与 `docs/marketing/README.md` 的契约一一对应）：
- * - `track` → `click`，`extra = { trigger: 'track', name, params }`
- * - `navigate` → `click`，`extra = { trigger: 'navigate', url }`
- * - `close` → `close`，带 `reason`
- * - 其余事件（`call` / `error` / `state-change` / `view-change` / `ready` / `open`）不产生上报
+ * - `interaction` 且 `trigger='action'` → 一条 `click`，`extra` 见 {@link buildClickExtra}
+ * - `interaction` 且 `trigger='show'` / `'close'` → `null`：曝光 / 关闭由宿主统一上报，
+ *   运营配在这两个时机上的埋点名走 {@link buildExposureReport} / {@link buildCloseReport} 的 `extra`
+ * - `interaction` 且 `trigger='action'` 但 `closes` 为真（手势里执行了关闭动作）→ `null`：
+ *   点关闭按钮的本质是关闭，不再算一次点击
+ * - 其余事件（`track` / `navigate` / `close` / `call` / `error` / `state-change` /
+ *   `view-change` / `ready` / `open`）不产生上报 —— 它们是动作粒度的事件，按它们上报会重复计数
  *
  * @param id 物料 id，为空时返回 `null`（拿不到 id 的上报对后端没有意义）
  * @param event 运行时事件名
@@ -147,4 +196,4 @@ declare function buildExposureReport(id: string | undefined | null): MarketingEx
  */
 declare function mapRuntimeEventToReport<K extends RuntimeEventName>(id: string | undefined | null, event: K, payload?: MarketingRuntimeEventPayload<K>): MarketingReportParams | null;
 
-export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, buildExposureReport, mapRuntimeEventToReport };
+export { type MarketingClickExtra, type MarketingClickReportParams, type MarketingCloseReportParams, type MarketingExposureReportParams, type MarketingReportEvent, type MarketingReportParams, type MarketingReportableEventName, type MarketingReportableEventPayloads, type MarketingRuntimeEventPayload, type MarketingTrackExtra, buildCloseReport, buildExposureReport, mapRuntimeEventToReport, pickInteractionTrack };

package/dist/report/index.js

@@ -1,38 +1,53 @@
 // src/report/map.ts
-function buildExposureReport(id) {
+function pickInteractionTrack(payload) {
+  const track = payload == null ? void 0 : payload.track;
+  if (!track) return void 0;
+  return { name: track.event, params: track.params };
+}
+function buildExposureReport(id, extra) {
   if (!id) return null;
-  return { id, event: "exposure" };
+  const params = { id, event: "exposure" };
+  if (extra && (extra.name !== void 0 || extra.params !== void 0)) {
+    params.extra = extra;
+  }
+  return params;
 }
-function mapRuntimeEventToReport(id, event, payload) {
+function buildCloseReport(id, options) {
   if (!id) return null;
-  switch (event) {
-    case "track": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "click",
-        extra: { trigger: "track", name: data.event, params: data.params }
-      };
-    }
-    case "navigate": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "click",
-        extra: { trigger: "navigate", url: data.url }
-      };
-    }
-    case "close": {
-      const data = payload != null ? payload : {};
-      return {
-        id,
-        event: "close",
-        reason: data.reason
-      };
-    }
-    default:
-      return null;
+  const params = {
+    id,
+    event: "close",
+    reason: options == null ? void 0 : options.reason
+  };
+  const extra = options == null ? void 0 : options.extra;
+  if (extra && (extra.name !== void 0 || extra.params !== void 0)) {
+    params.extra = extra;
+  }
+  return params;
+}
+function buildClickExtra(payload) {
+  const { track, navigate } = payload;
+  if (track) {
+    const extra = {
+      trigger: "track",
+      name: track.event,
+      params: track.params
+    };
+    if (navigate == null ? void 0 : navigate.url) extra.url = navigate.url;
+    return extra;
   }
+  if (navigate) return { trigger: "navigate", url: navigate.url };
+  return null;
+}
+function mapRuntimeEventToReport(id, event, payload) {
+  if (!id) return null;
+  if (event !== "interaction") return null;
+  const data = payload != null ? payload : {};
+  if (data.trigger !== "action") return null;
+  if (data.closes) return null;
+  const extra = buildClickExtra(data);
+  if (!extra) return null;
+  return { id, event: "click", extra };
 }
 
-export { buildExposureReport, mapRuntimeEventToReport };
+export { buildCloseReport, buildExposureReport, mapRuntimeEventToReport, pickInteractionTrack };

package/dist/{types-BgUaJUAu.d.cts → types-Bj0xyWnx.d.cts}

@@ -213,7 +213,12 @@ interface RenderLayer {
 interface RenderTree {
     /** 数据没回来或加载失败时为 false，框架层什么都不画 */
     ready: boolean;
-    /** 有弹窗层时框架层需要撑满宿主容器 */
+    /**
+     * 当前视图栈里是否有弹窗视图。
+     *
+     * 注意不是「配置里有没有 popup 视图」——多视图配置（如公告条点击弹出弹窗）在弹出之前
+     * 这里是 `false`，根容器保持 `relative`，宿主的流式坑位才不会被脱流的根节点撑塌。
+     */
     hasPopup: boolean;
     /** 根容器样式，已按 hasPopup 算好 */
     rootStyle: CssStyle;
@@ -225,6 +230,51 @@ interface RenderTree {
 }
 type DslSource = (params: Record<string, unknown>, user: Record<string, unknown>) => unknown | Promise<unknown>;
 type DslHandler = (params: Record<string, unknown>) => void;
+/**
+ * 一次交互（手势 / 时机）的触发来源。
+ *
+ * - `show`：视图的 `stage.onShow` 被触发（曝光时机）
+ * - `close`：视图的 `stage.onClose` 被触发（关闭时机）
+ * - `action`：用户点了带 `action` 的节点（含关闭按钮、tab、倒计时 `onEnd`）
+ */
+type DslInteractionTrigger = 'show' | 'close' | 'action';
+/**
+ * 一次交互的汇总事件（`interaction`），**专供上报**。
+ *
+ * 【为什么要有它】`track` / `navigate` 是**动作**粒度的事件，一次手势里配
+ * `sequence: [track, navigate]`（先埋点再跳转）是标准写法，按动作上报必然把点击量翻倍；
+ * 而 `track` 还能挂在 `stage.onShow` / `stage.onClose` 上，动作粒度看不出时机，
+ * 一律算成点击会把曝光和关闭也计成点击。
+ *
+ * 所以在**时机**粒度上再派发一条汇总事件：一次手势 = 一条 `interaction`，
+ * `sequence` 里有 N 个动作也只汇总成一条。原有的 `track` / `navigate` / `close` /
+ * `call` / `error` 事件语义不变、照常派发（宿主要靠它们做跳转、接自有埋点系统），
+ * `interaction` 是**新增**的，不替代任何既有事件。
+ */
+interface DslInteractionEvent {
+    /** 触发时机 */
+    trigger: DslInteractionTrigger;
+    /** 关闭原因，仅 `trigger='close'` 时有值 */
+    reason?: string;
+    /** 这次交互里的埋点动作；`sequence` 里有多个 `track` 时只取第一个 */
+    track?: {
+        event: string;
+        params?: Record<string, unknown>;
+    };
+    /** 这次交互里的跳转动作；有多个 `navigate` 时只取第一个 */
+    navigate?: {
+        url: string;
+        target?: string;
+    };
+    /**
+     * 这次交互里执行了关闭动作（`close` / `closeAll`）。
+     *
+     * 用来把「点关闭按钮」和「点营销内容」区分开：前者的本质是关闭，不该再算一次点击。
+     * 运营常把埋点配进关闭按钮的 `sequence: [track, close]`，不标记的话这一下会同时
+     * 产出 close 和 click 两条，点击量照样虚增。埋点名不会丢 —— 宿主把它并进 close 上报。
+     */
+    closes?: boolean;
+}
 interface RuntimeEvents {
     ready: {
         keys: string[];
@@ -244,6 +294,8 @@ interface RuntimeEvents {
         name: string;
         params: Record<string, unknown>;
     };
+    /** 一次交互的汇总事件，专供上报，见 {@link DslInteractionEvent} */
+    interaction: DslInteractionEvent;
     'state-change': Record<string, unknown>;
     'view-change': {
         view: string;
@@ -290,4 +342,4 @@ interface RuntimeOptions {
     emit?: RuntimeEmit;
 }
 
-export type { DslHandler as A, RuntimeEvents as B, CssStyle as C, Dsl as D, RuntimeEventName as E, RuntimeEmit as F, RuntimeOptions as R, RenderTree as a, DslView as b, DslStyle as c, DslViewType as d, DslNodeType as e, DslLength as f, DslRect as g, DslActionBase as h, DslNavigateAction as i, DslCloseAction as j, DslCloseAllAction as k, DslOpenAction as l, DslSetStateAction as m, DslTrackAction as n, DslCallAction as o, DslSequenceAction as p, DslAction as q, DslNode as r, DslClosePosition as s, DslCloseButton as t, DslStage as u, DslSourceRef as v, DslDerived as w, RenderElement as x, RenderLayer as y, DslSource as z };
+export type { DslHandler as A, DslInteractionTrigger as B, CssStyle as C, Dsl as D, DslInteractionEvent as E, RuntimeEvents as F, RuntimeEventName as G, RuntimeEmit as H, RuntimeOptions as R, RenderTree as a, DslView as b, DslStyle as c, DslViewType as d, DslNodeType as e, DslLength as f, DslRect as g, DslActionBase as h, DslNavigateAction as i, DslCloseAction as j, DslCloseAllAction as k, DslOpenAction as l, DslSetStateAction as m, DslTrackAction as n, DslCallAction as o, DslSequenceAction as p, DslAction as q, DslNode as r, DslClosePosition as s, DslCloseButton as t, DslStage as u, DslSourceRef as v, DslDerived as w, RenderElement as x, RenderLayer as y, DslSource as z };