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

GA4 支持的分析插件 有效载荷CMS v3 + 下一个.js. 添加完整的分析仪表板 有效载荷管理员 ——KPI,流量,上页/出处/活动,设备,地理,会话,出行,和铅-动作转换——外加一个小客户端-侧跟踪层为您前端. 可选 A/B 分析标签集成 @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(如. 123456789GA4 管理 地产设置 .

2. 为 Data API 创建服务账户

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

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

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

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

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

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

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

5. 向插件提供值

# .env
GA4_MEASUREMENT_ID=G-XXXXXXX
GA4_PROPERTY_ID=123456789
[email protected]
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和图表作为 同行依赖关系 所以它和你的应用分享一份 与所需的端点一起安装插件 :

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

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

快速启动

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

// 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() 返回服务商对象,所以包装器必须是客户端组件。 创建一次并挂载在您的应用程序的根上:

// 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>;
}

// 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收集了事件,且服务账户有财产访问,数据就会出现.

配置参考

插件选项

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 图形

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 如果服务账户证书缺失,则需要发出警告.

铅行动

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;
}

自动跟踪操作

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),跟踪路由变化,并给铅-动作登记器接线.

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

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

ga4Provider

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

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

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

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

<Track> - 申报活动

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

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。 。 。 .

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

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>
  );
}

事件名称

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

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

自定义类型

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

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

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

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

射击选项

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

管理图标和标签

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

// 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 组件路径语法) :

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

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

剪贴板和布局自定义

仪表板有三个内置标签:

重排、 重排大小、 隐藏

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

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客户端对撞 把它排入布局 像任何内置块.

// 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数字 :

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 条目 :

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

访问控制

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

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数字 :

1. 用AB插件运行 A/B 测试并挂载其 <ExperimentTracker> 在变种服务页上——邮票 fr_ab_experiment, (中文(简体) ), fr_ab_variant,以及 fr_ab_visitor_id 每个GA4事件.
2. 在GA4中登记这三个维度(见 GA4 设置) (中文(简体) ).
3. 在此启用标签 :

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

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

集成配置

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 };
}

参考文献

许可证

麻省理工学院 焦点反应