Wprowadzenie do Zdalnej konfiguracji na iOS

Wybierz platformę: iOS+ Android Web Flutter Unity C++


Za pomocą Firebase Remote Config możesz definiować parametry w aplikacji i aktualizować ich wartości w chmurze, co pozwala modyfikować wygląd i działanie aplikacji bez konieczności rozpowszechniania aktualizacji aplikacji. W tym przewodniku znajdziesz instrukcje, które pomogą Ci rozpocząć korzystanie z tej usługi, oraz przykładowy kod, który możesz sklonować lub pobrać z repozytorium firebase/quickstart-ios na GitHubie.

Krok 1. Dodaj Remote Config do aplikacji

  1. Dodaj Firebase do projektu aplikacji na urządzenia Apple, jeśli nie korzystasz w nim jeszcze z tej usługi.

  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. Pamiętaj, aby włączyć Google Analytics w swoim projekcie.

  3. Utwórz obiekt singleton Remote Config, jak w tym przykładzie:

    Swift

    let remoteConfig = RemoteConfig.remoteConfig()
let settings = RemoteConfigSettings()
settings.minimumFetchInterval = 0
RemoteConfig.remoteConfig().configSettings = settings

    Objective-C

    FIRRemoteConfig *remoteConfig = [FIRRemoteConfig remoteConfig];
FIRRemoteConfigSettings *remoteConfigSettings = [[FIRRemoteConfigSettings alloc] init];
remoteConfigSettings.minimumFetchInterval = 0;
remoteConfig.configSettings = remoteConfigSettings;

Ten obiekt służy do przechowywania domyślnych wartości parametrów w aplikacji, pobierania zaktualizowanych wartości parametrów z backendu Remote Config i kontrolowania, kiedy pobrane wartości są udostępniane aplikacji.

Podczas programowania zalecamy ustawienie stosunkowo krótkiego minimalnego interwału pobierania. Więcej informacji znajdziesz w sekcji Ograniczanie.

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

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

  1. Zdefiniuj zestaw nazw parametrów i ich wartości domyślnych za pomocą obiektu NSDictionary lub pliku plist.

    Jeśli masz już skonfigurowane wartości parametrów backendu Remote Config, możesz pobrać wygenerowany plik plist, który zawiera wszystkie wartości domyślne, i zapisać go w projekcie Xcode.

    REST

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

    Token okaziciela możesz wygenerować, uruchamiając to polecenie za pomocą Google Cloud CLI lub Cloud Shell:

    gcloud auth print-access-token

    Ten token jest krótkotrwały, więc jeśli pojawi się błąd uwierzytelniania, może być konieczne jego ponowne wygenerowanie.

    Konsola Firebase

    1. W konsoli Firebase otwórz stronę DevOps i zaangażowanie > Zdalna konfiguracja > Parametry.

    2. Otwórz Menu i wybierz Pobierz wartości domyślne.

    3. Gdy pojawi się prośba, włącz .plist dla iOS, a następnie kliknij Pobierz plik.

  2. Dodaj te wartości do obiektu Remote Config za pomocą setDefaults:. W tym przykładzie ustawiono domyślne wartości w aplikacji z pliku plist:

    Swift

    RemoteConfig.remoteConfig().setDefaults(fromPlist: "RemoteConfigDefaults")

    Objective-C

    [remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];

Krok 3. 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 później ustawisz wartości w backendzie Remote Config, pobierzesz je, a następnie aktywujesz, będą one dostępne dla aplikacji. W przeciwnym razie otrzymasz wartości parametrów w aplikacji skonfigurowane za pomocą setDefaults:. Aby uzyskać te wartości, wywołaj metodę configValueForKey:, podając klucz parametru jako argument.

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a parameter value using configValueForKey
let welcomeMessageValue = remoteConfig.configValue(forKey: "welcome_message")
let welcomeMessage = welcomeMessageValue.stringValue

let featureFlagValue = remoteConfig.configValue(forKey: "new_feature_flag")
let isFeatureEnabled = featureFlagValue.boolValue

Bardziej czytelnym i wygodnym sposobem uzyskiwania dostępu do tych wartości w języku Swift jest użycie notacji indeksu dolnego:

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a string parameter value
let welcomeMessage = remoteConfig["welcome_message"].stringValue

// Retrieve a boolean parameter value
let isFeatureEnabled = remoteConfig["new_feature_flag"].boolValue

// Retrieve a number parameter value
let maxItemCount = remoteConfig["max_items"].numberValue.intValue

Używanie protokołu Codable do konfiguracji z zabezpieczeniami wpisywania

W przypadku bardziej złożonych konfiguracji możesz użyć protokołu Codable języka Swift, aby dekodować uporządkowane dane z Remote Config. Zapewnia to zarządzanie konfiguracją z zabezpieczeniami wpisywania i ułatwia pracę ze złożonymi obiektami.

// Define a Codable struct for your configuration
struct AppFeatureConfig: Codable {
  let isNewFeatureEnabled: Bool
  let maxUploadSize: Int
  let themeColors: [String: String]
}

// Fetch and decode the configuration
func configureAppFeatures() {
  let remoteConfig = RemoteConfig.remoteConfig()
  remoteConfig.fetchAndActivate { status, error in
    guard error == nil else { return }

    do {
      let featureConfig = try remoteConfig["app_feature_config"].decoded(asType: AppFeatureConfig.self)
      configureApp(with: featureConfig)
    } catch {
      // Handle decoding errors
      print("Failed to decode configuration: \(error)")
    }
  }
}

Ta metoda umożliwia:

  • definiować złożone struktury konfiguracji,
  • Automatycznie analizuj konfiguracje JSON.
  • Zapewnij zabezpieczenia wpisywania podczas uzyskiwania dostępu do wartości Remote Config.
  • Podaj przejrzysty, czytelny kod do obsługi uporządkowanych szablonów Remote Config.

Używanie opakowań właściwości do konfiguracji deklaratywnej w SwiftUI

Opakowania właściwości to zaawansowana funkcja języka Swift, która umożliwia dodawanie niestandardowych zachowań do deklaracji właściwości. W SwiftUI opakowania właściwości służą do zarządzania stanem, powiązaniami i innymi zachowaniami właściwości. Więcej informacji znajdziesz w przewodniku po języku Swift.

struct ContentView: View {
  @RemoteConfigProperty(key: "cardColor", fallback: "#f05138")
  var cardColor

  var body: some View {
    VStack {
      Text("Dynamic Configuration")
        .background(Color(hex: cardColor))
    }
    .onAppear {
      RemoteConfig.remoteConfig().fetchAndActivate()
    }
  }
}

Użyj opakowania właściwości @RemoteConfigProperty, jeśli chcesz uzyskać deklaratywny sposób dostępu do wartości Remote Config w SwiftUI z wbudowaną obsługą wartości domyślnych i uproszczonym zarządzaniem konfiguracją.

Krok 4. Ustaw wartości parametrów

Za pomocą konsoli Firebase lub interfejsów API backendu Remote Config możesz tworzyć nowe domyślne wartości backendu, które zastępują wartości w aplikacji zgodnie z wybraną logiką warunkową lub kierowaniem na użytkowników. W tej sekcji znajdziesz instrukcje tworzenia tych wartości w konsoli Firebase.

  1. W konsoli Firebase otwórz stronę DevOps i zaangażowanie > Zdalna konfiguracja > Parametry.

  2. 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 wartość domyślną w aplikacji) oraz wartości warunkowe. Więcej informacji znajdziesz w artykule Parametry i warunki Remote Config.

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

    Swift

        Task {
        let customSignals: [String: CustomSignalValue?] = [
        "city": .string("Tokyo"),
        "preferred_event_category": .string("sports")
      ]

      do {
        try await remoteConfig.setCustomSignals(customSignals)
        print("Custom signals set successfully!")
        } catch {
            print("Error setting custom signals: \(error)")
        }
  }

    Objective-C

        dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
      NSDictionary *customSignals = @{
        @"city": @"Tokyo",
        @"preferred_event_category": @"sports"
      };

      [self.remoteConfig setCustomSignals:customSignals withCompletion:^(NSError * _Nullable error) {
          if (error) {
              NSLog(@"Error setting custom signals: %@", error);
          } else {
              NSLog(@"Custom signals set successfully!");
          }
    }];
});

Krok 5. Pobierz i aktywuj wartości

Aby pobrać wartości parametrów z usługi Remote Config, wywołaj metodę fetchWithCompletionHandler: lub fetchWithExpirationDuration:completionHandler:. Wszystkie wartości ustawione w backendzie są pobierane i zapisywane w pamięci podręcznej w obiekcie Remote Config.

Jeśli chcesz pobrać i aktywować wartości w jednym wywołaniu, użyj metody fetchAndActivateWithCompletionHandler:.

Ten przykład pobiera wartości z backendu Remote Config (nie wartości z pamięci podręcznej) i wywołuje activateWithCompletionHandler:, aby udostępnić je aplikacji:

Swift

remoteConfig.fetch { (status, error) -> Void in
  if status == .success {
    print("Config fetched!")
    remoteConfig.activate { changed, error in
      // ...
    }
  } else {
    print("Config not fetched")
    print("Error: \(error?.localizedDescription ?? "No error available.")")
  }
}

Objective-C

[remoteConfig fetchWithCompletionHandler:^(FIRRemoteConfigFetchStatus status, NSError *error) {
  if (status == FIRRemoteConfigFetchStatusSuccess) {
    NSLog(@"Config fetched!");
    [remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"Activate error: %@", error.localizedDescription);
      } else {
        dispatch_async(dispatch_get_main_queue(), ^{
          // update UI
        });
      }
    }];
  } else {
    NSLog(@"Config not fetched");
    NSLog(@"Error %@", error.localizedDescription);
  }
}];

Zaktualizowane wartości parametrów wpływają na zachowanie i wygląd aplikacji, dlatego należy je aktywować w momencie, który zapewni użytkownikowi płynne działanie aplikacji, np. przy następnym jej otwarciu. Więcej informacji i przykłady znajdziesz w artykule o strategiach wczytywania Zdalnej konfiguracji.

Krok 6. Słuchaj aktualizacji w czasie rzeczywistym

Po pobraniu wartości parametrów możesz używać Remote Config w czasie rzeczywistym, aby nasłuchiwać aktualizacji z backendu Remote Config. Remote Config wysyła sygnały do połączonych urządzeń w czasie rzeczywistym, gdy dostępne są aktualizacje, i automatycznie pobiera zmiany po opublikowaniu nowej wersji Remote Config.

Aktualizacje w czasie rzeczywistym są obsługiwane przez pakiet SDK Firebase na platformach Apple w wersji 10.7.0 lub nowszej.

  1. W aplikacji wywołaj addOnConfigUpdateListener, aby zacząć nasłuchiwać aktualizacji i automatycznie pobierać nowe lub zaktualizowane wartości parametrów. Poniższy przykład nasłuchuje aktualizacji, a gdy wywoływana jest metoda activateWithCompletionHandler, używa nowo pobranych wartości do wyświetlenia zaktualizowanej wiadomości powitalnej.

    Swift

    remoteConfig.addOnConfigUpdateListener { configUpdate, error in
    guard let configUpdate, error == nil else {
      print("Error listening for config updates: \(error)")
    }

    print("Updated keys: \(configUpdate.updatedKeys)")

    self.remoteConfig.activate { changed, error in
      guard error == nil else { return self.displayError(error) }
      DispatchQueue.main.async {
        self.displayWelcome()
      }
    }
  }

    Objective-C

    __weak __typeof__(self) weakSelf = self;
  [self.remoteConfig addOnConfigUpdateListener:^(FIRRemoteConfigUpdate * _Nonnull configUpdate, NSError * _Nullable error) {
    if (error != nil) {
      NSLog(@"Error listening for config updates %@", error.localizedDescription);
    } else {
      NSLog(@"Updated keys: %@", configUpdate.updatedKeys);

      __typeof__(self) strongSelf = weakSelf;
      [strongSelf.remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
        if (error != nil) {
          NSLog(@"Activate error %@", error.localizedDescription);
        }

        dispatch_async(dispatch_get_main_queue(), ^{
          [strongSelf displayWelcome];
        });
      }];
    }
  }];

  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ą moduł obsługi zakończenia.

Ograniczenia

Jeśli aplikacja pobiera dane zbyt wiele razy w krótkim czasie, wywołania pobierania są ograniczane, a pakiet SDK zwraca błąd FIRRemoteConfigFetchStatusThrottled. Przed wersją 6.3.0 pakietu SDK limit wynosił 5 żądań pobrania w 60-minutowym oknie (nowsze wersje mają bardziej liberalne limity).

Podczas tworzenia aplikacji możesz pobierać dane częściej, aby bardzo często (wiele razy na godzinę) odświeżać pamięć podręczną. Pozwoli Ci to na szybkie wprowadzanie zmian podczas tworzenia i testowania aplikacji. Aktualizacje Zdalnej konfiguracji w czasie rzeczywistym automatycznie pomijają pamięć podręczną, gdy konfiguracja jest aktualizowana na serwerze. Aby umożliwić szybkie iteracje w projekcie z wieloma deweloperami, możesz tymczasowo dodać w aplikacji właściwość FIRRemoteConfigSettings z krótkim minimalnym interwałem pobierania (MinimumFetchInterval).

Domyślny i zalecany interwał pobierania w środowisku produkcyjnym dla Remote Config wynosi 12 godzin, co oznacza, że konfiguracje nie będą pobierane z backendu częściej niż raz na 12 godzin, niezależnie od tego, ile wywołań pobierania zostanie faktycznie wykonanych. Minimalny interwał pobierania jest określany w następującej kolejności:

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