Pierwsze kroki ze Zdalnej konfiguracji Firebase


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. 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).

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)

Java

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

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.

  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:

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.

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).

  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).

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).

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: