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

如要開始使用 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 專案

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

透過 Firebase 註冊應用程式

如要在 Android 應用程式中使用 Firebase，您必須使用 Firebase 專案註冊應用程式。註冊應用程式通常稱為「新增」應用程式至專案中。

  1. 前往 Firebase 主控台。

  2. 在專案總覽頁面中間，按一下「Android」圖示 () 或「Add app」，啟動設定工作流程。

  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 (app-level)」根目錄。

  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 雲端通訊程式庫的依附元件。建議您使用 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.1.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.1")
}
    在尋找 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. 從右側窗格中選取「Send test message」。

  8. 在標示為「Add an FCM 註冊 token」的欄位中，輸入您在本指南的前一個章節取得的註冊憑證。

  9. 選取「測試」。

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

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

後續步驟

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

在應用程式於背景運作的情況下成功傳送通知訊息後，請參閱「在 Android 應用程式中接收訊息」，瞭解如何開始傳送至前景的應用程式。

不再侷限於通知訊息

除了通知訊息外，如要為應用程式新增其他進階行為，請參閱：