# @focus-reactive/payload-plugin-analytics 中文文档

规范地址：https://npmcn.com/package/%40focus-reactive/payload-plugin-analytics/

版本：1\.2\.2
npm 元数据更新时间：2026-10-27T09:21:21.015Z
中文译文更新时间：2026-11-15T04:10:57.843Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40focus-reactive/payload-plugin-analytics
原文对照：https://npmcn.com/package/%40focus-reactive/payload-plugin-analytics/?lang=original
项目主页：https://github.com/focusreactive/payload-plugins#readme
源码仓库：https://github.com/focusreactive/payload-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.6 MB，1154 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：next ^14\.1\.0 \|\| ^15\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，payload ^3\.0\.0，recharts ^2\.15\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，lucide-react ^0\.469\.0，@payloadcms/ui ^3\.0\.0，@payloadcms/next ^3\.0\.0，react-day-picker ^9\.0\.0，@tanstack/react-query ^5\.59\.0
- 首次发布：2026-06-04T15:21:31.361Z
- 最新版本发布：2026-07-08T11:23:35.621Z
- 近 30 天下载量：2597（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

GA4 支持的分析插件 [有效载荷CMS](https://payloadcms.com/) v3 + 下一个.js. 添加完整的分析仪表板 **有效载荷管理员** ——KPI,流量,上页/出处/活动,设备,地理学,会话,出行,和铅-动作相通

## 安装

```sh
npm install @focus-reactive/payload-plugin-analytics
```

也可以使用：`pnpm add @focus-reactive/payload-plugin-analytics`、`yarn add @focus-reactive/payload-plugin-analytics`、`bun add @focus-reactive/payload-plugin-analytics`

## README

# @ 焦点反应/ payload- plugin- 分析

GA4 支持的分析插件 [有效载荷CMS](https://payloadcms.com/) v3 + 下一个.js. 添加完整的分析仪表板 **有效载荷管理员** ——KPI,流量,上页/出处/活动,设备,地理,会话,出行,和铅-动作转换——外加一个小客户端-侧跟踪层为您前端. 可选 A/B 分析标签集成 [`@focus-reactive/payload-plugin-ab`](https://www.npmjs.com/package/@focus-reactive/payload-plugin-ab)。 。 。 .

有两分之一:

-   **服务器** —— 说 `analyticsPlugin()` 注册一个管理员仪表板视图和 REST 端点,从 **GA4 数据 API** 使用服务账户.
-   **客户端** —— 说 `<AnalyticsProvider>` + 键 `ga4Provider()` 装入 `gtag.js`,跟踪页面浏览和路由变化,以及消防参与/牵头行动活动到GA4.

* * *

## AI 整合提示

> 复制并粘贴此提示到您的 AI 助手( Cursor, Claude等) 中, 将插件整合到已有的 Biveload + Next.js 项目中 .

```
I want to add an analytics dashboard to my Payload CMS v3 + Next.js project using @focus-reactive/payload-plugin-analytics.

## How it works

The plugin has a server half and a client half:

- Server: analyticsPlugin() in payload.config.ts injects an admin view at /analytics and REST
  endpoints under /api/analytics/*. The endpoints read reports from the GA4 Data API using a
  Google service account. Nothing is stored in your database — GA4 is the source of truth.
- Client: <AnalyticsProvider provider={ga4Provider({ measurementId })}> wraps your front-end app.
  It injects gtag.js, tracks page_view on first load and on every route change, and exposes
  helpers to fire engagement and "lead_action" conversion events.

## Prerequisites (GA4)

1. A GA4 property — note its Measurement ID (G-XXXXXXX) and numeric Property ID.
2. A Google Cloud service account with the Google Analytics Data API enabled. Create a JSON key
   and grant the service account "Viewer" on the GA4 property (Admin → Property Access Management).
3. In GA4 → Admin → Custom definitions, register the EVENT-SCOPED custom dimensions and the
   custom metric the plugin reads (see "Register custom dimensions and the conversion event"
   below for the full table). At minimum:
   - Custom dimensions (scope = Event): `fr_session_id`, `fr_session_start`, `fr_event_seq`,
     `fr_lead_type`, and — if you use the A/B tab — `fr_ab_experiment`, `fr_ab_variant`,
     `fr_ab_visitor_id`.
   - Custom metric (scope = Event): `fr_elapsed_ms` (powers avg time-to-action on the Lead
     Actions tab).

## Installation

pnpm add @focus-reactive/payload-plugin-analytics

## Step 1 — Register the plugin in payload.config.ts

import { analyticsPlugin } from '@focus-reactive/payload-plugin-analytics'

// Inside buildConfig({ plugins: [...] })
analyticsPlugin({
  ga4: {
    measurementId: process.env.GA4_MEASUREMENT_ID!,         // G-XXXXXXX
    propertyId: process.env.GA4_PROPERTY_ID!,               // numeric
    serviceAccount: {
      clientEmail: process.env.GA4_CLIENT_EMAIL!,
      // Env vars escape newlines — un-escape them:
      privateKey: (process.env.GA4_PRIVATE_KEY ?? '').replace(/\\n/g, '\n'),
    },
  },
  leadActions: {
    types: ['phone_click', 'email_click', 'form_submit'],   // lead types you fire
  },
})

The admin dashboard, header link, and endpoints are injected automatically — no manual admin wiring.

## Step 2 — Wrap your front end with the provider (Client Component)

// app/providers.tsx
'use client'
import { AnalyticsProvider, ga4Provider } from '@focus-reactive/payload-plugin-analytics/client'

export function Analytics({ measurementId, children }) {
  return <AnalyticsProvider provider={ga4Provider({ measurementId })}>{children}</AnalyticsProvider>
}

// app/layout.tsx (Server Component)
import { Analytics } from './providers'
export default function RootLayout({ children }) {
  return (
    <html><body>
      <Analytics measurementId={process.env.NEXT_PUBLIC_GA4_MEASUREMENT_ID!}>{children}</Analytics>
    </body></html>
  )
}

## Step 3 — Fire conversion events

import { TrackLeadAction } from '@focus-reactive/payload-plugin-analytics/client'

<TrackLeadAction on="click" type="phone_click">
  <a href="tel:+1234567890">Call us</a>
</TrackLeadAction>

## Important notes

- ga4.measurementId must match /^G-[A-Z0-9]+$/ and ga4.propertyId is required — the plugin throws
  on buildConfig otherwise.
- The service account private key must be a real multi-line PEM at runtime. When stored in an env
  var, un-escape "\n" as shown above.
- The dashboard reads GA4 directly. New events take a few minutes to appear; GA4 also samples and
  applies its own data-freshness rules.
- The Lead Actions tab only works if "fr_lead_type" is registered as a custom dimension in GA4.
- AnalyticsProvider must be a client component boundary (it renders gtag scripts). Mount it once,
  as high as possible — nesting it fires duplicate page_view events (a dev warning is logged).
```

* * *

## 如何运作

GA4是真理的唯一来源. 插件从不将分析数据写入您的数据库—— 它 **读取** GA4 用于仪表板和 **写入** 从浏览器通过 `gtag.js`。 。 。 .

```
                    ┌─────────────────────────── Browser ───────────────────────────┐
                    │  <AnalyticsProvider provider={ga4Provider(...)}>                │
   Your front end → │    • injects gtag.js                                            │
                    │    • page_view on load + every route change                     │
                    │    • <Track> / <TrackLeadAction> / useAnalytics() → events      │
                    └───────────────────────────────┬─────────────────────────────────┘
                                                     │  events
                                                     ▼
                                          ┌──────────────────┐
                                          │   GA4 property   │
                                          └────────┬─────────┘
                                                   │  Data API (service account)
                                                   ▼
                    ┌──────────────────────── Payload admin ─────────────────────────┐
                    │  analyticsPlugin() → /api/analytics/* endpoints                 │
                    │                    → Analytics view at /admin/analytics         │
                    │  KPIs · Top pages/sources/events · Devices · Geo · Sessions ·   │
                    │  Journeys · Lead actions · (optional) A/B tab                   │
                    └─────────────────────────────────────────────────────────────────┘
```

仪表板视图 **分析** 标题图标、管理员和所有 REST 端点自动注入到您的有效载荷配置中。 您只注册插件并挂载客户端提供者 .

* * *

## GA4 设置

插件对两个 GA4 表面说话: 浏览器通过 `gtag.js` (度量衡ID),服务器通过 GA4 读取报告 **数据 API** (财产ID+服务账户). 二者设一.

### 1\. 获取您的GA4标识符

-   **测量标识** —— 说 `G-XXXXXXX`. GA4 – 管理员 – 数据流 – 您的网页流.
-   **财产标识** ——数字ID(如. `123456789`GA4 管理 地产设置 .

### 2\. 为 Data API 创建服务账户

1.  单位 [谷歌云控台](https://console.cloud.google.com/),创建(或选择)项目.
2.  启用 **Google 分析数据 API**。 。 。 .
3.  创建一个 **服务账户** • 增加一个 **JSON 键**从您需要的密钥文件中 `client_email` 财务报告和审定财务报表 `private_key`。 。 。 .

### 3\. 准许服务账户进入GA4财产

GA4 行政部门 **财产访问管理** - 加上服务账户 `client_email` 至少为 **查看器** 角色。 。 。 没有这个, 每份报告都会返回权限错误 .

### 4\. 登记自定义维度和转换事件

GA4 行政部门 **自定义** → **创建自定义尺寸** (镜= **活动**:

| 参数名称 | 范围 | 所需经费 |
| --- | --- | --- |
| `fr_session_id` | 活动 | 会话标签和会话抽屉(会话身份) |
| `fr_session_start` | 活动 | 会话开始时间/ 会话顺序 |
| `fr_event_seq` | 活动 | 一分钟内安排行程和抽屉 |
| `fr_lead_type` | 活动 | 主动作标签 |
| `fr_ab_experiment` | 活动 | A/B 标签( 可选) |
| `fr_ab_variant` | 活动 | A/B 标签( 可选) |
| `fr_ab_visitor_id` | 活动 | A/B 标签( 可选) |

然后创建匹配 **自定义度量** 在相同情况下 **自定义** 屏幕 – **创建自定义参数** (镜= **活动**:

| 参数名称 | 范围 | 单位/ 类型 | 所需经费 |
| --- | --- | --- | --- |
| `fr_elapsed_ms` | 活动 | 标准(分) | 在“牵头行动”标签上显示时间到行动 |

插件点火引导转换为 a `lead_action` 载有 `fr_lead_type` 参数(和 `fr_elapsed_ms` 页:1 GA4只允许您在自定义参数注册为维度或度量后查询,所以这些步骤对于上面提到的分页是强制性的. 未注册的尺寸优雅地降解——受影响的分页显示的是"设置需要"提示而不是失败.

### 5\. 向插件提供值

```bash
# .env
GA4_MEASUREMENT_ID=G-XXXXXXX
GA4_PROPERTY_ID=123456789
GA4_CLIENT_EMAIL=analytics@your-project.iam.gserviceaccount.com
GA4_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n"
NEXT_PUBLIC_GA4_MEASUREMENT_ID=G-XXXXXXX
```

> **发现:** env 文件以字元存储私钥 `\n` 顺序。 在传递到插件前取消它们 : `privateKey: process.env.GA4_PRIVATE_KEY!.replace(/\\n/g, '\n')`。 。 。 .

* * *

## 安装

该插件将它的回放UI和图表作为 **同行依赖关系** 所以它和你的应用分享一份 与所需的端点一起安装插件 :

```bash
pnpm add @focus-reactive/payload-plugin-analytics \
  @payloadcms/ui @payloadcms/next @tanstack/react-query \
  lucide-react react-day-picker recharts
```

| 同伴依赖关系 | 范围 | 为什么 |
| --- | --- | --- |
| `payload` | `^3.0.0` | 核心 — 插件目标 |
| `@payloadcms/ui` | `^3.0.0` | 仪表板使用的管理 UI 原始 |
| `@payloadcms/next` | `^3.0.0` | 管理视图+端点接线 |
| `@tanstack/react-query` | `^5.59.0` | 在仪表板上取取/采集数据 |
| `lucide-react` | `^0.469.0` | 图标(KPI,铅行动登记册) |
| `react-day-picker` | `^9.0.0` | 过滤栏中的日期距拾取器 |
| `recharts` | `^2.15.0` | 趋势/甜甜圈图 |
| `next` | `^14 || ^15` | 可选——仅供客户跟踪一半 |
| `react` 编号 : `react-dom` | `^18 || ^19` | 可选——仅供客户跟踪一半 |

`next`, (中文(简体) ), `react`,以及 `react-dom` 被宣布为可选, 但任何真正的有效载荷 v3 + Next.js app 已经提供了它们 .

* * *

## 快速启动

### 步骤1——注册插件(服务器)

```ts
// payload.config.ts
import { buildConfig } from "payload";
import { analyticsPlugin } from "@focus-reactive/payload-plugin-analytics";

export default buildConfig({
  plugins: [
    analyticsPlugin({
      ga4: {
        measurementId: process.env.GA4_MEASUREMENT_ID!, // G-XXXXXXX
        propertyId: process.env.GA4_PROPERTY_ID!, // numeric
        serviceAccount: {
          clientEmail: process.env.GA4_CLIENT_EMAIL!,
          privateKey: (process.env.GA4_PRIVATE_KEY ?? "").replace(/\\n/g, "\n"),
        },
      },
      leadActions: {
        types: ["phone_click", "email_click", "form_submit"],
      },
    }),
  ],
});
```

此输入, 没有进一步的管理配置 :

-   一个 **分析** 视图 `/admin/analytics`
-   管理员头中的图表图标( 工具提示 “ 分析” ) 链接到视图
-   REST 下端点 `/api/analytics/*`
-   仪表板需要的管理员

### 第2步——将前端与提供者相接

`ga4Provider()` 返回服务商对象,所以包装器必须是客户端组件。 创建一次并挂载在您的应用程序的根上:

```tsx
// app/AnalyticsProviderClient.tsx
"use client";

import { AnalyticsProvider, ga4Provider } from "@focus-reactive/payload-plugin-analytics/client";
import type { ReactNode } from "react";

export function AnalyticsProviderClient({ measurementId, children }: { measurementId: string; children: ReactNode }) {
  return <AnalyticsProvider provider={ga4Provider({ measurementId })}>{children}</AnalyticsProvider>;
}
```

```tsx
// app/layout.tsx (Server Component)
import { AnalyticsProviderClient } from "./AnalyticsProviderClient";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AnalyticsProviderClient measurementId={process.env.NEXT_PUBLIC_GA4_MEASUREMENT_ID!}>
          <main>{children}</main>
        </AnalyticsProviderClient>
      </body>
    </html>
  );
}
```

`page_view` 现在,在第一个负载和每个客户端的路由变化上自动开火.

### 第3步——打开仪表板

启动您的应用程序, 在有效载荷管理员中签名, 并单击标题中的图表图标( 或访问) `/admin/analytics`) (中文(简体) ). 在过滤栏中选择一个日期范围并进行比较。 一旦GA4收集了事件,且服务账户有财产访问,数据就会出现.

* * *

## 配置参考

### 插件选项

```ts
interface AnalyticsPluginConfig {
  /** GA4 connection — required. */
  ga4: Ga4Config;

  /** Skip the plugin entirely (returns the config untouched). */
  disabled?: boolean;

  /** Lead-action types + admin icon/label registry. */
  leadActions?: LeadActionsPluginConfig;

  /** Auto-attach DOM listeners on the client for common lead actions. */
  autoTrackLeadActions?: AutoTrackLeadActionsConfig;

  /** Gate access to the dashboard endpoints. Receives the Payload request. */
  access?: (args: { req: PayloadRequest }) => boolean | Promise<boolean>;

  /** Override / extend i18n strings used by the dashboard. */
  translations?: Translations;

  /** Register custom dashboard blocks (component + optional server fetch). */
  blocks?: Record<BlockId, Partial<BlockDefinition>>;

  /** Reorder, resize, enable/disable, or add rows & blocks per tab. */
  layout?: AnalyticsLayoutConfigInput;

  /** Enable the A/B analytics tab (integrates with payload-plugin-ab). */
  ab?: AbIntegrationConfig;
}
```

### Ga4 图形

```ts
interface Ga4Config {
  /** GA4 numeric Property ID — used by the Data API (server reports). */
  propertyId: string;
  /** GA4 Measurement ID (G-XXXXXXX) — used by gtag.js (client events). */
  measurementId: string;
  serviceAccount: {
    clientEmail: string;
    privateKey: string; // real multi-line PEM at runtime
  };
}
```

验证时间 `buildConfig` 时间 : `measurementId` 必须匹配 `^G-[A-Z0-9]+$`, (中文(简体) ), `propertyId` 如果服务账户证书缺失,则需要发出警告.

### 铅行动

```ts
interface LeadActionsPluginConfig {
  /** Lead-action type identifiers your front end fires (e.g. 'phone_click'). */
  types?: string[];
  /** Import path to a default-exported lead-action registry component
   *  (see "Lead Actions" → admin icons). e.g. '@/lead-actions-admin#default' */
  adminRegistry?: string;
}
```

### 自动跟踪操作

```ts
interface AutoTrackLeadActionsConfig {
  phoneClicks?: boolean; // tel: links
  emailClicks?: boolean; // mailto: links
  directionsClicks?: boolean; // map / directions links
  whatsappClicks?: boolean;
  telegramClicks?: boolean;
  formSubmits?: boolean;
}
```

传到 `<AnalyticsProvider autoTrackLeadActions={...}>` 在客户端上; 插件附加了点火匹配的 DOM 听器 `lead_action` 事件没有每个元素标记.

* * *

## 客户跟踪

所有客户出口都来自 `@focus-reactive/payload-plugin-analytics/client`。 。 。 .

### `<AnalyticsProvider>`

在应用根上挂一次. 注入提供者的脚本(gtag.js),跟踪路由变化,并给铅-动作登记器接线.

```tsx
<AnalyticsProvider
  provider={ga4Provider({ measurementId })}
  leadActionTypes={["phone_click", "cta_pricing_click"]} // optional
  autoTrackLeadActions={{ phoneClicks: true, formSubmits: true }} // optional
  trackRouteChanges // default: true
>
  {children}
</AnalyticsProvider>
```

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `provider` | `AnalyticsProvider` 适配器 | —— 说 | 通常情况下 `ga4Provider({ measurementId })` |
| `leadActionTypes` | `string[]` | —— 说 | 客户可用的铅行动类型 |
| `autoTrackLeadActions` | `AutoTrackLeadActionsConfig` | —— 说 | 用于共同牵头行动的自动附件 DOM 听众 |
| `trackRouteChanges` | `boolean` | `true` | 开火 `page_view` 在下一个.js客户端导航上 |

> 上马 **一次**. 筑巢 `<AnalyticsProvider>` 记录 dev 警告并导致重复 `page_view` 事件.

### `ga4Provider`

```ts
import { ga4Provider } from "@focus-reactive/payload-plugin-analytics/client";

const provider = ga4Provider({ measurementId: "G-XXXXXXX" });
```

返回 a `AnalyticsProvider` 装入的适配器 `gtag.js`,将事件推向 GA4 数据Layer,并报告页面浏览(带有标题+URL). 适配器接口很小——自己执行,以瞄准不同的后端:

```ts
interface AnalyticsProvider {
  readonly name: string;
  Scripts: () => ReactNode;
  trackEvent: (name: string, payload?: Record<string, unknown>) => void;
  pageView: (path: string) => void;
}
```

### `<Track>` - 申报活动

环绕 a **单人** 儿童元素并启动一个互动事件。 它与孩子的 现有处理器,所以你 `onClick`编号 :`onSubmit` 仍然运行.

```tsx
import { Track } from "@focus-reactive/payload-plugin-analytics/client";

<Track on="click" event="cta_click" payload={{ location: "hero" }}>
  <button onClick={doThing}>Get started</button>
</Track>;
```

`on` 接受 `"click" | "submit" | "view" | "hover"`。 。 。 . `on="view"` 当元素滚动到视图中时,发射一次.

### `<TrackLeadAction>` ——转换活动

一个薄薄的包裹 `<Track>` 点燃 `lead_action` 事件为 `fr_lead_type` 设置为 `type`。 。 。 .

```tsx
import { TrackLeadAction } from "@focus-reactive/payload-plugin-analytics/client";

<TrackLeadAction on="click" type="phone_click">
  <a href="tel:+1234567890">Call us</a>
</TrackLeadAction>;
```

### `useAnalytics()` - 必需的API

```tsx
import { useAnalytics } from "@focus-reactive/payload-plugin-analytics/client";

function ContactForm() {
  const { track, trackLeadAction, pageView } = useAnalytics();

  return (
    <form
      onSubmit={() => {
        trackLeadAction("form_submit", { form: "contact" });
      }}>
      {/* ... */}
    </form>
  );
}
```

| 方法 | 火灾 |
| --- | --- |
| `track(event, payload?)` | 自定义 GA4 事件 |
| `trackLeadAction(type, p?)` | `lead_action` 与 `fr_lead_type = type` |
| `pageView(path)` | 手册 `page_view` (很少需要——路线改变自动起火) |

### 事件名称

插件导出它依赖的 GA4 事件名常数 :

```ts
import {
  TRAFFIC_EVENTS, // page_view, session_start, first_visit, user_engagement
  ENGAGEMENT_EVENTS, // scroll, click, form_start, form_submit, video_start, ...
  LEAD_ACTION_EVENT_NAME, // 'lead_action'
  FR_LEAD_TYPE_PARAM, // 'fr_lead_type'
  BUILT_IN_LEAD_ACTION_TYPES,
} from "@focus-reactive/payload-plugin-analytics/client";
```

* * *

## 牵头行动

主要动作是转换仪表盘 **牵头行动** 选项卡。 它们都是同样的GA4事件—— `lead_action` ——以" the"为分 `fr_lead_type` 参数.

### 内建类型

```
phone_click · email_click · directions_click · whatsapp_click
telegram_click · website_click · booking_click · form_submit
```

### 自定义类型

在插件配置中声明您自己的类型( 所以仪表板知道要查询它们) , 并解雇客户端 :

```ts
// payload.config.ts
analyticsPlugin({
  ga4: {
    /* ... */
  },
  leadActions: {
    types: ["phone_click", "email_click", "form_submit", "cta_pricing_click"],
  },
});
```

```tsx
<TrackLeadAction on="click" type="cta_pricing_click">
  <button>See pricing</button>
</TrackLeadAction>
```

在仪表盘中,未知类型仍然带有人性化标签和倒置图标.

### 射击选项

| 方针 | 使用时间 |
| --- | --- |
| `<TrackLeadAction>` | 您控制元素并想要声明标记 |
| `useAnalytics().trackLeadAction()` | 从操作器起火 / 效果 |
| `autoTrackLeadActions` | B. 共同模式`tel:`, (中文(简体) ), `mailto:`,提交表格) |

自动跟踪尊重选择退出:添加 `data-analytics-skip` 到任何你不希望自动跟踪的元素.

### 管理图标和标签

定制铅-动作类型如何在登记簿中的仪表板(icon + 标签)中生成。 创建默认导出注册组件的客户端模块:

```tsx
// lead-actions-admin.tsx
"use client";

import { createLeadActionRegistry } from "@focus-reactive/payload-plugin-analytics/client";
import { Zap } from "lucide-react";

export default createLeadActionRegistry({
  cta_pricing_click: { icon: Zap, label: "Pricing CTA" },
});
```

然后点 `leadActions.adminRegistry` 在它上面( Payload 组件路径语法) :

```ts
analyticsPlugin({
  ga4: {
    /* ... */
  },
  leadActions: {
    types: ["cta_pricing_click"],
    adminRegistry: "@/lead-actions-admin#default",
  },
});
```

您的条目被合并到内置注册簿上, 因此您只声明您想要覆盖的内容 .

* * *

## 剪贴板和布局自定义

仪表板有三个内置标签:

| 标签 | 内建区块 |
| --- | --- |
| `overview` | `sessions-kpi`, (中文(简体) ), `users-kpi`, (中文(简体) ), `pageviews-kpi`, (中文(简体) ), `bounce-rate-kpi`, (中文(简体) ), `avg-duration-kpi`, (中文(简体) ), `trend-chart`, (中文(简体) ), `top-pages`, (中文(简体) ), `top-sources`, (中文(简体) ), `top-events`, (中文(简体) ), `devices-donut`, (中文(简体) ), `top-countries` |
| `lead-actions` | `total-leads-kpi`, (中文(简体) ), `conversion-rate-kpi`, (中文(简体) ), `avg-time-kpi`, (中文(简体) ), `lead-actions-by-type`, (中文(简体) ), `per-page-breakdown`, (中文(简体) ), `discovery-paths` |
| `sessions` | 会话列表 + 每次会话活动抽屉 |

### 重排、 重排大小、 隐藏

这个 `layout` 选项允许您覆盖每个标签的放置 。 每个区块的布置 `order`, (中文(简体) ), `colSpan`,以及 `enabled`; 每行都使用 `order`, (中文(简体) ), `columns`,以及 `enabled`。 。 。 .

```ts
analyticsPlugin({
  ga4: {
    /* ... */
  },
  layout: {
    tabs: {
      overview: {
        rows: {
          "kpi-row": {
            columns: 4,
            blocks: {
              "bounce-rate-kpi": { enabled: false }, // hide a block
              "sessions-kpi": { order: 0, colSpan: 1 }, // reposition / resize
            },
          },
        },
      },
    },
  },
});
```

内建行ID:概述 `kpi-row`, (中文(简体) ), `trend-row`, (中文(简体) ), `top-row`, (中文(简体) ), `devices-countries-row`; 牵头行动 `kpi-row`, (中文(简体) ), `by-type-row`, (中文(简体) ), `per-page-row`, (中文(简体) ), `journeys-row`。 。 。 .

### 自定义块

以 React 组件和可选服务器侧注册自己的块 `fetch` 与GA4客户端对撞 把它排入布局 像任何内置块.

```tsx
// payload.config.ts
import type { BlockFetchArgs } from "@focus-reactive/payload-plugin-analytics";

analyticsPlugin({
  ga4: {
    /* ... */
  },
  blocks: {
    "my-metric": {
      component: "@/blocks/MyMetric#default", // client component path
      fetch: async ({ dateRange, comparison, ga4, req }: BlockFetchArgs) => {
        const report = await ga4.runReport({
          /* GA4 Data API request */
        });
        return shapeForUi(report);
      },
    },
  },
  layout: {
    tabs: {
      overview: {
        rows: {
          "top-row": { blocks: { "my-metric": { order: 0, colSpan: 2 } } },
        },
      },
    },
  },
});
```

服务器结果通过 `/api/analytics/custom/my-metric` 并交给您的组件作为 `data`数字 :

```ts
interface BlockComponentProps<TData = unknown> {
  data?: TData;
  loading?: boolean;
  error?: Error;
  dateRange: DateRange;
  comparison: Comparison;
  colSpan: number;
  t: (key: string) => string;
  className?: string;
}
```

为了与内置外观相匹配,将仪表板的UI原始和查询钩从 `/client/blocks` 条目 :

```tsx
import {
  DataCard,
  KpiCard,
  BarList,
  TopNTable,
  DonutChart,
  TrendChart,
  SkeletonBlock,
  ErrorTile,
  useCustomBlockQuery,
} from "@focus-reactive/payload-plugin-analytics/client/blocks";
```

### 访问控制

把仪表板的终点 放在你自己的规则后面:

```ts
analyticsPlugin({
  ga4: {
    /* ... */
  },
  access: ({ req }) => Boolean(req.user) && req.user.role === "admin",
});
```

* * *

## A/B 标签

当你通过一个 `ab` 配置,仪表板得到一个 **A/B级** 选项卡,用于计算曝光率、转换率、升起率、统计意义、样本-比例-匹配率(SRM)和组合取胜率。 它读取 A/B 插件 `ab-experiments` 藏书加 `fr_ab_*` GA4维.

此标签被设计为配对 [`@focus-reactive/payload-plugin-ab`](https://www.npmjs.com/package/@focus-reactive/payload-plugin-ab)数字 :

1.  用AB插件运行 A/B 测试并挂载其 `<ExperimentTracker>` 在变种服务页上——邮票 `fr_ab_experiment`, (中文(简体) ), `fr_ab_variant`,以及 `fr_ab_visitor_id` 每个GA4事件.
2.  在GA4中登记这三个维度(见 [GA4 设置](https://npmcn.com/package/%40focus-reactive/payload-plugin-analytics/#readme-ga4-setup)) (中文(简体) ).
3.  在此启用标签 :

```ts
analyticsPlugin({
  ga4: {
    /* ... */
  },
  ab: {}, // presence of the key turns the tab on
});
```

A/B 标签上的转换相同 `lead_action` 事件作为仪表板的其余部分——没有单独的AB转换事件.

### 集成配置

```ts
interface AbIntegrationConfig {
  /** Slug of the AB plugin's experiments collection. Default: 'ab-experiments'. */
  experimentsCollectionSlug?: string;

  /** Override the GA4 dimension parameter names (must match what the tracker stamps). */
  dimensions?: { experiment?: string; variant?: string; visitorId?: string };

  /** Significance / SRM tuning. */
  stats?: {
    alpha?: number; // significance threshold. default 0.05
    power?: number; // statistical power (1 - beta). default 0.80
    srmThreshold?: number; // SRM chi-square failure threshold. default 0.001
    srmWindowDays?: number; // trailing window for the SRM check. default 7
  };

  /** Win-rate qualification. alpha/power inherited from `stats`. */
  winRate?: {
    mdeCeiling?: number; // qualifies when relative MDE ≤ this. default 0.20
    sessionFloor?: number; // per-bucket session floor. default 100
  };

  /** Map the AB plugin's field names if you customized them. */
  variantFields?: { variantOf?: string; passPercentage?: string; slug?: string; name?: string };
}
```

* * *

## 参考文献

| 导入路径 | 出口 |
| --- | --- |
| `@focus-reactive/payload-plugin-analytics` | `analyticsPlugin`; 配置类型(`AnalyticsPluginConfig`, (中文(简体) ), `Ga4Config`, (中文(简体) ), `AccessFn`, (中文(简体) ), `AutoTrackLeadActionsConfig`, (中文(简体) ), `AbIntegrationConfig`, (中文(简体) ), `LeadActionsPluginConfig`,...);查询/答复类型;布局类型(`BlockDefinition`, (中文(简体) ), `BlockFetchArgs`, (中文(简体) ), `BlockComponentProps`, (中文(简体) ), `AnalyticsLayoutConfigInput`,;事件+终点常数(`TRAFFIC_EVENTS`, (中文(简体) ), `ENGAGEMENT_EVENTS`, (中文(简体) ), `LEAD_ACTION_EVENT_NAME`, (中文(简体) ), `ANALYTICS_ENDPOINT_PATHS`组合 `BUILTIN_*` 编号) |
| `@focus-reactive/payload-plugin-analytics/client` | `AnalyticsProvider`, (中文(简体) ), `ga4Provider`, (中文(简体) ), `Track`, (中文(简体) ), `TrackLeadAction`, (中文(简体) ), `useAnalytics`, (中文(简体) ), `useLeadActionTypes`, (中文(简体) ), `createLeadActionRegistry`, (中文(简体) ), `LeadActionRegistryProvider`, (中文(简体) ), `useLeadActionRegistry`,事件常数+类型 |
| `@focus-reactive/payload-plugin-analytics/client/blocks` | 自定义块的 UI 原始文件 : `DataCard`, (中文(简体) ), `KpiCard`, (中文(简体) ), `BarList`, (中文(简体) ), `TopNTable`, (中文(简体) ), `DonutChart`, (中文(简体) ), `TrendChart`, (中文(简体) ), `SkeletonBlock`, (中文(简体) ), `ErrorTile`, (中文(简体) ), `EmptyTile`, (中文(简体) ), `SetupRequiredCard`; 钩子 `useCustomBlockQuery`, (中文(简体) ), `useSessionsQuery`, (中文(简体) ), `useSessionDetailQuery` |
| `@focus-reactive/payload-plugin-analytics/components/AnalyticsView` | 仪表板视图组件( 由插件自动注册) |
| `@focus-reactive/payload-plugin-analytics/components/AnalyticsView/AnalyticsHeaderLink` | 管理员头链接组件( 由插件自动注册) |
| `@focus-reactive/payload-plugin-analytics/admin.css` | Dashboard 样式表( 视图导入它本身; 曝光用于手动控制) |

* * *

## 许可证

麻省理工学院 [焦点反应](https://focusreactive.com/)

## 常见问题

### @focus-reactive/payload-plugin-analytics 是什么？

GA4 支持的分析插件 有效载荷CMS v3 \+ 下一个\.js\. 添加完整的分析仪表板 有效载荷管理员 ——KPI,流量,上页/出处/活动,设备,地理学,会话,出行,和铅-动作相通

### 如何安装 @focus-reactive/payload-plugin-analytics？

在项目目录运行 npm install @focus-reactive/payload-plugin-analytics，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：payload（^3\.0\.0）、recharts（^2\.15\.0）、lucide-react（^0\.469\.0）、@payloadcms/ui（^3\.0\.0）、@payloadcms/next（^3\.0\.0）、react-day-picker（^9\.0\.0）、@tanstack/react-query（^5\.59\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @focus-reactive/payload-plugin-analytics 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @focus-reactive/payload-plugin-analytics 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @focus-reactive/payload-plugin-analytics 可以商用吗？

@focus-reactive/payload-plugin-analytics 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @focus-reactive/payload-plugin-analytics 的下载量有多少？

根据 npm 官方下载统计，@focus-reactive/payload-plugin-analytics 在 2026/10/15 – 2026/11/13 这 30 天内被下载 2,597 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @focus-reactive/payload-plugin-analytics 还在维护吗？

最新版本 1\.2\.2 发布于 2026/07/08（4 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/06/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。