firebase-analytics

Firebase Analytics 技能

此技能介绍如何在 Flutter 应用中正确实现 Firebase Analytics，涵盖设置、事件记录、用户属性和数据收集最佳实践。

适用场景

在以下情况下使用此技能：

• 在 Flutter 项目中设置和配置 Firebase Analytics。
• 记录预定义或自定义分析事件。
• 设置用户属性或默认事件参数。
• 使用 GoRouter 或 Navigator 观察器实现屏幕浏览跟踪。
• 构建转化漏斗或跟踪用户流程。

---

1. 设置与配置

flutter pub add firebase_analytics
flutter run

import 'package:firebase_analytics/firebase_analytics.dart';

// After Firebase.initializeApp():
FirebaseAnalytics analytics = FirebaseAnalytics.instance;

• 使用任何 Firebase Analytics 功能前，先初始化 Firebase。
• Analytics 会自动记录部分事件和用户属性，无需为此编写额外代码。
• 在 iOS 上，如果应用不使用 IDFA（广告标识符），请使用不含 IDFA 的 Analytics 依赖项（Swift Package Manager 下的 FirebaseAnalyticsCore，或 CocoaPods 下的 FirebaseAnalytics/Core），而不是默认的 FirebaseAnalytics 依赖项，以避免 App Store 审核时被询问广告标识符相关问题：
  • **Swift Package Manager：**构建时设置 FIREBASE_ANALYTICS_WITHOUT_ADID=true（FIREBASE_ANALYTICS_WITHOUT_ADID=true flutter build ios）。

添加 Navigator 观察器以自动跟踪屏幕

MaterialApp(
  navigatorObservers: [
    FirebaseAnalyticsObserver(analytics: FirebaseAnalytics.instance),
  ],
);

对于 GoRouter，请在路由发生变化时手动记录屏幕浏览：

GoRouter(
  observers: [FirebaseAnalyticsObserver(analytics: FirebaseAnalytics.instance)],
);

验证清单

1. 确认在访问 FirebaseAnalytics.instance 前已完成 Firebase.initializeApp()。
2. 运行应用，并在 Firebase DebugView 控制台中检查收到的事件。
3. 确认自动事件（first_open、session_start）无需额外代码即可显示。

---

2. 事件记录

尽可能使用预定义事件方法，以便在报告中获得最详尽的信息，并使用未来的 Google Analytics 功能：

await FirebaseAnalytics.instance.logSelectContent(
  contentType: "image",
  itemId: itemId,
);

使用通用的 logEvent() 方法记录预定义和自定义事件：

await FirebaseAnalytics.instance.logEvent(
  name: "select_content",
  parameters: {
    "content_type": "image",
    "item_id": itemId,
  },
);

自定义事件示例 — 电商添加到购物车

Future<void> logAddToCart(String productId, String productName, double price) async {
  await FirebaseAnalytics.instance.logEvent(
    name: 'add_to_cart',
    parameters: {
      'product_id': productId,
      'product_name': productName,
      'price': price,
      'currency': 'USD',
    },
  );
}

• 事件名称区分大小写——仅大小写不同的名称会被视为两个不同的事件。
• 最多可使用 500 种不同的事件类型，但事件总量不受限制。
• 事件名称必须以字母开头，只能包含字母数字字符和下划线，且长度不得超过 40 个字符。

---

3. 参数与属性

• 参数名称：最多 40 个字符，必须以字母开头，且只能包含字母数字字符和下划线。
• 字符串参数值：最多 100 个字符。
• 前缀 firebase_、google_ 和 ga_ 为保留前缀——请勿用于参数名称。
• 每个事件最多可有 25 个自定义参数。
• 在 Analytics 控制台中注册自定义参数，才能在报告中将其用作维度或指标。

为所有后续事件设置默认参数（Web 不支持）：

await FirebaseAnalytics.instance.setDefaultEventParameters({
  'app_version': '1.2.3',
  'environment': 'production',
});

将默认参数设为 null，即可清除该参数。

---

4. 用户属性

await FirebaseAnalytics.instance.setUserProperty(
  name: 'favorite_food',
  value: favoriteFood,
);

设置用户 ID，以便关联不同设备上的事件：

await FirebaseAnalytics.instance.setUserId(id: 'user_12345');

• 使用用户属性前，请先在 Analytics 控制台中为其创建自定义定义。
• 每个项目最多可有 25 个自定义用户属性。
• 使用用户属性进行受众细分、报告筛选或 A/B 测试定位。

5. 最佳实践

• 收集用户数据前，请求必要的权限，尤其是在隐私控制严格的平台上。
• 切勿在事件或用户属性中记录敏感信息或个人身份信息。
• 使用一致的命名约定（snake_case）为自定义事件和参数命名。
• 将相关事件分组，以跟踪用户流程和转化漏斗。
• 开发期间，在 Firebase 控制台中使用 DebugView — 在实体设备上通过以下方式启用：
  • Android： adb shell setprop debug.firebase.analytics.app <package_name>
  • iOS： 在 Xcode 的方案参数中添加 -FIRDebugEnabled。
• 部署到生产环境之前，测试分析功能的实现，确认事件会显示在 DebugView 中。

---

参考资料

• FlutterFire GitHub 仓库