跨平台事件跟踪：为 Web、iOS 和 Android 提供统一的事件目录

如果你的 Web 团队把它叫做 “purchase_completed”，iOS 团队把它叫做 “orderPlaced”，Android 团队又把它叫做 “buy_event”，那你拥有的并不是分析——而是三个互不兼容的数据孤岛。跨平台事件跟踪始于一套共享的词汇表，而这正是产品分析中最棘手的问题之一，因为它需要在团队、代码库和发布周期之间进行协调。

Gurulu 通过一个标准事件目录解决了这一问题：一套由 18 个事件组成的标准化集合，在 Web、iOS 和 Android 上的行为完全一致。每个事件都有类型化的 Schema、平台专属的 SDK 辅助方法，以及针对遗留事件名的自动规范化。本指南将带你了解该目录、各 SDK 以及配置流程。

事件不一致带来的问题

当各平台的事件名不一致时，下游的每个系统都会崩坏。横跨 Web 和移动端的漏斗无法构建，因为各步骤的名称不同。归因模型会少算转化，因为 iOS 上的一笔购买在以 Web 为中心的模型里是不可见的。CRM 分群会排除移动端用户，因为符合条件的事件在其平台的命名空间中根本不存在。而当产品经理问“有多少用户完成了新手引导？”时，数据团队要花两天时间去协调三套不同的事件 Schema，然后才能给出答案。

其根本原因几乎总是相同的：每个平台团队都各自独立地埋点，没有共享的规范。等到有人察觉到这种不一致时，已经有数月的历史数据被锁死在互不兼容的 Schema 中了。

Gurulu 的标准事件目录

Gurulu 定义了 18 个标准事件，每个都以 $ 为前缀，以便与自定义事件区分。这些事件覆盖了核心用户生命周期：获取、激活、参与、变现和留存。每个 Gurulu SDK——Web、iOS 和 Android——都以完全相同的名称、完全相同的属性 Schema 和完全相同的语义实现这些事件。

// Gurulu Canonical Events (subset of 18)
$page_view    // Web, iOS, Android
$session_start
$sign_up
$login
$purchase
$add_to_cart
$search
$share
$app_install  // iOS, Android only
$first_open   // iOS, Android only

类型化 SDK 辅助方法

每个 SDK 都为标准事件提供类型化的辅助函数。你无需传入原始字符串并寄望属性名能对上，而是可获得编译期检查和自动补全。SDK 会在运行时校验属性类型，并在开发模式下于缺失必填属性时记录警告。这能在埋点缺陷进入生产环境之前就将其捕获。

// Web (JavaScript)
import { gurulu } from '@gurulu/web';
gurulu.track('$purchase', {
  value: 49.99,
  currency: 'USD',
  items: [{ id: 'sku_001', name: 'Pro Plan' }],
});

// iOS (Swift)
import GuruluSDK

Gurulu.track("$purchase", properties: [
  "value": 49.99,
  "currency": "USD",
  "items": [["id": "sku_001", "name": "Pro Plan"]]
])

// Android (Kotlin)
import io.gurulu.sdk.Gurulu

Gurulu.track("\$purchase", mapOf(
  "value" to 49.99,
  "currency" to "USD",
  "items" to listOf(mapOf("id" to "sku_001", "name" to "Pro Plan"))
))

请注意，事件名、属性键和属性类型在三个平台上完全一致。当这些事件抵达 Gurulu 的接入端点时，无论来源如何，都会以相同的 Schema 存储。漏斗、归因和 CRM 分群无需任何额外映射即可跨平台运作。

规范化映射

如果你已有的代码库中存在非标准的事件名，无需一次性重写所有埋点。Gurulu 支持规范化映射：一项配置，可自动将传入的事件名转换为其标准对应名称。你可以在控制台的“设置”下定义映射，也可以通过 API 定义。

// Normalization mapping examples
order_completed    → $purchase
signed_up          → $sign_up
item_added_to_cart → $add_to_cart
page_loaded        → $page_view
user_registered    → $sign_up

规范化发生在接入时、事件存储之前。这意味着从你启用映射的那一刻起，历史数据就会使用标准名称，即便你的代码仍在发送旧名称。随着时间推移，你可以将埋点迁移为直接使用标准名称，并移除这些映射。

搭建跨平台跟踪

第一步：在每个平台上安装 Gurulu SDK。Web SDK 是一个 script 标签或 npm 包。iOS SDK 可通过 Swift Package Manager 或 CocoaPods 获取。Android SDK 位于 Maven Central 上。每个 SDK 都用你的站点 ID 和令牌进行初始化，并自动跟踪页面浏览、会话开始和应用生命周期事件。

第二步：使用标准名称为你的关键事件埋点。先从对业务最重要的事件入手——通常是 $sign_up、$purchase 和 $add_to_cart。使用类型化辅助方法以确保一致性。不要试图一次性为全部 18 个事件埋点；先从转化漏斗开始，再逐步扩展。

第三步：为任何无法立即重命名的遗留事件配置规范化映射。这样在你逐步迁移代码库的同时，仍可获得跨平台的统一分析。大多数团队会在两到四个冲刺内完成迁移，每次专注于一个平台。