Wprowadzenie do Zdalnej konfiguracji na iOS

Wybierz platformę:

iOS+ Android Web Flutter Unity C++

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 rozpocząć pracę, oraz przykładowy kod, który można sklonować lub pobrać z repozytorium GitHub firebase/quickstart-ios.

Krok 1. Dodaj Remote Config do aplikacji

1. Jeśli nie korzystasz jeszcze z Firebase, dodaj ją do projektu Apple.

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 pojedynczy obiekt Remote Config, jak w tym przykładzie:

   Swift

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

   Objective-C

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

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 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 2. 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ą NSDictionary obiektu 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 dostępu możesz wygenerować, uruchamiając to polecenie za pomocą Google Cloud CLI lub Cloud Shell:

   gcloud auth print-access-token
   

   Ten token ma krótki okres ważności, więc jeśli pojawi się błąd uwierzytelniania, może być konieczne ponowne wygenerowanie tokena.

   Firebase konsola

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

   2. Gdy pojawi się odpowiedni komunikat, włącz .plist na iOS, a następnie kliknij Pobierz plik.

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

   Swift

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

   Objective-C

   [remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];
   ObjCMigratedSnippets.m

Uwaga: te fragmenty kodu odnoszą się do pliku RemoteConfigDefaults.plist z przykładowego projektu quickstart-ios. Jeśli używasz pobranego pliku domyślnego, użyj remote_config_defaults.

Krok 3. Uzyskiwanie wartości parametrów do użycia w aplikacji

Możesz teraz pobierać wartości parametrów z obiektu Remote Config. Jeśli później ustawisz wartości w Remote Configbackendzie, pobierzesz je i aktywujesz,Remote Config będą one dostępne w Twojej aplikacji. W przeciwnym razie uzyskasz 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 czytelny i wygodny sposób uzyskiwania dostępu do tych wartości w Swift to notacja indeksu w Swift:

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 zachowaniem bezpieczeństwa typów

W przypadku bardziej złożonych konfiguracji możesz użyć protokołu Codable Swift, aby dekodować dane strukturalne z Remote Config. Umożliwia to zarządzanie konfiguracją z zachowaniem bezpieczeństwa typów i upraszcza 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 pozwala:

• Zdefiniuj złożone struktury konfiguracji.
• Automatyczne analizowanie konfiguracji JSON.
• Zapewnij bezpieczeństwo typów podczas uzyskiwania dostępu do wartości Remote Config.
• Udostępnij przejrzysty, czytelny kod do obsługi szablonów uporządkowanych Remote Config.

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

Otoczki 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 otoczki 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 otoki właściwości @RemoteConfigProperty, jeśli chcesz mieć 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ą Firebase konsoli lub Remote Config backendowych interfejsów API 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 Firebase konsoli.

1. W Firebasekonsoli otwórz projekt.
2. W menu wybierz Remote Config, aby wyświetlić panel Remote Config.
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 wartość domyślną w aplikacji) oraz wartości warunkowe. Więcej informacji znajdziesz w artykule 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.

   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 Remote Config, wywołaj metodę fetchWithCompletionHandler: lub fetchWithExpirationDuration:completionHandler:. Wszystkie wartości ustawione w backendzie są pobierane i buforowane w obiekcie Remote Config.

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

W tym przykładzie wartości są pobierane z backendu Remote Config (nie z pamięci podręcznej), a następnie wywoływana jest funkcja 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.")")
  }
}
MigratedSnippets.swift

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);
  }
}];
ObjCMigratedSnippets.m

Zaktualizowane wartości parametrów wpływają na zachowanie 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 6. Słuchaj aktualizacji w czasie rzeczywistym

Po pobraniu wartości parametrów możesz użyć Remote Config w czasie rzeczywistym, aby nasłuchiwać aktualizacji z backendu Remote Config. Sygnały w czasie rzeczywistymRemote Config informują połączone urządzenia o dostępności aktualizacji i Remote Configautomatycznie pobierają zmiany po opublikowaniu nowej wersji.

Aktualizacje w czasie rzeczywistym są obsługiwane przez pakiet SDK Firebase na platformy Apple w wersji 10.7.0 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, a następnie włącz go.

1. W aplikacji wywołaj funkcję addOnConfigUpdateListener, aby rozpocząć nasłuchiwanie aktualizacji i automatycznie pobierać nowe lub zaktualizowane wartości parametrów. Poniższy przykład nasłuchuje aktualizacji i gdy wywoływana jest funkcja activateWithCompletionHandler, używa nowo pobranych wartości do wyświetlania zaktualizowanego powitania.

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

Ograniczenia

Jeśli aplikacja zbyt często pobiera dane w krótkim czasie, wywołania pobierania są ograniczane, a pakiet SDK zwraca wartość FIRRemoteConfigFetchStatusThrottled. Przed wersją 6.3.0 pakietu SDK limit wynosił 5 żądań pobierania w 60-minutowym okresie obserwacji (nowsze wersje mają bardziej liberalne limity).

Wskazówka: od wersji 10.7.0 pakietu SDK na platformy Apple możesz używać funkcji Remote Configw czasie rzeczywistym, aby automatycznie pobierać zaktualizowane wartości parametrów z backendu Remote Configzaraz po ich opublikowaniu, z pominięciem ustawienia minimalnego interwału pobierania. Aby odświeżyć pamięć podręczną, możesz używać aktualizacji w czasie rzeczywistym zamiast częstego pobierania. Więcej informacji znajdziesz w artykule Słuchanie aktualizacji w czasie rzeczywistym.

Podczas tworzenia aplikacji możesz częściej pobierać dane, aby odświeżać pamięć podręczną (wiele razy na godzinę), co pozwoli Ci szybko wprowadzać zmiany w aplikacji i ją testować. Aktualizacje konfiguracji zdalnej w czasie rzeczywistym automatycznie pomijają pamięć podręczną, gdy konfiguracja zostanie zaktualizowana na serwerze. Aby umożliwić szybkie iteracje w projekcie, nad którym pracuje wielu deweloperów, możesz tymczasowo dodać w aplikacji usługę FIRRemoteConfigSettings z krótkim minimalnym interwałem pobierania (MinimumFetchInterval).

Domyślny i zalecany interwał pobierania w środowisku produkcyjnym w przypadku Remote Config wynosi 12 godzin. Oznacza to, ż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 FIRRemoteConfigSettings.MinimumFetchInterval
3. Wartość domyślna to 12 godzin.

Pamiętaj, że to ustawienie powinno być używane tylko w przypadku programowania, a nie w przypadku aplikacji działającej w środowisku produkcyjnym. Jeśli testujesz aplikację 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.