配置 Firebase 上报

本文旨在介绍如何设置 Firebase 分析平台，让您的游戏可以直接将分析数据上报至 Firebase。

需要设置 Firebase

在构建项目之前，请确保您已按照下方的 Firebase 设置步骤进行操作，以避免应用启动时崩溃。

说明

Firebase 需运行在 Android 4.0 及以上，设备也需安装 Google Play Services 11.0.2 及以上版本。

前提条件

注意

Firebase 支持多商店渠道包，同一开发者账号下可以创建多个 app。只需要在同一个 Firebase 项目下填新的渠道包名和对应签名配置，并通过重复以下步骤完成额外游戏应用的配置。

1. 注册 Firebase 项目

在 Firebase Console 页面根据提示注册 Firebase 项目。

图片: Register Firebase project

2. 添加应用

注意

在 Firebase Console 的 Project Overview 页面，添加对应平台的 Firebase 应用。
根据提示添加相应的资料。
添加 Android 应用。
1. 填写信息后，点击 REGISTER APP。
  如果部分字段不确认，可以后续在设置中补充。
2. 下载 google-services.json 文件备用，后续也可以在 Firebase Console 重新下载。
3. 跳过其他步骤。
添加 iOS 应用。
1. 填写信息后，点击 REGISTER APP。
  如果部分字段不确认，可以后续在设置中补充。
2. 下载 google-services.json 文件备用，后续也可以在 Firebase Console 重新下载。
3. 配置推送功能的 APN 证书。

3. 上传 iOS APNs 证书

在 Settings 页面，点击 CLOUD MESSAGING 并找到 iOS 项目。
分别添加 开发证书 和 正式证书。

详细信息，请参见设置 Apple 平台客户端。

4. 项目配置

在 Project settings 中可以继续设置项目信息，下载 google-services.json 和 GoogleService-Info.plist ，或者配置好 Android 证书指纹。

Image: Firebase Project Settings

接入 Player Network SDK。

步骤1：设置权限和配置

Android

用户权限

警告

由于 Firebase SDK 只兼容 minSdkVersion >= 19，所以在 Android 4.2 以下系统上运行可能会存在问题，需要游戏设置 minSdkVersion >= 19。

Firebase 需要访问网络的权限。

<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

工程配置

在 INTLConfig.ini 文件中配置 Android client key。

[Google]
GOOGLE_CLIENT_KEY_ANDROID = {YOUR_CLIENT_KEY_ANDROID}

替换 {YOUR_CLIENT_KEY_ANDROID} 为 Player Network SDK 需要的 Web client key，配置 API OAuth 时在 Credentials 页面的网页客户端对应的客户端 ID。即 OAuth 2.5 后台 API 配置的建立 OAuth 操作中的 Server Client ID。

google-services.json

警告

没有 google-services.json 文件会导致打包失败。

Gradle 打包方式支持从 google-services.json 文件直接读取内容，转化成对应的 app/build/generated/res/google-services/{build_type}/values/values.xml 配置文件。

Unity
Unreal Engine

有关在项目的 Assets/Plugins/Android/ 目录下添加 google-services.json 文件的更多详情，请参见 The Google Services Gradle Plugin。

iOS

工程配置

Firebase Plist

警告

没有 GoogleService-info.plist 文件会导致启动崩溃。

将配置文件 GoogleService-info.plist 放在 Assets/Plugins/iOS/INTLSDK/INTLFirebase/ThirdSDK/ 目录下。

图片：Unity Plist File

[可选] Unity 引擎导出 Xcode

在导出 Xcode 工程前，需先完成 .projmods 文件的配置。

Player Network SDK 已经将以下配置写入 INTLFirebaseKit.projmods 文件中，业务只需确保信息正确无误。

{
    "group": "INTL",
    "libs": [],
    "frameworks": [],
    "files": [
        "Plugins/iOS/INTLSDK/INTLFirebase/GoogleService-Info.plist"
    ],
    "folders": [],
    "excludes": [],
    "headerpaths":[],
    "build_settings": {},
    "system_capabilities": {"com.apple.Push":"TRUE"},
    "Info.plist":{},
}

有关 Xcode 工程导出的更多信息，请参见 Player Network SDK XUPorter 解决方案。

[可选] Private Set Membership

Private Set Membership (PSM) 是一种密码学技术，可用于验证用户数据是否包含在另一方持有的大型数据集之中，而无需透露数据本身或学习关于数据集的任何其他信息，从而提高 iOS 应用广告的可观察转化次数。

从 Player Network SDK V1.19.00 开始，iOS 客户端接入了 Google PSM 功能，以增加更准确的玩家信号量，提升广告买量效果。

PSM 功能默认是关闭的，若要开启功能，需先开启获取各渠道登录玩家邮箱的权限。下列第三方登录渠道在 Player Network SDK 支持 PSM 功能：

获得权限后，在 INTLConfig.ini 文件的 Firebase 节点下增加以下配置：

ANALYTICS_FIREBASE_REPORT_EMAIL = 1

打开 PSM 功能后会在玩家登录新账号的时候，通过 Firebase 提供的接口上报玩家的邮箱到 Google 的服务器，由 Google 后台进行广告转化率的计算。要验证 PSM 功能，请参见验收用例 4。

更多关于 PSM 的信息，请参见衡量 iOS 应用广告系列的 Google Ads 转化次数。

步骤2：异步获取 instanceId

注意

由于 Firebase 的 instanceID 获取是异步操作，因此调用 getInstanceID 可能返回空值。建议采用异步方式获取 instanceId。

Unity
Unreal Engine

INTLAPI.ExtendInvoke("Firebase", "getInstanceIDAsync", "");
INTLAPI.AddExtendResultObserver(OnExtendEvent);
void OnExtendEvent(INTLExtendResult ret)
{
   //Extend 回调
}

INTLWrapper::Instance()->ExtendInvoke("Firebase", "getInstanceIDAsync", "").c_str();

//需要在子类中实现
AnalyticsWindow.h
virtual void UAnalyticsWindow::OnExtendResult_Implementation(FINTLExtendResult ret) {
   //Extend 回调
}

步骤3：配置事件上报

警告

Firebase 会采集玩家设备的 Android ID。如果需要关闭对 Android ID 的采集，请参见停用 SSAID 收集。

事件是游戏中您要衡量的重要事件，每个游戏最多可以报告500种不同类型的事件，并且最多可以将25个唯一参数与每种事件类型相关联。您可以为您的游戏自定义事件类型。

每个事件类型都由一个唯一的名称标识。事件名称最长可达40个字符，只能包含字母数字字符和下划线（“_”），并且必须以字母字符开头。“firebase_”，“google_” 和 “ga_” 前缀是保留的，不应使用。

更多信息，请参见 FirebaseAnalytics.Event 文档。

手动报告事件

上报事件中注册自定义 key-value 参数，在 Firebase 管理端点击 Manage Custom Definitions。

图片: Key Value

自定义参数注册成功后显示效果如下：

图片: Key Value

漏斗事件

注意

从 Player Network SDK V1.20 开始支持。

在 INTLConfig.ini 的 ANALYTICS_REPORT_FUNNEL_CHANNEL 配置中增加 Firebase 渠道，Player Network SDK 会将漏斗事件同步上报至 Firebase 渠道。

[ANALYTICS]
ANALYTICS_REPORT_FUNNEL_CHANNEL = Firebase

可以参考管理端查看上报事件查看上报事件。

崩溃查看

警告

从 Player Network SDK V1.17 或以上不再支持。

步骤4：初始化分析模块

Unity
Unreal Engine

初始化分析模块，再调用 ReportEvent 开始 Firebase 上报数据。

数据上报验收

文档参考

数据维度

Firebase 事件：

自动收集事件：first_open、session_start、screen_view 等
推荐事件：level_start、level_end
将这些事件添加到您的网站或移动应用程序中有助于您衡量其他功能和行为，并生成更有用的报告。由于这些事件需要额外的上下文才能有意义，因此它们不会由全局站点标签自动发送。
自定义事件：ReportEvent
通过 API 自定义 eventname 的事件

更多信息，请参见事件与属性。

管理端查看上报事件

警告

事件非实时上报，延迟为1小时以上。

访问 Firebase 管理端查看上报事件。

图片: Firebase Event View

开启调试模式查看上报事件

通常，Firebase 所记录的事件会每隔1小时左右集中起来作为一批进行处理，并一起进行上传。此方法能节省最终用户设备的耗电量，并减少网络流量的消耗。为了以最短的延迟验证事件上报情况，可以在开发设备上启用调试模式。

更多关于开启调试模式的信息，请参见 Firebase 开启调试模式。

iOS
Android

注意

测试模式下延迟为20秒左右。

在 Firebase 控制台中查看事件：

在 Firebase 控制台，选择 DebugView.
选择对应的机型查看上报事件。

在 Xcode 调试控制台中查看事件：

在 Xcode 中，点击产品 > 方案 > 编辑方案。
从左侧菜单中选择 Run。
选择 Arguments 标签。
在 Arguments Passed On Launch 部分中，添加 -FIRAnalyticsDebugEnabled。

注意

测试模式下延迟为5秒左右。

执行 bash adb shell setprop debug.firebase.analytics.app {package_name} 命令
在 Firebase 控制台， DebugView 页面选择对应的机型

注意

调试模式将保持启用状态，直至您通过以下命令行明确停用调试模式：
bash adb shell setprop debug.firebase.analytics.app .none.

验收用例 1

子功能模块：Reporting
特性点：Event Reporting
测试点：Firebase 事件信息上报成功
前提条件：初始化分析模块
操作步骤/输入
1. 请求 ReportRevenue
2. eventName = Report_Event, paramsDic-key1=k1, paramsDic-value1=v1, paramsDic-key2=k2, paramsDic-value2=v2, spChannels=Firebase
3. 卸载安装 SDK 并启动游戏
4. 进入管理端点击 Events 查看上报 first_open events 事件
预期输出信息上报成功，检查如下：
管理端查看：Firebase 可以查到上报的事件，查询设置的参数
1. 打开 app 检查 session_start events: Reported qty+1
  检查：eventName = Report_Event, paramsDic-key1=k1, paramsDic-value1=v1, paramsDic-key2=k2, paramsDic-value2=v2, spChannels = Firebase
2. 卸载安装 first_open event 事件上报数量 +1，查看卸载安装检查 first_open events：事件：上报数量 +1
  检查：sDic-value2=v2 spChannels = Firebase

验收用例 2

子功能模块：ReportRevenue
特性点：Firebase 支付事件上报
测试点：请求 ReportRevenue 后查询上报（Firebase）
前提条件：网络连接正常
- 操作步骤/输入
1. 请求 ReportRevenue
2. eventName = （可自定义）, spChannels = Firebase, Currency = USD, Revenue = 100
3. Firebase 查询上报事件
4. DD平台查询 AnalyticsReportRevenue 事件
预期输出信息上报成功，检查如下：
1. 联网后 Firebase 相关事件统计 +1，点击事件详情展示可展示 USD100 相关 value
2. DD平台成功查询 methodName 为 AnalyticsReportRevenue 与 method_id=715 事件上报

验收用例 3

子功能模块：ReportRevenue
特性点：Firebase 支付事件上报
测试点：断网状态下请求 ReportRevenue 后查询上报（Firebase）
前提条件：断开网络状态
操作步骤/输入
1. 请求 ReportRevenue
2. eventName = （可自定义）, spChannels = Firebase, Currency = USD, Revenue = 1000
3. 重新连接网络
4. Firebase 查询上报事件
5. DD平台查询 AnalyticsReportRevenue 事件
预期输出信息上报成功，检查如下：
1. 联网后 Firebase 相关事件统计 +1，点击事件详情展示可展示 USD100 相关 value
2. DD平台成功查询 methodName 为 AnalyticsReportRevenue 与 method_id=715 事件上报

验收用例 4

子功能模块：Reporting
特性点：iOS 端 PSM 上报
测试点：初始化 PSM
前提条件：PSM 功能已开启
操作步骤/输入
1. 使用 Xcode 打开游戏的 iOS 工程，开启调试模式。
2. 从测试手机上删除已安装的游戏 app。
3. 使用 Xcode 重新安装游戏 app。
4. 使用已开启获取邮箱权限的渠道账号登录游戏。
5. 参考使用 Google Analytics 启动设备上转化衡量，确认 PSM 是否已经正常初始化。
预期输出信息上报成功，在 Xcode 的日志输出界面里检查是否存在下列任何一条信息：
- On-device conversion measurement found a match
- On-device conversion measurement did not find a match.

若有多个登录渠道需要使用 PSM 上报邮箱，请重复步骤2至5。

错误码

更多信息，请参见 Firebase Docs。

前提条件​

步骤1：设置权限和配置​

Android​

google-services.json​

iOS​

Firebase Plist​

[可选] Unity 引擎导出 Xcode​

[可选] Private Set Membership​

步骤2：异步获取 instanceId​

步骤3：配置事件上报​

手动报告事件​

漏斗事件​

崩溃查看​

步骤4：初始化分析模块​

数据上报验收​

文档参考​

数据维度​

管理端查看上报事件​

开启调试模式查看上报事件​

验收用例 1​

验收用例 2​

验收用例 3​

验收用例 4​

错误码​