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

如要開始使用 FCM，請建立最簡單的用途：從 通知撰寫工具傳送測試通知訊息到開發裝置，此時應用程式在裝置上處於背景狀態。本頁列出所有步驟，從設定到驗證都有，如果您已為 FCM 設定 Android 用戶端應用程式，可能已完成部分步驟。

設定 SDK

如果您已為應用程式啟用其他 Firebase 功能，可能已完成本節所述工作。

事前準備

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

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

    • 以 API 級別 21 (Lollipop) 以上版本為目標版本
    • 搭載 Android 5.0 以上版本
    • 使用 Jetpack (AndroidX)，包括符合下列版本需求：
      • com.android.tools.build:gradle v7.3.0 以上版本
      • compileSdkVersion 28 以上版本

  • 設定實體裝置或使用模擬器執行應用程式。
    請注意，依附於 Google Play 服務的 Firebase SDK 必須在已安裝 Google Play 服務的裝置或模擬器上執行。

  • 使用 Google 帳戶登入 Firebase。

如果您還沒有 Android 專案，只是想試用 Firebase 產品，可以下載我們的快速入門範例。

建立 Firebase 專案

將 Firebase 加入 Android 應用程式前，請先建立要連結至該 Android 應用程式的 Firebase 專案。如要進一步瞭解 Firebase 專案，請參閱「瞭解 Firebase 專案」。

向 Firebase 註冊應用程式

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

  1. 前往 Firebase 控制台。

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

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

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

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

新增 Firebase 設定檔

  1. 下載應用程式的 Firebase 設定檔 (google-services.json)，然後新增至程式碼集：

    1. 按一下「下載 google-services.json」，取得應用程式的 Firebase 設定檔。

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

  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.3" 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.3' 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:34.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 程式庫版本。

    (替代做法)  不使用 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:25.0.0")
    implementation("com.google.firebase:firebase-analytics:23.0.0")
}

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

存取註冊權杖

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

應用程式首次啟動時，FCM SDK 會為用戶端應用程式執行個體產生註冊權杖。如要指定單一裝置或建立裝置群組，您需要擴充 FirebaseMessagingService 並覆寫 onNewToken，才能存取這個權杖。

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

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

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

擷取目前的註冊權杖

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

Kotlin

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

/**
 * 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. 在標示為「新增 FCM 註冊權杖」的欄位中，輸入您在本指南先前章節中取得的註冊權杖。

  9. 選取「測試」。

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

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

後續步驟

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

應用程式在背景執行時，成功傳送通知訊息後，請參閱「在 Android 應用程式中接收訊息」，開始傳送至前景執行的應用程式。

不只是通知訊息

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