Flutter中Firebase Analytics设置用户ID及属性的问题排查

问题背景 #

• 目标：在Flutter应用交互时保存用户ID及其属性
• 问题：事件能成功记录，但调试模式下及等待24-48小时后，控制台仍看不到用户ID及属性详情
• 已操作：已在用户范围的Custom definitions中定义了要保存的属性

排查与解决步骤 #

1. 验证setUser方法的调用时机 #

确保setUser在用户登录成功后立即调用，且调用逻辑未被条件分支跳过。比如在登录接口返回成功后执行：

void onLoginSuccess(String userId, String userName) {
  AnalyticsClass().setUser(userId, userName);
}

若调用时机过晚，后续事件可能无法关联用户属性。

2. 用调试视图实时校验 #

开启设备调试模式，在Firebase控制台的DebugView中实时查看事件是否携带用户ID和属性：

# Android设备
adb shell setprop debug.firebase.analytics.app 你的应用包名
# iOS设备
defaults write 你的应用BundleID firebase.analytics.debugMode YES

如果DebugView里也没有用户数据，说明代码层面的设置存在问题。

3. 检查用户属性命名与值的合规性 #

Firebase对用户属性有严格限制：

• 名称不能含空格、特殊字符（下划线除外），长度不超24字符，不能以firebase_/google_开头
• 属性值长度不能超36字符（字符串类型）
  你的referral命名合规，但要确保传入的值符合长度要求。

4. 确认Custom Definitions配置正确性 #

在Firebase控制台的Analytics > Custom Definitions > User Properties中：

• 确保属性名称与代码中setUserProperty的name参数完全一致（区分大小写）
• 确认属性Scope设置为User，状态为Active
  注：自定义属性创建后，标准报告显示需等待，但DebugView能实时查看。

5. 优化异步调用顺序 #

用Future.wait确保setUser中的两个异步操作都完成后，再触发事件：

setUser(String id, name) async {
  await Future.wait([
    fa.setUserId(id: id),
    fa.setUserProperty(name: 'referral', value: "test new : $name")
  ]);
}

避免因异步操作未完成就触发事件，导致事件无法关联用户属性。

6. 升级Firebase SDK版本 #

确保firebase_analytics依赖为最新稳定版，旧版本可能存在用户属性同步bug。更新pubspec.yaml：

dependencies:
  firebase_analytics: ^最新稳定版本号

执行flutter pub get完成更新。

7. 校验用户ID的有效性 #

确保传入setUserId的id不为空字符串或null（resetUser场景除外），空ID会导致Firebase不记录用户标识。

代码优化建议 #

可在buttonTap中直接携带参数，快速验证数据传递是否正常：

buttonTap(id, name) async {
  await fa.logEvent(
    name: 'button_tap',
    parameters: {
      'user_id': id,
      'referral': "test new : $name"
    }
  );
}

内容的提问来源于stack exchange，提问作者Manish