Начало работы с Remote Config в iOS

Вы можете использовать Firebase Remote Config, чтобы задавать параметры в приложении и обновлять их значения в облаке. Это позволяет изменять внешний вид и поведение приложения без выпуска обновлений. В этом руководстве приведены пошаговые инструкции по началу работы и образцы кода, которые можно клонировать или скачать из репозитория firebase/quickstart-ios на GitHub.

Шаг 1. Добавьте Remote Config в приложение

1. Если вы ещё этого не сделали, добавьте Firebase в проект Apple.

2. Для Remote Config необходимо использовать Google Analytics, чтобы реализовать условный таргетинг экземпляров приложения на свойства пользователей и аудитории. Убедитесь, что в проекте включен Google Analytics.

3. Создайте объект-одиночку Remote Config, как показано в следующем примере:

   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

Этот объект используется для хранения значений параметров по умолчанию в приложении, получения обновленных значений параметров из серверной части Remote Config и управления тем, когда полученные значения становятся доступны в приложении.

Во время разработки рекомендуется установить относительно низкий минимальный интервал выборки. Подробнее об ограничении скорости передачи данных…

Шаг 2. Задайте значения параметров по умолчанию в приложении

Вы можете задать значения параметров по умолчанию для объектов Remote Config, чтобы приложение работало нужным образом до подключения к серверной части Remote Config и чтобы значения по умолчанию были доступны, если они не заданы в серверной части.

1. Определите набор названий параметров и их значений по умолчанию, используя объект NSDictionary или файл plist.

   Если вы уже настроили значения серверных параметров Remote Config, вы можете скачать сгенерированный файл plist, в котором будут указаны все значения по умолчанию, и сохранить его в проекте 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
   

   Вы можете создать токен носителя, выполнив следующую команду с помощью Google Cloud CLI или Cloud Shell:

   gcloud auth print-access-token
   

   Токен действует недолго, поэтому, если вы получите ошибку аутентификации, вам может потребоваться сгенерировать его заново.

   Консоль Firebase

   1. В консоли Firebase выберите DevOps & Engagement (DevOps и взаимодействие) > Remote Config (Удаленная настройка) > Parameters (Параметры).

   2. Откройте more_vert Меню и выберите Скачать значения по умолчанию.

   3. Когда появится запрос, включите .plist для iOS и нажмите Скачать файл.

2. Добавьте эти значения в объект Remote Config, используя setDefaults:. В примере ниже показано, как задать значения по умолчанию для приложения из файла plist:

   Swift

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

   Objective-C

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

Шаг 3. Получите значения параметров, которые будут использоваться в приложении

Теперь вы можете получать значения параметров из объекта Remote Config. Если вы позже зададите значения в серверной части Remote Config, получите их и активируете, эти значения будут доступны в приложении. В противном случае вы получите значения параметров в приложении, настроенные с помощью setDefaults:. Чтобы получить эти значения, вызовите метод configValueForKey:, указав ключ параметра в качестве аргумента.

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

В 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

Используйте Codable для безопасной конфигурации

Для более сложных конфигураций можно использовать протокол Codable языка Swift, чтобы декодировать структурированные данные из Remote Config. Это обеспечивает безопасное управление конфигурацией и упрощает работу со сложными объектами.

// 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)")
    }
  }
}

Этот метод позволяет:

• Определять сложные структуры конфигурации.
• Автоматически анализировать конфигурации JSON.
• При доступе к значениям Remote Config соблюдайте безопасность типов.
• Предоставляйте понятный и легко читаемый код для работы со структурированными Remote Configшаблонами.

Используйте обертки свойств для декларативной конфигурации в SwiftUI

Обертки свойств – это мощная функция Swift, которая позволяет добавлять пользовательское поведение к объявлениям свойств. В SwiftUI обертки свойств используются для управления состоянием, привязками и другими свойствами. Дополнительную информацию можно найти в руководстве по языку 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()
    }
  }
}

Используйте обертку свойства @RemoteConfigProperty, если вам нужен декларативный способ доступа к значениям Remote Config в SwiftUI со встроенной поддержкой значений по умолчанию и упрощенным управлением конфигурацией.

Шаг 4. Задайте значения параметров

С помощью Firebase или серверных API Remote Config можно создавать новые значения по умолчанию, которые будут переопределять значения в приложении в соответствии с заданной логикой или таргетингом на пользователей. В этом разделе описано, как создать эти значения в консоли Firebase.

1. В консоли Firebase выберите DevOps & Engagement (DevOps и взаимодействие) > Remote Config (Удаленная настройка) > Parameters (Параметры).

2. Задайте параметры с теми же названиями, что и в приложении. Для каждого параметра можно задать значение по умолчанию (которое в конечном итоге заменит значение по умолчанию в приложении), а также условные значения. Подробнее о параметрах и условиях Remote Config…

3. Если вы используете условия для специальных сигналов, укажите атрибуты и их значения. Ниже приведены примеры того, как задать условие для собственного сигнала.

   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!");
             }
       }];
   });

Шаг 5. Получите и активируйте значения

Чтобы получить значения параметров из Remote Config, вызовите метод fetchWithCompletionHandler: или fetchWithExpirationDuration:completionHandler:. Все значения, заданные на сервере, извлекаются и кешируются в объекте Remote Config.

Если вам нужно получить и активировать значения за один вызов, используйте fetchAndActivateWithCompletionHandler:.

В этом примере значения извлекаются из серверной части Remote Config (не из кеша) и вызывается функция activateWithCompletionHandler:, чтобы сделать их доступными для приложения:

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

[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

Поскольку обновленные значения параметров влияют на поведение и внешний вид приложения, активировать полученные значения следует в момент, когда это не помешает пользователю, например при следующем открытии приложения. Дополнительную информацию и примеры можно найти в статье Стратегии загрузки Remote Config.

Шаг 6. Слушайте обновления в реальном времени

После того как вы получите значения параметров, вы можете использовать Remote Config в реальном времени, чтобы отслеживать обновления от серверной части Remote Config. Сигналы в реальном времени Remote Config передаются на подключенные устройства, когда становятся доступны обновления, и автоматически извлекают изменения после публикации новой версии Remote Config.

Обновления в реальном времени поддерживаются в SDK Firebase для платформ Apple версии 10.7.0 и более поздних.

1. В приложении вызовите метод addOnConfigUpdateListener, чтобы начать отслеживать обновления и автоматически получать новые или измененные значения параметров. В примере ниже показано, как отслеживать обновления и при вызове activateWithCompletionHandler использовать полученные значения для показа обновленного приветственного сообщения.

   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. Когда вы опубликуете новую версию Remote Config, устройства, на которых запущено ваше приложение и которые отслеживают изменения, вызовут обработчик завершения.

Ограничение пропускной способности

Если приложение запрашивает данные слишком часто за короткий период времени, вызовы функции получения данных ограничиваются и SDK возвращает код FIRRemoteConfigFetchStatusThrottled. До версии 6.3.0 SDK лимит составлял пять запросов на получение в течение 60 минут (в более новых версиях лимиты более мягкие).

Во время разработки приложения вам может потребоваться часто обновлять кеш (много раз в час), чтобы быстро вносить изменения и тестировать приложение. Обновления Remote Config в реальном времени автоматически пропускают кеш, когда конфигурация обновляется на сервере. Чтобы обеспечить быструю итерацию в проекте с большим количеством разработчиков, вы можете временно добавить в приложение свойство FIRRemoteConfigSettings с низким минимальным интервалом получения (MinimumFetchInterval).

Интервал получения данных для Remote Config по умолчанию и рекомендуемый интервал составляет 12 часов. Это означает, что конфигурации не будут извлекаться из серверной части чаще, чем раз в 12 часов, независимо от того, сколько вызовов извлечения было выполнено. Минимальный интервал получения определяется в следующем порядке:

1. Параметр в fetch(long)
2. Параметр в FIRRemoteConfigSettings.MinimumFetchInterval
3. Значение по умолчанию – 12 часов.