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

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

設定 SDK

本節說明您已為應用程式啟用其他 Firebase 功能時可能完成的工作。

事前準備

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

  • 請確認您的專案符合以下要求 (請注意，部分產品的要求可能更嚴格)：

    • 以 API 級別 19 (KitKat) 以上版本為目標
    • 使用 Android 4.4 以上版本
    • 使用 Jetpack (AndroidX)，其中包含下列版本需求：
      • com.android.tools.build:gradle 7.3.0 以上版本
      • compileSdkVersion 28 以上版本

  • 設定實體裝置或使用模擬器執行應用程式。
    請注意，含有依附元件的 Google Play 服務 Firebase SDK 需要裝置或模擬器安裝 Google Play 服務。

  • 使用 Google 帳戶登入 Firebase。

如果您沒有 Android 專案，只是想試用 Firebase 產品，可以下載其中一個快速入門導覽課程範例。

建立 Firebase 專案

您需要先建立用於連結 Android 應用程式的 Firebase 專案，才能將 Firebase 新增到 Android 應用程式。如要進一步瞭解 Firebase 專案，請參閱「瞭解 Firebase 專案」一文。

透過 Firebase 註冊應用程式

如要在 Android 應用程式中使用 Firebase，您需要透過 Firebase 專案註冊應用程式。註冊應用程式的做法通常稱為「新增」應用程式到專案中。

  1. 前往 Firebase 主控台。

  2. 在專案總覽頁面的中央，按一下「Android」圖示 () 或「新增應用程式」，啟動設定工作流程。

  3. 在「Android package name」欄位中輸入應用程式的套件名稱。

  4. (選用) 輸入其他應用程式資訊：應用程式暱稱和偵錯簽署憑證 SHA-1。

  5. 按一下 [Register app] (註冊應用程式)。

新增 Firebase 設定檔

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

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

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

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

    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.1" 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.1' 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 雲端通訊程式庫的依附元件。建議您使用 Firebase Android BoM 來控管程式庫版本管理。

    為了提供最佳的 Firebase 雲端通訊體驗，建議您在 Firebase 專案中啟用 Google Analytics (分析)，並將 Google Analytics (分析) 專用 Firebase SDK 新增至應用程式。

    dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.0.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 程式庫版本。

    (替代方法) 新增 Firebase 程式庫依附元件，「不必」使用 BoM

    如果選擇不使用 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.0.0")
    implementation("com.google.firebase:firebase-analytics:22.0.0")
}
    在尋找 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 控制台中，開啟「訊息」頁面。

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

    1. 依序選取「Firebase 通知訊息」和「建立」。

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

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

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

  8. 在標示為「Add an FCM registration token」的欄位中，輸入您在本指南上一節所取得的註冊權杖。

  9. 選取「測試」。

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

如要進一步瞭解向應用程式傳送的訊息，請參閱 FCM 報表資訊主頁，其中記錄了在 Apple 和 Android 裝置上傳送及開啟的訊息數量，以及 Android 應用程式的「曝光」(使用者看到的通知) 資料。

後續步驟

傳送訊息至前景應用程式

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

不再侷限於通知訊息

如要除了通知訊息之外，並在應用程式中加入其他進階行為，請參閱：