Pierwsze kroki ze Zdalnej konfiguracji Firebase


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 sklonować 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. 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.

    Podczas 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.9.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 korzystasz z Firebase Android BoM, aplikacja zawsze używa zgodnych wersji bibliotek Firebase na Androida.

    Jeśli zdecydujesz się nie używać Firebase BoM, musisz podać każdą wersję biblioteki Firebase w linii 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.0")
        implementation("com.google.firebase:firebase-analytics:22.2.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).

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:

KotlinJava
val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
val configSettings = remoteConfigSettings {
    minimumFetchIntervalInSeconds = 3600
}
remoteConfig.setConfigSettingsAsync(configSettings)
FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);

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 ustawić stosunkowo krótki minimalny interwał pobierania. Więcej informacji znajdziesz w artykule na temat ograniczania.

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.

  1. Zdefiniuj zestaw nazw parametrów i ich wartości domyślnych 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:

    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
    
    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ą atrybutu setDefaultsAsync(int), jak pokazano poniżej:

    KotlinJava
    remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)
    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ą parametru 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 jako argument klucz parametru:

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.

    KotlinJava
        val customSignals = customSignals {
            put("city", "Tokyo")
            put("preferred_event_category", "sports")
        }
    
        remoteConfig.setCustomSignals(customSignals)
        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:

    KotlinJava
    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()
        }
    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ę po raz kolejny. 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ż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).

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

    KotlinJava
    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)
        }
    })
    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ę aplikacji Remote Config, urządzenia, na których jest ona uruchomiona 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).

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

Domyślny minimalny interwał pobierania w przypadku Remote Config wynosi 12 godzin, co oznacza, że konfiguracje nie będą pobierane z back-endu częściej niż raz w ciągu 12-godzinnego okna, 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).

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: