Wprowadzenie do Komunikacji w chmurze Firebase w aplikacjach na Androida

Z tego przewodnika dowiesz się, jak rozpocząć korzystanie z Firebase Cloud Messaging w aplikacjach klienckich na Androida, aby móc niezawodnie wysyłać wiadomości.

FCM klienci wymagają urządzeń z Androidem 6.0 lub nowszym, na których jest zainstalowana aplikacja Sklep Google Play, albo emulatora z Androidem 6.0 i interfejsami API Google. Pamiętaj, że nie musisz wdrażać aplikacji na Androida w Sklepie Google Play.

Konfigurowanie pakietu SDK

Dodaj Firebase do projektu aplikacji na Androida, jeśli nie korzystasz w nim jeszcze z tej usługi.

Aby zapewnić optymalne działanie FCM, zdecydowanie zalecamy włączenie Google Analytics w projekcie. Google Analytics jest wymagane do raportowania dostarczania wiadomości w FCM.

Edytowanie pliku manifestu aplikacji

Dodaj do pliku manifestu aplikacji te elementy:

• Usługa, która rozszerza FirebaseMessagingService. Jest to wymagane, jeśli chcesz obsługiwać wiadomości w inny sposób niż tylko odbierać powiadomienia w aplikacjach działających w tle. Aby otrzymywać powiadomienia w aplikacjach działających na pierwszym planie, odbierać ładunek danych i korzystać z innych funkcji, musisz rozszerzyć tę usługę.

<service
    android:name=".java.MyFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
AndroidManifest.xml

• (Opcjonalnie) W komponencie aplikacji elementy metadanych, które pozwalają ustawić domyślną ikonę i kolor powiadomienia. Android używa tych wartości, gdy w przychodzących wiadomościach nie są wyraźnie określone ikona ani kolor.

<!-- 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" />
AndroidManifest.xml

• (Opcjonalnie) W Androidzie 8.0 (interfejs API na poziomie 26) i nowszych wersjach, obsługiwane są kanały powiadomień, które są też zalecane. FCM udostępnia domyślny kanał powiadomień z podstawowymi ustawieniami. Jeśli wolisz utworzyć i używać własnego kanału domyślnego, ustaw default_notification_channel_id na identyfikator obiektu kanału powiadomień jak pokazano poniżej. FCM będzie używać tej wartości, gdy w przychodzących wiadomościach nie będzie wyraźnie określony kanał powiadomień. Więcej informacji znajdziesz w artykule Zarządzanie kanałami powiadomień.

<meta-data
    android:name="com.google.firebase.messaging.default_notification_channel_id"
    android:value="@string/default_notification_channel_id" />
AndroidManifest.xml

Prośba o zgodę na wyświetlanie powiadomień w czasie działania aplikacji na Androidzie 13 lub nowszym

Android 13 wprowadza nowe uprawnienie do wyświetlania powiadomień w czasie działania aplikacji. Dotyczy to wszystkich aplikacji dział101}jących na Androidzie 13 lub nowszym, które używają FCM powiadomień.

Domyślnie pakiet SDK FCM (w wersji 23.0.6 lub nowszej) zawiera uprawnienie POST_NOTIFICATIONS zdefiniowane w pliku manifestu. Aplikacja będzie jednak musiała poprosić o wersję tego uprawnienia w czasie działania aplikacji za pomocą stałej android.permission.POST_NOTIFICATIONS. Aplikacja nie będzie mogła wyświetlać powiadomień, dopóki użytkownik nie przyzna jej tego uprawnienia.

Aby poprosić o nowe uprawnienie w czasie działania aplikacji:

// Declare the launcher at the top of your Activity/Fragment:
private val requestPermissionLauncher = registerForActivityResult(
    ActivityResultContracts.RequestPermission(),
) { isGranted: Boolean ->
    if (isGranted) {
        // FCM SDK (and your app) can post notifications.
    } else {
        // TODO: Inform user that that your app will not show notifications.
    }
}

private fun askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
            PackageManager.PERMISSION_GRANTED
        ) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
        }
    }
}
MainActivity.kt

// Declare the launcher at the top of your Activity/Fragment:
private final ActivityResultLauncher<String> requestPermissionLauncher =
        registerForActivityResult(new ActivityResultContracts.RequestPermission(), isGranted -> {
            if (isGranted) {
                // FCM SDK (and your app) can post notifications.
            } else {
                // TODO: Inform user that that your app will not show notifications.
            }
        });

private void askNotificationPermission() {
    // This is only necessary for API level >= 33 (TIRAMISU)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) ==
                PackageManager.PERMISSION_GRANTED) {
            // FCM SDK (and your app) can post notifications.
        } else if (shouldShowRequestPermissionRationale(Manifest.permission.POST_NOTIFICATIONS)) {
            // TODO: display an educational UI explaining to the user the features that will be enabled
            //       by them granting the POST_NOTIFICATION permission. This UI should provide the user
            //       "OK" and "No thanks" buttons. If the user selects "OK," directly request the permission.
            //       If the user selects "No thanks," allow the user to continue without notifications.
        } else {
            // Directly ask for the permission
            requestPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS);
        }
    }
}
MainActivity.java

Zazwyczaj należy wyświetlić interfejs, który wyjaśni użytkownikowi, jakie funkcje zostaną włączone, jeśli przyzna aplikacji uprawnienia do wysyłania powiadomień. Ten interfejs powinien zawierać opcje, które pozwolą użytkownikowi wyrazić zgodę lub odmówić, np. przyciski OK i Nie, dziękuję. Jeśli użytkownik wybierze OK, bezpośrednio poproś o uprawnienie. Jeśli użytkownik wybierze Nie, dziękuję, pozwól mu kontynuować bez powiadomień.

Więcej sprawdzonych metod dotyczących tego, kiedy aplikacja powinna poprosić użytkownika o uprawnienie do wyświetlania powiadomień w czasie działania aplikacji , znajdziesz w artykule POST_NOTIFICATIONS.

Uprawnienia do wyświetlania powiadomień w aplikacjach kierowanych na Androida 12L (interfejs API na poziomie 32) lub starszego

Android automatycznie prosi użytkownika o zgodę, gdy aplikacja po raz pierwszy tworzy kanał powiadomień, o ile aplikacja działa na pierwszym planie. Istnieją jednak ważne zastrzeżenia dotyczące czasu tworzenia kanału i próśb o uprawnienia:

• Jeśli aplikacja utworzy swój pierwszy kanał powiadomień, gdy działa w tle (co robi pakiet SDK FCMpodczas odbierania powiadomienia FCM), Android nie pozwoli na wyświetlenie powiadomienia i nie poprosi użytkownika o zgodę na wyświetlanie powiadomień, dopóki aplikacja nie zostanie ponownie otwarta. Oznacza to, że wszystkie powiadomienia odebrane, zanim aplikacja zostanie otwarta i użytkownik zaakceptuje uprawnienia, zostaną utracone.
• Zdecydowanie zalecamy zaktualizowanie aplikacji, aby była kierowana na Androida 13 lub nowszego, dzięki czemu będzie mogła korzystać z interfejsów API platformy do wysyłania próśb o uprawnienia. Jeśli nie jest to możliwe, aplikacja powinna tworzyć kanały powiadomień, zanim wyśle do niej jakiekolwiek powiadomienia. Dzięki temu wyświetli się okno z prośbą o zgodę na wyświetlanie powiadomień i nie zostaną utracone żadne powiadomienia. Więcej informacji znajdziesz w artykule Sprawdzone metody dotyczące zgody na wyświetlanie powiadomień.

Opcjonalnie: usuwanie uprawnienia POST_NOTIFICATIONS

Domyślnie pakiet SDK FCM zawiera uprawnienie POST_NOTIFICATIONS. Jeśli aplikacja nie używa wiadomości z powiadomieniami (ani za pomocą FCM powiadomień, ani za pomocą innego pakietu SDK, ani bezpośrednio wysyłanych przez aplikację) i nie chcesz, aby zawierała to uprawnienie, możesz je usunąć za pomocą znacznika remove narzędzia do łączenia plików manifestu. Pamiętaj, że usunięcie tego uprawnienia uniemożliwia wyświetlanie wszystkich powiadomień, a nie tylko FCM powiadomień. Dodaj do pliku manifestu aplikacji te elementy:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" tools:node="remove"/>

Uzyskiwanie dostępu do tokena rejestracji FCM

Przy pierwszym uruchomieniu aplikacji pakiet SDK FCM generuje token rejestracji dla instancji aplikacji klienckiej. Jeśli chcesz kierować reklamy na pojedyncze instancje aplikacji lub tworzyć grupy urządzeń, musisz uzyskać dostęp do tego tokena, rozszerzając FirebaseMessagingService i zastępując onNewToken. Ponieważ token może zostać zmieniony po pierwszym uruchomieniu, zdecydowanie zalecamy pobranie najnowszego zaktualizowanego tokena rejestracji.

Token rejestracji może się zmienić, gdy:

• aplikacja zostanie przywrócona na nowym urządzeniu,
• użytkownik odinstaluje i ponownie zainstaluje aplikację,
• użytkownik wyczyści dane aplikacji.

Pobieranie bieżącego tokena rejestracji

Gdy musisz pobrać bieżący token, wywołaj FirebaseMessaging.getInstance().getToken():

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

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

Monitorowanie generowania tokenów

Wywołanie zwrotne onNewToken jest wywoływane za każdym razem, gdy zostanie wygenerowany nowy token.

/**
 * 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

/**
 * 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

Po uzyskaniu tokena możesz wysłać go na serwer aplikacji i zapisać go za pomocą preferowanej metody.

Sprawdzanie, czy są dostępne Usługi Google Play

Aplikacje, które korzystają z pakietu SDK Usług Google Play, powinny zawsze sprawdzać, czy na urządzeniu jest zainstalowany zgodny plik APK Usług Google Play, zanim uzyskają dostęp do funkcji Usług Google Play. Więcej informacji znajdziesz w artykule Konfigurowanie Usług Google Play. Zalecamy, aby zrobić to w 2 miejscach: w metodzie onCreate() głównej aktywności i w metodzie onResume(). Sprawdzenie w onCreate() gwarantuje, że aplikacja nie będzie mogła być używana bez pomyślnego sprawdzenia. Sprawdzenie w onResume() gwarantuje, że jeśli użytkownik wróci do uruchomionej aplikacji w inny sposób, np. za pomocą przycisku Wstecz, sprawdzenie zostanie wykonane.

Jeśli na urządzeniu nie ma zgodnej wersji Usług Google Play, Twoja aplikacja może wywołać GoogleApiAvailability.makeGooglePlayServicesAvailable() aby umożliwić użytkownikom pobranie Usług Google Play ze Sklepu Play.

Zapobieganie automatycznej inicjalizacji

Gdy zostanie wygenerowany token rejestracji FCM, biblioteka prześle identyfikator i dane konfiguracyjne do Firebase. Jeśli wolisz zapobiec automatycznemu generowaniu tokenów , wyłącz zbieranie danych Analytics i automatyczną inicjalizację FCM (musisz wyłączyć obie te opcje) , dodając te wartości metadanych do pliku AndroidManifest.xml:

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

Aby ponownie włączyć automatyczną inicjalizację FCM, wywołaj:

Firebase.messaging.isAutoInitEnabled = true
MainActivity.kt

FirebaseMessaging.getInstance().setAutoInitEnabled(true);
MainActivity.java

Aby ponownie włączyć zbieranie danych Analytics, wywołaj metodę setAnalyticsCollectionEnabled() klasy FirebaseAnalytics. Przykład:

setAnalyticsCollectionEnabled(true);

Po ustawieniu te wartości są zachowywane po ponownym uruchomieniu aplikacji.

Wysyłanie wiadomości z powiadomieniem

Aby sprawdzić, czy klient na Androida jest prawidłowo skonfigurowany, możesz wysłać testową wiadomość z powiadomieniem, korzystając z tych instrukcji:

1. Zainstaluj i uruchom aplikację na urządzeniu docelowym.

2. Upewnij się, że aplikacja działa w tle na urządzeniu.

3. W konsoli Firebase otwórz DevOps i zaangażowanie > Wiadomości.

4. Utwórz kampanię.

   • Jeśli to Twoja pierwsza wiadomość:

     1. Kliknij Utwórz pierwszą kampanię.

     2. Kliknij Wiadomości z powiadomieniami Firebase i wybierz Utwórz.

   • Jeśli masz już utworzone kampanie:

     1. Na karcie Kampanie kliknij Nowa kampania.

     2. Kliknij Powiadomienia.

5. Wpisz tekst wiadomości. Wszystkie pozostałe pola są opcjonalne.

6. W prawym panelu kliknij Wyślij wiadomość testową.

7. W polu Dodaj token rejestracji FCM wpisz token rejestracji uzyskany w poprzedniej sekcji tego przewodnika.

8. Kliknij Testuj.

Urządzenie docelowe z aplikacją działającą w tle powinno otrzymać powiadomienie.

Aby uzyskać informacje o dostarczaniu wiadomości do aplikacji, w konsoli Firebase otwórz DevOps i zaangażowanie > Wiadomości > Raporty. Ten panel rejestruje liczbę wysłanych i otwartych wiadomości na urządzeniach Apple i Android oraz dane o „wyświetleniach” (powiadomieniach widzianych przez użytkowników) w przypadku aplikacji na Androida.

Dalsze kroki

Po wykonaniu czynności konfiguracyjnych możesz przejść do dalszych działań związanych z FCM na Androidzie:

• Wysyłanie wiadomości na urządzenia
• Odbieranie wiadomości w aplikacji na Androida
• Wysyłanie wiadomości do tematów