Google is committed to advancing racial equity for Black communities. See how.
本頁面由 Cloud Translation API 翻譯而成。
Switch to English

在Android上設置Firebase Cloud Messaging客戶端應用

要編寫您的Firebase Cloud Messaging Android客戶端應用程序,請使用FirebaseMessaging API和Android Studio 1.4或更高版本以及Gradle。此頁面中的說明假定您已完成將Firebase添加到Android項目的步驟。

FCM客戶端要求運行Android 4.1或更高版本的設備也安裝了Google Play商店應用,或者運行帶有Google API的Android 4.1的模擬器。請注意,您不僅限於通過Google Play商店部署Android應用。

設置SDK

本部分介紹如果您已經為應用程序啟用了其他Firebase功能,則可能已完成的任務。

在你開始之前

  • Android Studio安裝或更新為最新版本。

  • 確保您的項目符合以下要求:

    • 定位到API級別16(Jelly Bean)或更高版本
    • 使用Gradle 4.1或更高版本
    • 使用Jetpack(AndroidX) ,其中包括滿足以下版本要求:
      • com.android.tools.build:gradle v3.2.1或更高版本
      • compileSdkVersion 28或更高版本
  • 設置物理設備或使用仿真器運行您的應用程序。
    請注意,依賴於Google Play服務的Firebase SDK需要設備或仿真器安裝Google Play服務。

  • 使用您的Google帳戶登錄Firebase

如果您還沒有Android項目,而只想試用Firebase產品,則可以下載我們的快速入門示例之一

創建一個Firebase項目

在將Firebase添加到Android應用之前,您需要創建一個Firebase項目以連接到Android應用。訪問了解Firebase項目以了解有關Firebase項目的更多信息。

在Firebase中註冊您的應用

要在Android應用中使用Firebase,您需要在Firebase項目中註冊您的應用。註冊您的應用程序通常被稱為“將您的應用程序添加到您的項目中”。

  1. 轉到Firebase控制台

  2. 在項目概述頁面的中心,單擊Android圖標( )或添加應用程序以啟動設置工作流程。

  3. 在“ Android包名稱”字段中輸入您應用的包名稱。

  4. (可選)輸入其他應用程序信息:應用程序暱稱調試簽名證書SHA-1

  5. 點擊註冊應用

添加Firebase配置文件

  1. 將Firebase Android配置文件添加到您的應用中:

    1. 點擊下載google-services.json以獲取您的Firebase Android配置文件( google-services.json )。

    2. 將您的配置文件移動到應用程序的模塊(應用程序級)目錄中。

  2. 要在您的應用中啟用Firebase產品,請將google-services插件添加到您的Gradle文件中。

    1. 在您的根級別(項目級別)的Gradle文件( build.gradle )中,添加規則以包括Google Services Gradle插件。還要檢查您是否擁有Google的Maven存儲庫。

      buildscript {
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
        }
      
        dependencies {
          // ...
      
          // Add the following line:
          classpath 'com.google.gms:google-services:4.3.5'  // Google Services plugin
        }
      }
      
      allprojects {
        // ...
      
        repositories {
          // Check that you have the following line (if not, add it):
          google()  // Google's Maven repository
          // ...
        }
      }
      
    2. 在模塊(應用程序級)Gradle文件(通常為app/build.gradle )中,應用Google Services Gradle插件:

      apply plugin: 'com.android.application'
      // Add the following line:
      apply plugin: 'com.google.gms.google-services'  // Google Services plugin
      
      android {
        // ...
      }
      

將Firebase SDK添加到您的應用

  1. 使用Firebase Android BoM ,在模塊(應用程序級)Gradle文件(通常為app/build.gradle )中聲明Firebase Cloud Messaging Android庫的依賴app/build.gradle

    為了獲得Firebase Cloud Messaging的最佳體驗,我們建議您在項目中啟用Google Analytics(分析) 。另外,作為設置Google Analytics(分析)的一部分,您需要將適用於Google Analytics(分析)的Firebase SDK添加到您的應用中。

    爪哇

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:27.0.0')
    
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When using the BoM, you don't specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging'
        implementation 'com.google.firebase:firebase-analytics'
    }
    

    通過使用Firebase Android BoM ,您的應用將始終使用Firebase Android庫的兼容版本。

    (可選)使用BoM聲明Firebase庫依賴關係

    如果選擇不使用Firebase BoM,則必須在其依賴關係行中指定每個Firebase庫版本。

    請注意,如果您在應用中使用多個Firebase庫,我們強烈建議您使用BoM來管理庫版本,以確保所有版本都兼容。

    dependencies {
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When NOT using the BoM, you must specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging:21.1.0'
        implementation 'com.google.firebase:firebase-analytics:18.0.3'
    }
    

    Kotlin + KTX

    dependencies {
        // Import the BoM for the Firebase platform
        implementation platform('com.google.firebase:firebase-bom:27.0.0')
    
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When using the BoM, you don't specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging-ktx'
        implementation 'com.google.firebase:firebase-analytics-ktx'
    }
    

    通過使用Firebase Android BoM ,您的應用將始終使用Firebase Android庫的兼容版本。

    (可選)使用BoM聲明Firebase庫依賴關係

    如果選擇不使用Firebase BoM,則必須在其依賴關係行中指定每個Firebase庫版本。

    請注意,如果您在應用中使用多個Firebase庫,我們強烈建議您使用BoM來管理庫版本,以確保所有版本都兼容。

    dependencies {
        // Declare the dependencies for the Firebase Cloud Messaging and Analytics libraries
        // When NOT using the BoM, you must specify versions in Firebase library dependencies
        implementation 'com.google.firebase:firebase-messaging-ktx:21.0.1'
        implementation 'com.google.firebase:firebase-analytics-ktx:18.0.3'
    }
    

  2. 同步您的應用程序,以確保所有依賴項都具有必需的版本。

編輯您的應用清單

將以下內容添加到您的應用清單中:

  • 擴展FirebaseMessagingService的服務。如果您要進行其他消息處理,而不僅僅是在後台接收有關應用程序的通知,則這是必需的。要在前台應用程序中接收通知,接收數據有效載荷,發送上游消息等,您必須擴展此服務。
  • <service
        android:name=".java.MyFirebaseMessagingService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
  • (可選)在應用程序組件中,元數據元素用於設置默認的通知圖標和顏色。只要傳入消息未明確設置圖標或顏色,Android就會使用這些值。
  • <!-- 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" />
    <!-- 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" />
  • (可選)從Android 8.0(API級別26)及更高版本開始,支持並建議使用通知渠道。 FCM提供具有基本設置的默認通知渠道。如果您喜歡 創建和使用自己的默認通道,則將default_notification_channel_id設置為通知通道對象的ID,如下所示;每當傳入消息未顯式設置通知通道時,FCM將使用此值。要了解更多信息,請參閱管理通知渠道
  • <meta-data
        android:name="com.google.firebase.messaging.default_notification_channel_id"
        android:value="@string/default_notification_channel_id" />

訪問設備註冊令牌

首次啟動應用程序時,FCM SDK會為客戶端應用程序實例生成註冊令牌。如果要定位單個設備或創建設備組,則需要通過擴展FirebaseMessagingService並覆蓋onNewToken來訪問此令牌。

本節介紹如何檢索令牌以及如何監視對令牌的更改。由於令牌在初次啟動後可以旋轉,因此強烈建議您檢索最新的更新註冊令牌。

在以下情況下,註冊令牌可能會更改:

  • 該應用已在新設備上還原
  • 用戶卸載/重新安裝應用程序
  • 用戶清除應用程序數據。

檢索當前註冊令牌

當您需要檢索當前令牌時,請調用FirebaseMessaging.getInstance().getToken()

爪哇

FirebaseMessaging.getInstance().getToken()
    .addOnCompleteListener(new OnCompleteListener<String>() {
        @Override
        public void onComplete(@NonNull Task<String> task) {
          if (!task.isSuccessful()) {
            Log.w(TAG, "Fetching FCM registration token failed", task.getException());
            return;
          }

          // Get new FCM registration token
          String token = task.getResult();

          // Log and toast
          String msg = getString(R.string.msg_token_fmt, token);
          Log.d(TAG, msg);
          Toast.makeText(MainActivity.this, msg, Toast.LENGTH_SHORT).show();
        }
    });

Kotlin + KTX

FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
    if (!task.isSuccessful) {
        Log.w(TAG, "Fetching FCM registration token failed", task.exception)
        return@OnCompleteListener
    }

    // Get new FCM registration token
    val token = task.result

    // Log and toast
    val msg = getString(R.string.msg_token_fmt, token)
    Log.d(TAG, msg)
    Toast.makeText(baseContext, msg, Toast.LENGTH_SHORT).show()
})

監控令牌生成

每當生成新令牌時,就會觸發onNewToken回調。

爪哇

/**
 * There are two scenarios when onNewToken is called:
 * 1) When a new token is generated on initial app startup
 * 2) Whenever an existing token is changed
 * Under #2, there are three scenarios when the existing token is changed:
 * A) App is restored to a new device
 * B) User uninstalls/reinstalls the app
 * C) User clears app data
 */
@Override
public void onNewToken(String token) {
    Log.d(TAG, "Refreshed token: " + token);

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token);
}

Kotlin + KTX

/**
 * Called if the FCM registration token is updated. This may occur if the security of
 * the previous token had been compromised. Note that this is called when the
 * FCM registration token is initially generated so this is where you would retrieve the token.
 */
override fun onNewToken(token: String) {
    Log.d(TAG, "Refreshed token: $token")

    // If you want to send messages to this application instance or
    // manage this apps subscriptions on the server side, send the
    // FCM registration token to your app server.
    sendRegistrationToServer(token)
}

獲取令牌後,可以將其發送到應用服務器並使用首選方法進行存儲。

檢查Google Play服務

依賴Play服務SDK的應用在訪問Google Play服務功能之前,應始終檢查設備是否有兼容的Google Play服務APK。建議在兩個位置執行此操作:在主活動的onCreate()方法及其onResume()方法中。在onCreate()檢查可確保在未成功進行檢查的情況下無法使用該應用程序。在onResume()檢查可確保如果用戶通過其他方式(例如通過“後退”按鈕onResume()返回到正在運行的應用程序,則仍將執行檢查。

如果設備沒有兼容版本的Google Play服務,則您的應用可以調用GoogleApiAvailability.makeGooglePlayServicesAvailable()以允許用戶從Play商店下載Google Play服務。

防止自動初始化

生成FCM註冊令牌後,庫會將標識符和配置數據上載到Firebase。如果您希望防止令牌自動生成,請通過將以下元數據值添加到AndroidManifest.xml來禁用Analytics收集和FCM自動初始化(必須同時禁用兩者):

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

要重新啟用FCM自動初始化,請進行運行時調用:

爪哇

FirebaseMessaging.getInstance().setAutoInitEnabled(true);

Kotlin + KTX

Firebase.messaging.isAutoInitEnabled = true

要重新啟用Analytics(分析)集合,請調用FirebaseAnalytics類的setAnalyticsCollectionEnabled()方法。例如:

setAnalyticsCollectionEnabled(true);

一旦設置,這些值將在應用程序重新啟動後持續存在。

下一步

設置客戶端應用程序後,您就可以開始使用Notifications作曲家發送下游消息了。快速入門示例中演示了此功能,您可以下載,運行和查看該示例

要將其他更高級的行為添加到您的應用中,您可以聲明一個意圖過濾器並實現一個活動以響應傳入的消息。有關詳細信息,請參閱從應用程序服務器發送消息的指南:

請記住,要利用這些功能,您需要服務器實現和服務器協議(HTTP或XMPP),或者Admin SDK的實現。