Pierwsze kroki ze Zdalnej konfiguracji Firebase

iOS+ Android Web Flutter Unity C++

Ważne: w tej sekcji opisujemy czynności, które należy wykonać, aby skonfigurować Remote Config z klientami mobilnymi i internetowymi. W przypadku środowisk serwera zapoznaj się z artykułem Używanie Remote Config w środowiskach serwera.

Możesz używać Firebase Remote Config do definiowania parametrów w aplikacji i aktualizowania ich wartości w chmurze, co pozwala modyfikować wygląd i działanie aplikacji bez rozpowszechniania jej aktualizacji. Ten przewodnik zawiera instrukcje, jak zacząć korzystać z usługi, oraz przykładowy kod, który możesz sklonować lub pobrać z repozytorium GitHub firebase/quickstart-android.

Krok 1. Dodaj do aplikacji Firebase i pakiet SDK 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 kierowania warunkowego instancji aplikacji na odbiorców i właściwości użytkowników. Sprawdź, czy w projekcie włączona jest 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.16.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")
   }

   Gdy korzystamy z Firebase Android BoM, aplikacja zawsze używa zgodnych wersji bibliotek Firebase na Androida.

   (Alternatywnie)  Dodaj zależności biblioteki Firebase bez użycia BoM

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

   Pamiętaj, że jeśli w aplikacji używasz wielu bibliotek Firebase, zdecydowanie zalecamy korzystanie z BoM do zarządzania wersjami bibliotek, co zapewnia zgodność wszystkich wersji.

   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.5.0")
   }

   Szukasz modułu biblioteki przeznaczonego specjalnie dla języka Kotlin? Od października 2023 r. Firebase BoM(wersja 32.5.0) deweloperzy korzystający z języków Kotlin i Java mogą używać głównego modułu biblioteki (szczegółowe informacje znajdziesz w odpowiedziach na najczęstsze pytania dotyczące tej inicjatywy).

Uwaga: pakiet SDK do Androida jest zależny od interfejsu Remote Config REST API, więc nie wyłączaj tego interfejsu, który jest domyślnie włączony w typowym projekcie.

Krok 2. Pobierz obiekt singleton Remote Config

Pobierz instancję obiektu Remote Config i ustaw minimalny interwał pobierania, aby umożliwić 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 singleton służy do przechowywania domyślnych wartości parametrów w aplikacji, pobierania zaktualizowanych wartości parametrów z backendu i określania, kiedy pobrane wartości mają być udostępniane aplikacji.

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

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

W obiekcie Remote Config możesz ustawić domyślne wartości parametrów w aplikacji, aby działała ona zgodnie z oczekiwaniami, zanim połączy się z backendem Remote Config, oraz aby wartości domyślne były dostępne, jeśli żadne nie są ustawione w backendzie.

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

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

   Jeśli masz już skonfigurowane Remote Config wartości parametrów backendu, możesz pobrać wygenerowany plik XML zawierający wszystkie wartości domyślne i zapisać 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
   

   Firebase konsola

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

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

2. Dodaj te wartości do obiektu Remote Config za pomocą funkcji 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

Możesz teraz 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 Twojej aplikacji. W przeciwnym razie uzyskasz wartości parametrów w aplikacji skonfigurowane za pomocą setDefaultsAsync(int). Aby uzyskać te wartości, wywołaj metodę wymienioną poniżej, która jest mapowana na typ danych oczekiwany przez aplikację, podając klucz parametru jako argument:

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

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

Za pomocą Firebasekonsoli lub Remote Configbackendowych interfejsów API możesz tworzyć nowe domyślne wartości po stronie serwera, które zastępują wartości w aplikacji zgodnie z wybraną logiką warunkową lub kierowaniem na użytkowników. W tej sekcji opisujemy Firebase kroki w konsoli, które należy wykonać, aby utworzyć te wartości.

1. W Firebasekonsoli otwórz projekt.
2. W menu wybierz Remote Config, aby wyświetlić Remote Configpanel.
3. Zdefiniuj parametry o takich samych nazwach jak parametry zdefiniowane w aplikacji. W przypadku każdego parametru możesz ustawić wartość domyślną (która ostatecznie zastąpi odpowiednią wartość domyślną w aplikacji) oraz wartości warunkowe. Więcej informacji znajdziesz w sekcji Remote Config Parametry i warunki.

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

   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 backendu Remote Config, wywołaj metodę fetch(). Wszystkie wartości ustawione w backendzie są pobierane i przechowywane w obiekcie Remote Config.

2. Aby pobrane wartości parametrów były dostępne 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 backendu 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 momencie, który zapewni użytkownikowi płynne działanie aplikacji, np. przy następnym otwarciu aplikacji. 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 prawidłowy zasób ciągu tekstowego google_app_id, aby można było zainicjować Remote Config. Wtyczka Gradle zwykle dodaje tę wartość automatycznie, ale odpowiednią wartość znajdziesz w pliku google-services.json pobranym z konsoli Firebase.google-services 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żyć Remote Config w czasie rzeczywistymRemote Config, aby nasłuchiwać aktualizacji z backendu. Sygnały w czasie rzeczywistymRemote Config informują połączone urządzenia o dostępności aktualizacji i automatycznie pobierają zmiany po opublikowaniu nowej Remote Config wersji.

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

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

1. W aplikacji użyj addOnConfigUpdateListener(), aby rozpocząć nasłuchiwanie 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 działa Twoja aplikacja i które nasłuchują zmian, wywołają ConfigUpdateListener.

Ograniczenia

Jeśli aplikacja pobiera dane zbyt wiele razy 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 wersji 21.3.0 pakietu SDK na Androida (Firebase BoM od wersji 31.3.0) możesz używać funkcji czasu rzeczywistegoRemote Config, aby automatycznie pobierać zaktualizowane wartości parametrów z Remote Config backendu zaraz po ich opublikowaniu, z pominięciem ustawienia minimalnego interwału pobierania. Więcej informacji znajdziesz w artykule Słuchanie aktualizacji w czasie rzeczywistym.

Podczas tworzenia aplikacji możesz często (wiele razy na godzinę) pobierać i aktywować konfiguracje, aby szybko wprowadzać zmiany w aplikacji i ją testować. Aktualizacje w czasie rzeczywistym Remote Config automatycznie pomijają pamięć podręczną, gdy konfiguracja jest aktualizowana na serwerze. Aby umożliwić szybkie iteracje w projekcie z udziałem maksymalnie 10 deweloperów, możesz tymczasowo ustawić w aplikacji obiekt FirebaseRemoteConfigSettings z niskim minimalnym interwałem pobierania (setMinimumFetchIntervalInSeconds).

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 tego, ile wywołań pobierania zostanie faktycznie wykonanych. Minimalny interwał pobierania jest określany w tej kolejności:

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

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

Pamiętaj, że to ustawienie powinno być używane tylko w przypadku aplikacji w trakcie tworzenia, a nie aplikacji działających w środowisku produkcyjnym. Jeśli testujesz aplikację tylko z małym, 10-osobowym zespołem deweloperskim, prawdopodobnie nie przekroczysz godzinnych limitów po stronie usługi. Jeśli jednak udostępnisz aplikację tysiącom testerów z bardzo krótkim minimalnym interwałem pobierania, prawdopodobnie przekroczysz ten limit.

Dalsze kroki

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

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