Wprowadzenie do Zdalnej konfiguracji Firebase

iOS+ Android Internet Flutter Unity C++

Ważne: w tej sekcji znajdziesz instrukcje konfigurowania Zdalnej konfiguracji w klientach mobilnych i internetowych. W przypadku środowisk serwera zapoznaj się z artykułem o korzystaniu ze Zdalnej konfiguracji w środowiskach serwerów.

Za pomocą Zdalnej konfiguracji Firebase możesz definiować parametry w aplikacji i aktualizować ich wartości w chmurze. Pozwala to modyfikować wygląd i działanie aplikacji bez jej aktualizowania. Ten przewodnik zawiera instrukcje i przykładowy kod, który możesz skopiować lub pobrać z repozytorium GitHub firebase/quickstart-android.

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

1. Dodaj Firebase do swojego projektu Android, chyba że masz to już za sobą.

2. Zdalna konfiguracja wymaga Google Analytics do kierowania warunkowego instancji aplikacji na odbiorców i właściwości użytkowników. Pamiętaj, aby włączyć Google Analytics w swoim projekcie.

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 biblioteki Zdalnej konfiguracji na Androida. Do kontrolowania obsługi wersji biblioteki zalecamy używanie funkcji Firebase Android BoM.

   Podczas konfigurowania Analytics musisz też dodać do swojej aplikacji pakiet SDK Firebase dla Google Analytics.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.1.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 BoM Firebase Android BoM Twoja aplikacja zawsze używa zgodnych wersji bibliotek Firebase na Androida.

   (Alternatywnie) Dodawanie zależności bibliotek Firebase bez korzystania z BM

   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 swojej aplikacji używasz wielu bibliotek Firebase, zdecydowanie zalecamy korzystanie z BoM do zarządzania wersjami bibliotek. Dzięki temu będziesz mieć pewność, że wszystkie wersje są 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.0.0")
       implementation("com.google.firebase:firebase-analytics:22.0.1")
   }
   

   Szukasz modułu biblioteki korzystającego z usługi Kotlin? Od października 2023 r. (Firebase BoM 32.5.0) zarówno deweloperzy aplikacji Kotlin, jak i języki Java mogą korzystać z modułu biblioteki głównej (więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania o tę inicjatywę).

Uwaga: pakiet Android SDK zależy od interfejsu Zdalnej konfiguracji REST API, więc upewnij się, że nie wyłączasz tego interfejsu API, który jest domyślnie włączony w typowym projekcie.

Krok 2. Pobierz obiekt klasy typu singleton Zdalnej konfiguracji

Pobierz instancję obiektu Zdalnej konfiguracji i ustaw minimalny interwał pobierania, aby umożliwić częste odświeżanie:

Kotlin+KTX

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 kontrolowania, kiedy pobrane wartości mają być udostępniane aplikacji.

Podczas programowania zalecamy ustawienie stosunkowo niskiego minimalnego odstępu pobierania. Więcej informacji znajdziesz w sekcji Ograniczanie wykorzystania.

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

W obiekcie Zdalnej konfiguracji możesz ustawić domyślne wartości parametrów aplikacji, dzięki czemu aplikacja będzie działać zgodnie z oczekiwaniami przed nawiązaniem połączenia z backendem Zdalnej konfiguracji, a jeśli w backendzie nie zostaną ustawione żadne wartości domyślne, będą one dostępne.

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

1. Zdefiniuj zbiór nazw parametrów i ich domyślnych wartości za pomocą obiektu Map lub pliku zasobów XML zapisanego w folderze res/xml aplikacji. Przykładowa aplikacja z szybkim wprowadzeniem Zdalnej konfiguracji używa pliku XML do definiowania domyślnych nazw i wartości parametrów.

   Jeśli masz już skonfigurowane wartości parametrów backendu Zdalnej konfiguracji, możesz pobrać wygenerowany plik XML ze wszystkimi wartościami domyślnymi i zapisać go w katalogu res/xml swojej 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ę prośba, włącz plik .xml na Androida, a następnie kliknij Pobierz plik.

2. Dodaj te wartości do obiektu Zdalnej konfiguracji za pomocą narzędzia setDefaultsAsync(int), jak pokazano poniżej:

   Kotlin+KTX

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

Krok 4. Pobierz wartości parametrów do wykorzystania w aplikacji

Teraz możesz pobierać wartości parametrów z obiektu Zdalnej konfiguracji. Jeśli ustawisz wartości w backendzie, pobierzesz je i aktywujesz, będą one dostępne dla Twojej aplikacji. W przeciwnym razie Twoje wartości parametrów w aplikacji zostaną skonfigurowane za pomocą metody setDefaultsAsync(int). Aby uzyskać te wartości, wywołaj podaną poniżej metodę, która jest mapowana na typ danych spodziewany przez aplikację, podając klucz parametru jako argument:

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

Krok 5. Ustaw wartości parametrów w backendzie Zdalnej konfiguracji

Za pomocą konsoli Firebase lub interfejsów API backendu Zdalnej konfiguracji możesz utworzyć nowe wartości domyślne po stronie serwera, które zastąpią wartości w aplikacji odpowiednio do oczekiwanej logiki warunkowej lub kierowania na użytkowników. W tej sekcji opisujemy, jak utworzyć te wartości w konsoli Firebase.

1. W konsoli Firebase otwórz projekt.
2. Z menu wybierz Zdalna konfiguracja, aby wyświetlić panel Zdalnej konfiguracji.
3. Zdefiniuj parametry o takich samych nazwach jak parametry zdefiniowane w aplikacji. Dla każdego parametru możesz ustawić wartość domyślną (która ostatecznie zastąpi odpowiednią wartość domyślną w aplikacji), a także możesz ustawić wartości warunkowe. Więcej informacji znajdziesz w artykule Parametry i warunki Zdalnej konfiguracji.

Krok 6. Pobierz i aktywuj wartości

1. Aby pobrać wartości parametrów z backendu Zdalnej konfiguracji, wywołaj metodę fetch(). Wszystkie wartości ustawione w backendzie są pobierane i przechowywane w obiekcie Zdalnej konfiguracji.

2. Aby udostępnić w aplikacji pobrane wartości parametrów, 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 Zdalnej konfiguracji i udostępnić je aplikacji:

   Kotlin+KTX

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

Te zaktualizowane wartości parametrów wpływają na działanie i wygląd aplikacji, dlatego musisz aktywować pobrane wartości w czasie, który zapewni użytkownikom płynne działanie, np. gdy następnym razem otworzy on Twoją aplikację. Więcej informacji i przykłady znajdziesz w artykule Strategie wczytywania Zdalnej konfiguracji.

Uwaga: jeśli Twoja aplikacja nie kompiluje się w Gradle, musisz ręcznie dodać do niej odpowiedni zasób ciągu google_app_id, aby umożliwić jej zainicjowanie Zdalna konfiguracja. Zwykle wtyczka do Gradle google-services dodaje tę wartość automatycznie, ale odpowiednią wartość można znaleźć 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 o przetwarzaniu pliku JSON.

Krok 7. Nasłuchuj aktualizacji w czasie rzeczywistym

Po pobraniu wartości parametrów możesz używać Zdalnej konfiguracji w czasie rzeczywistym do nasłuchiwania aktualizacji z backendu Zdalnej konfiguracji. Zdalna konfiguracja wysyła do połączonych urządzeń sygnały w czasie rzeczywistym o dostępności aktualizacji i automatycznie pobiera zmiany po opublikowaniu nowej wersji Zdalnej konfiguracji.

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

Ważne: Zdalna konfiguracja w czasie rzeczywistym wymaga też interfejsu Realtime API Zdalnej konfiguracji Firebase, który powinien już być włączony. Aby to sprawdzić, otwórz konsolę Google Cloud, wybierz swój projekt i otwórz stronę Interfejsy API i usługi. Interfejs API powinien być włączony. Jeśli nie ma tej opcji lub nie jest ona włączona, kliknij Włącz interfejsy API i usługi, wyszukaj Interfejs Realtime API Zdalnej konfiguracji Firebase i włącz go.

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

   Kotlin+KTX

   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() {
               @Override
               public void onComplete(@NonNull Task 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ę Zdalnej konfiguracji, urządzenia, na których działa Twoja aplikacja i nasłuchują zmian, wywołają funkcję ConfigUpdateListener.

Ograniczenia

Jeśli aplikacja pobierze zbyt wiele razy w krótkim czasie, wywołania pobierania są ograniczane, a pakiet SDK zwraca FirebaseRemoteConfigFetchThrottledException. Przed wersją 17.0.0 pakietu SDK obowiązywał limit 5 żądań pobierania w 60-minutowym okresie (nowsze wersje mają bardziej rygorystyczne limity).

Wskazówka: od pakietu SDK Android w wersji 21.3.0 lub nowszej (Firebase BoM w wersji 31.3.0 lub nowszej) możesz używać Zdalnej konfiguracji w czasie rzeczywistym do automatycznego pobierania zaktualizowanych wartości parametrów z backendu Zdalnej konfiguracji, gdy tylko zostaną one opublikowane, z pominięciem minimalnego ustawienia interwału pobierania. Więcej informacji znajdziesz w sekcji Nasłuchuj aktualizacji w czasie rzeczywistym.

Podczas tworzenia aplikacji warto często pobierać i aktywować konfiguracje, by umożliwić szybkie iteracje podczas tworzenia i testowania aplikacji. Zdalna konfiguracja w czasie rzeczywistym automatycznie pomija pamięć podręczną po zaktualizowaniu konfiguracji na serwerze. Aby zapewnić szybką iterację projektu obejmującego maksymalnie 10 deweloperów, możesz tymczasowo ustawić w aplikacji obiekt FirebaseRemoteConfigSettings z krótkim minimalnym odstępem czasu pobierania (setMinimumFetchIntervalInSeconds).

Domyślny minimalny interwał pobierania dla Zdalnej konfiguracji to 12 godzin, co oznacza, że konfiguracje będą pobierane z backendu tylko raz w ciągu 12 godzin, niezależnie od tego, ile rzeczywiście zostało wykonanych wywołań pobierania. Minimalny odstęp czasu pobierania jest określany w tej kolejności:

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

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

Pamiętaj, że to ustawienie powinno być używane tylko na potrzeby programowania, a nie do aplikacji działających w środowisku produkcyjnym. Jeśli testujesz aplikację w niewielkim 10-osobowym zespole programistycznym, raczej nie możesz przekroczyć godzinowego limitu po stronie usługi. Gdyby jednak rozpowszechniłeś swoją aplikację tysiącom użytkowników testowych przy bardzo krótkim minimalnym odstępie czasu pobierania, prawdopodobnie przekroczyłaby ten limit.

Dalsze kroki

Zapoznaj się z przypadkami użycia Zdalnej konfiguracji i zapoznaniem się z niektórymi kluczowymi pojęciami i dokumentacją zaawansowanych strategii, w tym:

• Zarządzanie wersjami szablonów Zdalnej konfiguracji
• Strategie wczytywania konfiguracji