Pierwsze kroki ze Zdalnej konfiguracji Firebase

iOS+ Android Sieć Flutter Unity C++

Ważne: w tej sekcji znajdziesz instrukcje konfigurowania usługi Remote Config z klientami mobilnymi i internetowymi. Informacje o środowiskach serwera znajdziesz w artykule Używanie Remote Config w środowiskach serwera.

Za pomocą Firebase Remote Config możesz definiować parametry w aplikacji i zmieniać ich wartości w chmurze, co umożliwia modyfikowanie wyglądu i zachowania aplikacji bez rozpowszechniania jej aktualizacji. W tym przewodniku znajdziesz instrukcje rozpoczęcia pracy i przykładowy kod, który możesz skopiować lub pobrać z repozytorium GitHub firebase/quickstart-android.

Krok 1. Dodaj do aplikacji pakiet SDK Firebase i Zdalnej konfiguracji

1. Jeśli jeszcze tego nie zrobiono, dodaj Firebase do projektu na Androida.

2. W przypadku Remote Config usługa Google Analytics jest wymagana do warunkowego kierowania instancji aplikacji na właściwości użytkownika i listy odbiorców. Sprawdź, czy w projekcie włączysz Google Analytics.

3. W pliku Gradle modułu (na poziomie aplikacji) (zwykle <project>/<app-module>/build.gradle.kts lub <project>/<app-module>/build.gradle) dodaj zależność z biblioteką Remote Config na Androida. Zalecamy używanie Firebase Android BoM do kontrolowania wersji biblioteki.

   W ramach konfigurowania Analytics musisz też dodać do aplikacji pakiet SDK Firebase dla Google Analytics.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.15.0"))
   
       // Add the dependencies for the Remote Config and Analytics libraries
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-config")
       implementation("com.google.firebase:firebase-analytics")
   }

   Dzięki użyciu Firebase Android BoMaplikacja zawsze będzie używać zgodnych wersji bibliotek Firebase na Androida.

   (Alternatywnie)  Dodaj zależności biblioteki Firebase bez korzystania z BoM

   Jeśli zdecydujesz się nie używać Firebase BoM, musisz określić każdą wersję biblioteki Firebase w jej wierszu zależności.

   Jeśli w aplikacji używasz kilku bibliotek Firebase, zdecydowanie zalecamy korzystanie z BoM do zarządzania wersjami bibliotek. Dzięki temu wszystkie wersje będą ze sobą zgodne.

   dependencies {
       // Add the dependencies for the Remote Config and Analytics libraries
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-config:22.1.2")
       implementation("com.google.firebase:firebase-analytics:22.4.0")
   }

   Szukasz modułu biblioteki dla Kotlina? Od października 2023 r. (Firebase BoM 32.5.0) deweloperzy Kotlina i Java mogą korzystać z głównego modułu biblioteki (szczegółowe informacje znajdziesz w często zadawanych pytaniach dotyczących tej inicjatywy).

Uwaga: pakiet SDK Androida jest zależny od interfejsu API REST Remote Config, dlatego nie go wyłączaj. W typowym projekcie jest on włączony domyślnie.

Krok 2. Pobierz obiekt singletona Remote Config

Pobierz instancję obiektu Remote Config i ustaw minimalny interwał pobierania ustawień, aby umożliwić ich częste odświeżanie:

Kotlin

val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
val configSettings = remoteConfigSettings {
    minimumFetchIntervalInSeconds = 3600
}
remoteConfig.setConfigSettingsAsync(configSettings)
MainActivity.kt

Java

FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);
MainActivity.java

Obiekt typu singleton służy do przechowywania domyślnych wartości parametrów w aplikacji, pobierania zaktualizowanych wartości parametrów z backendu oraz kontrolowania, kiedy pobrane wartości są udostępniane aplikacji.

Podczas tworzenia zalecamy ustawienie stosunkowo niskiego minimalnego interwału pobierania. Więcej informacji znajdziesz w sekcji Ograniczanie.

Krok 3. Ustaw domyślne wartości parametrów w aplikacji

Wartości domyślne parametrów w aplikacji możesz ustawić w obiekcie Remote Config, aby aplikacja działała zgodnie z oczekiwaniami, zanim połączy się z serwerem Remote Config, oraz aby były dostępne wartości domyślne, jeśli na serwerze nie ma żadnych ustawionych wartości.

Ważne: nie przechowuj poufnych danych w kluczach ani wartościach parametrów Remote Config. Dane Remote Config są szyfrowane podczas przesyłania, ale użytkownicy mają dostęp do dowolnego domyślnego lub pobranego parametru Remote Config, który jest dostępny dla ich instancji aplikacji klienckiej.

1. Zdefiniuj zestaw nazw parametrów i ich domyślnych wartości za pomocą obiektu Map lub pliku zasobu XML przechowywanego w folderze res/xml aplikacji. Przykładowa aplikacja Remote Config z krótkiego wprowadzenia korzysta z pliku XML do definiowania domyślnych nazw i wartości parametrów.

   Jeśli masz już skonfigurowane wartości parametrów backendu Remote Config, możesz pobrać wygenerowany plik XML zawierający wszystkie wartości domyślne i zapisz go w katalogu res/xml aplikacji:

   REST

   curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=XML -o remote_config_defaults.xml
   

   Konsola Firebase

   1. Na karcie Parametry otwórz Menu i wybierz Pobierz wartości domyślne.

   2. Gdy pojawi się odpowiedni komunikat, włącz plik.xml na Androida, a następnie kliknij Pobierz plik.

2. Dodaj te wartości do obiektu Remote Config za pomocą elementu setDefaultsAsync(int), jak pokazano poniżej:

   Kotlin

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

Krok 4. Uzyskaj wartości parametrów, które będą używane w Twojej aplikacji

Teraz możesz pobierać wartości parametrów z obiektu Remote Config. Jeśli ustawisz wartości w backendzie, pobierzesz je, a następnie aktywujesz, będą one dostępne w aplikacji. W przeciwnym razie otrzymasz wartości parametrów skonfigurowane w aplikacji za pomocą setDefaultsAsync(int). Aby uzyskać te wartości, wywołaj metodę wymienioną poniżej, która jest zmapowana na typ danych oczekiwany przez aplikację, podając jako argument klucz parametru:

• getBoolean()
• getDouble()
• getLong()
• getString()

Krok 5. Ustaw wartości parametrów w backendzie Remote Config

Za pomocą konsoli Firebase lub Remote Config backendowych interfejsów API możesz tworzyć nowe domyślne wartości po stronie serwera, które zastąpią wartości w aplikacji zgodnie z wybraną przez Ciebie logiką warunkową lub kierowaniem na użytkowników. W tej sekcji opisano czynności do wykonania w konsoli Firebase, aby utworzyć te wartości.

1. W konsoli Firebase otwórz projekt.
2. Aby wyświetlić panel Remote Config, w menu kliknij Remote Config.
3. Zdefiniuj parametry o tych samych nazwach co parametry zdefiniowane w aplikacji. Dla każdego parametru możesz ustawić wartość domyślną (która ostatecznie zastąpi odpowiadającą jej wartość domyślną w aplikacji), a także wartości warunkowe. Więcej informacji znajdziesz w artykule Remote Config Parametry i warunki.

4. Jeśli używasz warunków sygnału niestandardowego, zdefiniuj atrybuty i ich wartości. Poniższe przykłady pokazują, jak zdefiniować niestandardowy warunek sygnału.

   Kotlin

       val customSignals = customSignals {
           put("city", "Tokyo")
           put("preferred_event_category", "sports")
       }
   
       remoteConfig.setCustomSignals(customSignals)

   Java

       CustomSignals customSignals = new CustomSignals.Builder()
           .put("city", "Tokyo")
           .put("preferred_event_category", "sports")
           .build();
   
       mFirebaseRemoteConfig.setCustomSignals(customSignals);

Krok 6. Pobierz i aktywuj wartości

1. Aby pobrać wartości parametrów z back-endu Remote Config, wywołaj metodę fetch(). Wszystkie wartości ustawione na zapleczu są pobierane i przechowywane w obiekcie Remote Config.

2. Aby udostępnić wartości pobranych parametrów aplikacji, wywołaj metodę activate().

   Jeśli chcesz pobrać i aktywować wartości w jednym wywołaniu, możesz użyć żądania fetchAndActivate(), aby pobrać wartości z back-endu Remote Config i udostępnić je aplikacji:

   Kotlin

   remoteConfig.fetchAndActivate()
       .addOnCompleteListener(this) { task ->
           if (task.isSuccessful) {
               val updated = task.result
               Log.d(TAG, "Config params updated: $updated")
               Toast.makeText(
                   this,
                   "Fetch and activate succeeded",
                   Toast.LENGTH_SHORT,
               ).show()
           } else {
               Toast.makeText(
                   this,
                   "Fetch failed",
                   Toast.LENGTH_SHORT,
               ).show()
           }
           displayWelcomeMessage()
       }

   Java

   mFirebaseRemoteConfig.fetchAndActivate()
           .addOnCompleteListener(this, new OnCompleteListener<Boolean>() {
               @Override
               public void onComplete(@NonNull Task<Boolean> task) {
                   if (task.isSuccessful()) {
                       boolean updated = task.getResult();
                       Log.d(TAG, "Config params updated: " + updated);
                       Toast.makeText(MainActivity.this, "Fetch and activate succeeded",
                               Toast.LENGTH_SHORT).show();
   
                   } else {
                       Toast.makeText(MainActivity.this, "Fetch failed",
                               Toast.LENGTH_SHORT).show();
                   }
                   displayWelcomeMessage();
               }
           });

Zaktualizowane wartości parametrów wpływają na działanie i wygląd aplikacji, dlatego należy aktywować pobrane wartości w takim momencie, aby zapewnić użytkownikowi płynne działanie, np. gdy otworzy on aplikację. Więcej informacji i przykłady znajdziesz w artykule Strategie wczytywania Zdalnej konfiguracji.

Uwaga: jeśli Twoja aplikacja nie jest kompilowana za pomocą Gradle, musisz ręcznie dodać do niej odpowiedni zasób ciągu tekstowego google_app_id, aby można było zainicjować funkcję Remote Config. Wtyczka Gradle google-services zwykle dodaje te informacje automatycznie, ale odpowiednią wartość znajdziesz w pliku google-services.json pobranym z konsoli Firebase. Więcej informacji o pobieraniu wartości google_app_id z pliku google-services.json znajdziesz w artykule Przetwarzanie pliku JSON.

Krok 7. Słuchaj aktualizacji w czasie rzeczywistym

Po pobraniu wartości parametrów możesz używać interfejsu Remote Config w czasie rzeczywistym do odbierania aktualizacji z back-endu Remote Config. W czasie rzeczywistym Remote Config sygnalizuje połączonym urządzeniom, że są dostępne aktualizacje, i automatycznie pobiera zmiany po opublikowaniu nowej wersji Remote Config.

Aktualizacje w czasie rzeczywistym są obsługiwane przez pakiet SDK Firebase w wersji Android 21.3.0 lub nowszej (Firebase BoM w wersji 31.2.4 lub nowszej).

Ważne: funkcja Remote Config w czasie rzeczywistym wymaga też interfejsu Firebase Remote ConfigRealtime API, który powinien być już włączony. Aby to sprawdzić, otwórz konsolę Google Cloud, wybierz projekt i otwórz stronę Interfejsy API i usługi. Interfejs API powinien być widoczny jako włączony. Jeśli go brakuje lub nie jest włączony, kliknij Włącz interfejsy API i usługi, wyszukaj Firebase Remote Config Interfejs API w czasie rzeczywistym i go włącz.

1. W aplikacji użyj polecenia addOnConfigUpdateListener(), aby zacząć nasłuchiwać aktualizacji i automatycznie pobierać nowe wartości parametrów. Zaimplementuj wywołanie zwrotne onUpdate(), aby aktywować zaktualizowaną konfigurację.

   Kotlin

   remoteConfig.addOnConfigUpdateListener(object : ConfigUpdateListener {
       override fun onUpdate(configUpdate : ConfigUpdate) {
          Log.d(TAG, "Updated keys: " + configUpdate.updatedKeys);
   
          if (configUpdate.updatedKeys.contains("welcome_message")) {
              remoteConfig.activate().addOnCompleteListener {
                  displayWelcomeMessage()
              }
          }
       }
   
       override fun onError(error : FirebaseRemoteConfigException) {
           Log.w(TAG, "Config update error with code: " + error.code, error)
       }
   })

   Java

   mFirebaseRemoteConfig.addOnConfigUpdateListener(new ConfigUpdateListener() {
       @Override
       public void onUpdate(ConfigUpdate configUpdate) {
           Log.d(TAG, "Updated keys: " + configUpdate.getUpdatedKeys());
           mFirebaseRemoteConfig.activate().addOnCompleteListener(new OnCompleteListener<Boolean>() {
               @Override
               public void onComplete(@NonNull Task<Boolean> task) {
                   displayWelcomeMessage();
               }
           });
       }
       @Override
       public void onError(FirebaseRemoteConfigException error) {
           Log.w(TAG, "Config update error with code: " + error.getCode(), error);
       }
   });

2. Gdy następnym razem opublikujesz nową wersję Remote Config, urządzenia, na których jest uruchomiona Twoja aplikacja i które nasłuchują zmian, wywołają funkcję ConfigUpdateListener.

Ograniczenia

Jeśli aplikacja pobiera dane zbyt często w krótkim czasie, wywołania pobierania są ograniczane, a pakiet SDK zwraca wartość FirebaseRemoteConfigFetchThrottledException. Przed wersją 17.0.0 pakietu SDK limit wynosił 5 żądań pobierania w okresie 60 minut (nowsze wersje mają bardziej liberalne limity).

Wskazówka: od pakietu Android SDK w wersji 21.3.0 (Firebase BoM w wersji 31.3.0 lub nowszej) możesz używać Remote Config w czasie rzeczywistym, aby automatycznie pobierać zaktualizowane wartości parametrów z Remote Config backendu, gdy tylko zostaną opublikowane, bez względu na ustawienie minimalnego interwału pobierania. Więcej informacji znajdziesz w artykule o słuchaniu aktualizacji w czasie rzeczywistym.

Podczas tworzenia aplikacji możesz bardzo często (wiele razy na godzinę) pobierać i aktywować konfiguracje (na przykład wiele razy na godzinę), aby umożliwić szybkie iterowanie podczas tworzenia i testowania aplikacji. Aktualizacje w czasie rzeczywistym Remote Config automatycznie pomijają pamięć podręczną, gdy konfiguracja zostanie zaktualizowana na serwerze. Aby umożliwić szybkie iteracje w projekcie z do 10 deweloperami, możesz tymczasowo ustawić obiekt FirebaseRemoteConfigSettings z niskim minimalnym interwałem pobierania (setMinimumFetchIntervalInSeconds) w swojej aplikacji.

Domyślny minimalny interwał pobierania dla Remote Config wynosi 12 godzin, co oznacza, że konfiguracje nie będą pobierane z backendu częściej niż raz w ciągu 12 godzin, niezależnie od liczby wywołań funkcji pobierania. W szczególności minimalny interwał pobierania jest określany w tej kolejności:

1. Parametr w pliku fetch(long)
2. Parametr w pliku FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
3. Wartość domyślna 12 godzin

Aby ustawić minimalny interwał pobierania na wartość niestandardową, użyj parametru FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long).

Pamiętaj, że tego ustawienia należy używać tylko do celów programistycznych, a nie do uruchamiania aplikacji w środowisku produkcyjnym. Jeśli aplikację testuje mały zespół 10-osobowy, prawdopodobnie nie przekroczysz godzinnych limitów na stronie usługi. Jeśli jednak opublikujesz aplikację dla tysięcy użytkowników testowych z bardzo krótkim minimalnym interwałem pobierania, prawdopodobnie przekroczy ona ten limit.

Dalsze kroki

Jeśli jeszcze tego nie zrobisz, zapoznaj się z Remote Config przypadkami użycia i pojęciami kluczowymi oraz dokumentacją dotyczącą zaawansowanych strategii, w tym:

• Zarządzanie wersjami szablonu Remote Config
• Strategie wczytywania konfiguracji