傳送測試訊息至背景執行的應用程式

如要開始使用 FCM，請建立最簡單的用途：當應用程式處於裝置背景時，從 通知編輯器傳送測試通知訊息。本頁面列出達成此目標的所有步驟，從設定到驗證，如果您已為 FCM 設定 Android 用戶端應用程式，這可能會涵蓋您已完成的步驟。

設定 SDK

如果您已為應用程式啟用其他 Firebase 功能，則本節將說明您可能已完成的任務。

事前準備

  • 安裝或更新至最新版的 Android Studio。

  • 請確認專案符合下列規定 (請注意，部分產品可能有更嚴格的規定)：

    • 指定 API 級別 21 (Lollipop) 以上版本
    • 使用 Android 5.0 以上版本
    • 使用 Jetpack (AndroidX)，包括符合下列版本需求：
      • com.android.tools.build:gradle 7.3.0 以上版本
      • 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. 按一下 [Register app] (註冊應用程式)。

新增 Firebase 設定檔

  1. 請下載 Firebase Android 設定檔 (google-services.json)，然後將其新增至應用程式：

    1. 按一下「Download google-services.json」，取得 Firebase Android 設定檔。

    2. 將設定檔移至應用程式的模組 (應用程式層級) 根目錄。

  2. 須有 Google 服務 Gradle 外掛程式 (google-services)，Firebase SDK 才能存取 google-services.json 設定檔中的值。

    1. 在根層級 (專案層級) Gradle 檔案 (<project>/build.gradle.kts 或 <project>/build.gradle) 中，將 Google 服務外掛程式新增為依附元件：

      Kotlin 

      plugins {
  id("com.android.application") version "7.3.0" apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id("com.google.gms.google-services") version "4.4.2" apply false
}

      Groovy 

      plugins {
  id 'com.android.application' version '7.3.0' apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id 'com.google.gms.google-services' version '4.4.2' apply false
}

    2. 在模組 (應用程式層級) Gradle 檔案 (通常為 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，新增 Google 服務外掛程式：

      Kotlin 

      plugins {
  id("com.android.application")

  // Add the Google services Gradle plugin
  id("com.google.gms.google-services")
  // ...
}

      Groovy 

      plugins {
  id 'com.android.application'

  // Add the Google services Gradle plugin
  id 'com.google.gms.google-services'
  // ...
}

在應用程式中新增 Firebase SDK

  1. 在模組 (應用程式層級) Gradle 檔案 (通常為 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，加入 Android 的 Firebase Cloud Messaging 程式庫依附元件。建議您使用 Firebase Android BoM 來控制程式庫版本。

    為提供最佳的 Firebase Cloud Messaging 體驗，建議您在 Firebase 專案中啟用 Google Analytics，並將 Google Analytics 專用 Firebase SDK 新增至應用程式。

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.6.0"))

    // Add 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 {
    // Add 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:24.1.0")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}
    想找 Kotlin 專屬的程式庫模組嗎？自 2023 年 10 月 (Firebase BoM 32.5.0)起，Kotlin 和 Java 開發人員皆可依賴主要程式庫模組 (詳情請參閱這項計畫的常見問題)。

  2. 將 Android 專案與 Gradle 檔案同步處理。

存取註冊權杖

如要傳送訊息給特定裝置，您必須知道該裝置的註冊權杖。您必須在「通知」控制台的欄位中輸入權杖，才能完成本教學課程。因此，請務必在擷取權杖後複製或安全地儲存權杖。

在應用程式首次啟動時，FCM SDK 會為用戶端應用程式例項產生註冊權杖。如果您想指定單一裝置或建立裝置群組，就必須擴充 FirebaseMessagingService 並覆寫 onNewToken，才能存取這個權杖。

本節將說明如何擷取權杖，以及如何監控權杖的變更。由於權杖可以在初始啟動後輪替，因此強烈建議您擷取最新更新的註冊權杖。

註冊權杖可能會在下列情況下變更：

  • 應用程式已在新裝置上還原
  • 使用者解除安裝/重新安裝應用程式
  • 使用者清除應用程式資料。

擷取目前的註冊權杖

如需擷取目前的權杖，請呼叫 FirebaseMessaging.getInstance().getToken()：

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()
})

Java

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();
        }
    });

監控權杖產生作業

每當產生新的權杖，就會觸發 onNewToken 回呼。

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)
}
MyFirebaseMessagingService.kt

Java

/**
 * 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(@NonNull 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);
}
MyFirebaseMessagingService.java

取得權杖後，您可以將權杖傳送至應用程式伺服器，並使用偏好的儲存方法儲存權杖。

傳送測試通知訊息

  1. 在目標裝置上安裝並執行應用程式。在 Apple 裝置上，您必須接受接收遠端通知的權限要求。

  2. 確認應用程式在裝置的背景中執行。

  3. 在 Firebase 控制台中，開啟「Messaging」頁面。

  4. 如果這是您的第一則訊息，請選取「建立第一個廣告活動」。

    1. 選取「Firebase 通知訊息」，然後選取「建立」。

  5. 否則，請在「廣告活動」分頁中依序選取「新增廣告活動」和「通知」。

  6. 輸入訊息文字。其他欄位則為選填欄位。

  7. 在右側窗格中選取「傳送測試訊息」。

  8. 在「Add an FCM registration token」欄位中，輸入您在本指南前一個部分取得的註冊權杖。

  9. 選取「測試」。

選取「Test」後，指定的用戶端裝置 (應用程式在背景執行) 應會收到通知。

如要深入瞭解應用程式訊息的傳送情形，請參閱 FCM 報表資訊主頁，這可記錄在 Apple 和 Android 裝置上傳送及開啟的訊息數量，以及 Android 應用程式「曝光次數」(使用者看到的通知) 資料。

後續步驟

將訊息傳送至前景應用程式

在應用程式處於背景執行時，您已成功傳送通知訊息，請參閱「在 Android 應用程式中接收訊息」，瞭解如何開始傳送至前景應用程式。

除了通知訊息之外

如要進一步瞭解通知訊息，並在應用程式中加入其他進階行為，請參閱：