一、开发者平台配置

1.1 注册项目

在 Firebase 控制台 页面注册项目，根据提示完成 Firebase 项目注册。

1.2 添加应用

1）在 Firebase 控制台主页（Project Overview），添加对应平台的 Firebase 应用

2）并根据提示添加相应的资料

3）添加 Android 应用

1.填写信息后，注册 App。如果部分字段不确认，可以后续在设置中补充；
2.下载 google-services.json 文件，备用。后续也可以在 Firebase 控制台重新下载；
3.跳过其他步骤；

4）添加 iOS 应用

1.填写信息后，注册 App。如果部分字段不确认，可以后续在设置中补充；
2.下载 GoogleService-Info.plist 文件，备用。后续也可以 Firebase 控制台重新下载；
3.跳过其他步骤；

1.3 上传 iOS APNs 证书

1）在项目 设置 页面 云消息传递 菜单，找到 iOS 项目

2）分别添加 开发证书 和 正式证书

更多详细信息请参考 Google Firebase 文档说明：
https://firebase.google.com/docs/cloud-messaging/ios/certs

二、 Android工程配置

2.1 google-services.json 文件配置

1）gradle 打包方式

gradle 打包方式，支持从 google-services.json 文件直接读取内容，转化成对应的配置文件（app/build/generated/res/google-services/{build_type}/values/values.xml）。参考官网说明https://developers.google.com/android/guides/google-services-plugin 配置如下几步：

• 添加 google-services.json 文件

将 google-services.json 文件放在项目的根目录下。

• 在项目的 build.gradle 文件中加入

apply plugin: 'com.google.gms.google-services'
// ...
dependencies {
    classpath 'com.google.gms:google-services:4.2.0'
    // ...
}

2）手动配置方式

根据 Firebase 官网生成的 google-services.json 文件，也可以手动配置这些资源内容。修改资源工程 Plugins/Android/gcloudsdk-msdk-firebase/res/values/values.xml 目录下的文件中 string 配置。

<!-- 均可在 google-services.json 中找到对应的值-->
<string name="gcm_defaultSenderId">{project_number}</string>
<string name="firebase_database_url">{firebase_url}</string>
<string name="google_storage_bucket">{storage_bucket}</string>
<string name="google_app_id">{mobilesdk_app_id}</string>
<string name="google_api_key">{current_key}</string>
<string name="google_crash_reporting_api_key">{current_key}</string>
<string name="default_web_client_id">{other_platform_oauth_client : client_id}</string>

注意：编译器会自动填充com.crashlytics.android.build_id字段，无需关注。

项目配置：

< gcm_defaultSenderId 为数字，对应 json 文件中的 project_number； < firebase_database_url 为 URL 链接字符串，对应 json 文件中的 firebase_url； < google_storage_bucket 为字符串，对应 json 文件中的 storage_bucket；

{
  "project_info": {
    "project_number": "263738xxxxxx",
    "firebase_url": "https://msdk-xxxx.firebaseio.com",
    "storage_bucket": "msdk-xxxx.appspot.com"
  }
}

应用相关配置：

< google_app_id 为字符串，对应 json 文件中的 mobilesdk_app_id； < google_api_key、google_crash_reporting_api_key 相同，为字符串，对应 json 文件中的 current_key； < default_web_client_id 为字符串，对应 json 文件中的 client_id；

"client": [
{
  "client_info": {
    "mobilesdk_app_id": "1:263738xxxxxx:android:cc76b90af5xxxxxx"
  },
  "api_key": [
    {
      "current_key": "AIzaSyCmNTRpx-0B5TEFFMxxxxxxxxxxxxxx"
    }
  ],
  "services": {
    "appinvite_service": {
      "status": 2,
      "other_platform_oauth_client": [
        {
          "client_id":"263738xxxxxx-vjemk2j6amh7irxxxxxxxxxxxx.appsgoogleusercontentcom",
          "client_type": 3
        }
// ...

2.2 修改第三方依赖库的 AndroidManifest.xml 修改应用包名

1. firebase-common-xxx(xxx 表示当前使用的 firebase 版本) 目录下 AndroidManifest.xml 配置文件中修改应用包名。

   <provider
    android:name="com.google.firebase.provider.FirebaseInitProvider"
    android:authorities="{applicationId}.firebaseinitprovider"
    android:exported="false"
    android:initOrder="100" />
   

[info] ${applicationId} 需要修改为应用包名

1. 【17.0.0 版本以下需要】firebase-iid-xxx(xxx 表示当前使用的 firebase 版本) 目录下 AndroidManifest.xml 配置文件中修改应用包名。

   <permission android:name="${applicationId}.permission.C2D_MESSAGE"
     android:protectionLevel="signature" />
   <uses-permission android:name="${applicationId}.permission.C2D_MESSAGE" />
   <receiver
     android:name="com.google.firebase.iid.FirebaseInstanceIdReceiver"
     android:exported="true"
     android:permission="com.google.android.c2dm.permission.SEND" >
     <intent-filter>
         <action android:name="com.google.android.c2dm.intent.RECEIVE" />
         <action android:name="com.google.android.c2dm.intent.REGISTRATION" />
         <category android:name="${applicationId}" />
     </intent-filter>
   </receiver>
   

[info] ${applicationId} 需要修改为应用包名

2.3 【可选】配置默认通知栏的图标以及颜色

1）默认通知栏图标

在推送消息时，如果指定图标，则使用该图标最为默认图标。

  <!-- Set custom default icon. This is used when no icon is set for incoming notification messages.
       See README(https://goo.gl/l4GJaQ) for more. -->
  <meta-data
     android:name="com.google.firebase.messaging.default_notification_icon"
     android:resource="@drawable/ic_stat_ic_notification" />

[info] drawable 可以放置到 Unity 的 Assets/Plugins/Android/ 目录下的 Android 工程目录下。如： xxx/res/drawable。

2）默认通知栏背景颜色

在推送消息时，如果没有指定消息颜色，则使用该颜色作为默认颜色。

  <!-- Set color used with incoming notification messages. This is used when no color is set for the incoming
     notification message. See README(https://goo.gl/6BKBk7) for more.-->
   <meta-data
      android:name="com.google.firebase.messaging.default_notification_color"
      android:resource="@color/colorAccent" />

[info] color 可以放置到 Unity 的 Assets/Plugins/Android/ 目录下的 Android 工程目录下资源文件中定义。如： xxx/res/values/colors.xml 文件中。

三、iOS工程配置

3.1 处理 Firebase plist 文件

添加配置文件 GoogleService-info.plist 至 Xcode 工程。

• unity 工程：替换 Plugins/iOS/GCloudSDK/MSDKFirebase/ThirdSDK 路径下 GoogleService-info.plist 文件
  

• UnrealEngine 工程：替换 MSDKFirebase/Source/MSDKFirebase/lib/iOS/Third/MSDKFirebase/Protobuf.embeddedframework.zip 路径下 GoogleService-info.plist 文件

3.2 打开 Xcode 推送

使用 Xcode 8 及以上版本编译时，打开 Capabilites/Push Notification 功能。

3.3 系统库依赖

• 添加下列系统库：
  • UserNotification.framework
  • StoreKit.framework
  • AdSupport.framework （Firebase官方文档推荐添加）

3.4 Unity XUPoter 的 xx.projmods 文件的配置

Unity 导出 XCode 工程时，需要配置 projmods 文件，使得导出的 XCode 工程能得到以上所述的配置。

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

四、功能说明

4.1 推送功能

1）TAG 标签功能

[info] MSDK 的 Push 模块中的打 Tag 就是 Firebase 的 topic 功能。

TAG (topic) 功能是给用户打标签。应用可以跟进运营需求，做相应的活动功能。

topic 字段定义需要满足如下条件：[a-zA-Z0-9-.~%]{1,900}，即为：大小写字面、数字、横线 "-"、下划线 "" 等字符的组合。

最佳实践：

1. 可以在用户首次购买点券的时候标记用户为付费用户。

   MSDKPush.SetTag("paid");
   

2. 在 Firebase 后台针对付费用户推送消息。

   

[warning] 由于网络、系统异常的情况，无法保障 TAG 100% 正确。

2）本地推送功能

[warning] MSDK 从 V5.30.001 版本开始，新增 Android 本地推送功能。

可在游戏未运行的情况下添加本地推送，用户点击推送后可拉起指定的 activity，若未指定则拉起默认 mainActivity。

支持消息展示和消息被点击的回调，请确保已按照指引注册过回调：注册回调。

使用说明：

• 使用 Firebase 本地推送功能需要先注册过 Firebase 渠道，请先根据相关指引注册推送和注销推送 进行渠道注册。

• 需要设置通知渠道，请在 Androidmanifest 中，加入以下配置

        <meta-data
            android:name="LOCAL_PUSH_CHANNEL"
            android:value="MSDK-Test"
            />
        <meta-data
            android:name="LOCAL_PUSH_CHANNEL_ID"
            android:value="MSDK-Test"
            />

该配置为适配 API 26 及以上的设备，若未配置该字段，则默认 APP 在 API 26 及以上设备的通知渠道名称为 MSDK-Firebase。更多关于通知渠道，请参考 Android 官方文档：创建和管理通知渠道。

• 需要在进程杀死的情况下正常收到推送消息，需要业务指引用户开启 APP 的自启动权限，不同手机厂商的 rom 不同，对应的功能页面不一致，需针对不同的手机厂商做适配。

4.2 统计功能

1）开启调试模式

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

• 要在 Android 模拟设备上启用 Analytics“调试”模式，请执行以下命令行：

  adb shell setprop debug.firebase.analytics.app {package_name}

  “调试”模式将保持启用状态，直至您通过以下命令行明确停用“调试”模式：

  adb shell setprop debug.firebase.analytics.app .none.

• 要在 Xcode 调试控制台中查看此事件，请启用 Analytics 调试：

  1. 在 Xcode 中，依次选择 Product > Scheme > Edit scheme...；
  2. 从左侧菜单中选择 Run；
  3. 选择 Arguments 标签；
  4. 在 Arguments Passed On Launch 部分中，添加 -FIRAnalyticsDebugEnabled；

• 查看报告，在开发设备上启用“调试”模式之后，请跳转到 Firebase 管理端。

  

2）上报事件查看

请跳转到 Firebase 管理端。

上报事件中自定义 key-value 参数需要业务去 Firebase 管理端 对应事件中注册。
自定义参数注册成功后显示效果如下：

3）管理用户意见征求设置

如果开发者为应用维护 Google Analytics（分析）并希望集成意见征求模式，请参阅本页内容： https://developers.google.com/tag-platform/security/guides/app-consent?platform=android&hl=zh-cn#upgrade-consent-v2

1. 配置默认值

   请参考 Google 文档进行配置（注意：查阅英文版本，中文翻译版本信息滞后）

   • Android ： https://developers.google.com/tag-platform/security/guides/app-consent?platform=android#initial_setup

     Android 需要配置在应用的 AndroidManifest.xml 文件中，参考配置 （业务需要根据自身情况进行调整）：

     <meta-data android:name="google_analytics_default_allow_analytics_storage" android:value="true" />
     <meta-data android:name="google_analytics_default_allow_ad_storage" android:value="true" />
     <meta-data android:name="google_analytics_default_allow_ad_user_data" android:value="false" />
     <meta-data android:name="google_analytics_default_allow_ad_personalization_signals" android:value="false" />
     

   • iOS ： https://developers.google.com/tag-platform/security/guides/app-consent?platform=ios#initial_setup

     iOS 需要配置在应用的 Plist 文件中，参考配置 （业务需要根据自身情况进行调整）：

     <key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_ANALYTICS_STORAGE</key> <true/>
     <key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_STORAGE</key> <true/>
     <key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_USER_DATA</key> <false/>
     <key>GOOGLE_ANALYTICS_DEFAULT_ALLOW_AD_PERSONALIZATION_SIGNALS</key> <false/>
     

2. 使用接口调整配置

   MSDK 提供了扩展接口，用于管理 User Consent

   C#

   C++

   string userConsent = "{\"ad_storage\":true,\"analytics_storage\":true,\"ad_user_data\":false,\"ad_personalization\":false}";
     MSDKExtend::Invoke("Firebase" "setUserConsent", userConsent);

   string userConsent = "{\"ad_storage\":true,\"analytics_storage\":true,\"ad_user_data\":false,\"ad_personalization\":false}";
     MSDKExtend::Invoke("Firebase" "setUserConsent", userConsent);

   其中，扩展 JSON 参数的键值为 Consent Type

4.3 Crash异常上报功能

1）概述

Firebase Crashlytics 是一个轻量级的实时崩溃报告解决方案，可帮助您对影响应用质量的稳定性问题进行跟踪、确定优先解决顺序并加以修复。Crashlytics 会对崩溃进行智能分组并突出显示导致这些崩溃的环境因素，从而为您节省问题排查的时间。

您可以查明某个特定的崩溃是否影响到了很多用户；当某个问题突然变得严重时收到提醒；找出哪些代码行导致了崩溃。

2）上报信息介绍

在 Firebase 控制台 页面注册项目，根据提示完成 Firebase 项目注册，并在 Firebase 控制台主页（Project Overview），添加对应平台的 Firebase 应用，在 Quality->Crashlytics 查看 crash 上报。

①上报 crash 进程的堆栈，如下图所示：

②上报当前手机的基本信息，包括设备名称（厂商，型号）、系统版本、可用存储空间、可用内存大小等；

③上报用户的 openid，如下图的“User”所示。默认上报的 User ID 是 MSDK openid，也支持设置自定义User ID。

④用户自定义上报信息

A.可以设置关键数据键值对，随崩溃信息上报。在 Keys 中查看，如下图所示：

B.用户自定义日志（custom log messages）在 Logs 进行日志下载查看，如下图所示：

五、常见问题

5.1 常见编译问题

1、MSDK 5.3.000 版本，Firebase 版本升级为 6.1.0 正式版，新增 崩溃上报 功能。（Firebase 要求 Unity5.3 以上版本 。在 Unity4.x 下，工程中有 Firebase 会导致工程打不开。Firebase 崩溃上报要求 UE4.23 及以上）；

2、Unity2017 之后支持 dotnet4，业务可以根据自身情况选择 dotnet3 或者 dotnet4；并将目录完整拷贝到 asserts/CloudSDK/Scripts 下。

3、Unity2018 iOS 打包时，Crashlytics.framework 和 Fabric.framework 会出现 Embeded Binary 的问题。这是因为插件包中包含了一些 shell 运行脚本，用来上传 dYSM 文件以及其他操作。业务可以手动反选 Add to Embedded Binaries；

5.2 Firebase 拆除 Crash 模块

MSDK 5.16 版本开始支持 AndroidX 和 iOS 上 Firebase Crash 模块的拆除，业务可通过以下方式手动移除第三方插件。

1、Unity 引擎

• Android X
  1）删除整包中 GCloudSDK/Scripts/MSDKFirebase 文件夹；
  2）删除整包中 Plugins/Android/gcloudsdk-firebase-app-unity-6.16.1 （版本号可能有改动）文件夹；
  3）删除整包中 Plugins/Android/gcloudsdk-msdk-firebase/additions.gradle 文件中的 compile "com.google.firebase:firebase-crashlytics:17.2.2" （版本号可能有改动）。
  

• iOS
  1）删除整包中 GCloudSDK/Scripts/MSDKFirebase 文件夹；
  2）删除整包中 Plugins/iOS/GCloudSDK/MSDKFirebase/ThirdSDK/FirebaseCrashlytics.framework 文件；
  3）删除整包中 Plugins/iOS/GCloudSDK/MSDKFirebase/Firebase 文件夹。
  

2、UE 引擎

• Android X
  1）删除整包中 MSDKFirebase/Source/MSDKFirebase/lib/Android/msdk-firebase/additions.gradle 文件中的 compile "com.google.firebase:firebase-crashlytics:17.2.2" （版本号可能有改动）；
  2）删除整包中 MSDKFirebase/Source/MSDKFirebase/MSDKFirebase.Build.cs 文件中的以下内容。
  

  #if UE_4_22_OR_LATER 
    PublicAdditionalFrameworks.Add(new Framework("FIRAnalyticsConnector", "lib/iOS/Third/MSDKFirebase/FirebaseCrashlytics.embeddedframework.zip", "")); 
  #else 
    PublicAdditionalFrameworks.Add(new UEBuildFramework("FIRAnalyticsConnector", "lib/iOS/Third/MSDKFirebase/FirebaseCrashlytics.embeddedframework.zip", "")); 
  #endif
  

• iOS
  1）删除整包中 MSDKFirebase/Source/MSDKFirebase/lib/iOS/Third/MSDKFirebase/FirebaseCrashlytics.framework 文件；
  2）删除整包中 MSDKFirebase/Source/MSDKFirebase/MSDKFirebase.Build.cs 文件中的以下内容。
  

  #if UE_4_22_OR_LATER 
    PublicAdditionalFrameworks.Add(new Framework("FIRAnalyticsConnector", "lib/iOS/Third/MSDKFirebase/FirebaseCrashlytics.embeddedframework.zip", "")); 
  #else 
    PublicAdditionalFrameworks.Add(new UEBuildFramework("FIRAnalyticsConnector", "lib/iOS/Third/MSDKFirebase/FirebaseCrashlytics.embeddedframework.zip", "")); 
  #endif