Интеграция SDK для библиотек

При использовании Varioqub в библиотеках может возникнуть ситуация, когда библиотекам нужен свой набор A/B экспериментов.

Для решения этой проблемы используется VarioqubInstance. Методы аналогичны VarioqubFacade.

Требования к библиотеке:

• iOS, версия 12 и выше.
• Xcode 14.1 и выше.

Общие рекомендации при интеграции

1. При старте новой сессии вызывайте метод VarioqubInstance.activateConfigAndWait(), чтобы получить значения сохраненных флагов.
2. Запускайте VarioqubInstance.fetchConfig в фоне, чтобы выгрузить новые значения флагов с сервера и активировать их при старте следующей сессии.
3. Не рекомендуется вызывать метод VarioqubInstance.activateConfigAndWait() в середине сессии — это может привести к неконсистентному поведению приложения.

Шаг 1. Подключите библиотеку в проект

Библиотека может работать со следующими системами управления зависимостями:

pod 'Varioqub', '~> 0.8'
pod 'Varioqub/MetricaAdapterReflection', '~> 0.8'

pod 'AppMetricaAnalytics', '~> 5.10.0'

pod 'Varioqub', '~> 0.8'

pod 'Varioqub/MetricaAdapter', '~> 0.8'

Шаг 2. Инициализируйте библиотеку

Для инициализации Varioqub используется метод VarioqubFacade.initializeInstance(clientId:config:idProvider:reporter:). Ниже пример инициализации:

let libInstance = VarioqubFacade.initializeInstance(
  clientId: libraryClientId,
  config: libConfig,
  idProvider: libAdapter,
  reporter: libAdapter
)

В качестве параметров он принимает:

• clientId: String. Идентификатор вашего проекта в формате appmetrica.XXXXXX, где XXXXXX — идентификатор приложения из интерфейса AppMetrica (например, clientId: "appmetrica.1234567").

  Совет

  ID приложения можно получить на странице Настройки AppMetrica: скопируйте его из Общие настройки → ID приложения.

• config: VarioqubConfig. Конфигурация Varioqub по умолчанию. Дополнительно можно передать список пользовательских параметров в clientFeatures. Например, признак того, что пользователь подписан на рассылки.

• idProvider: VarioqubIdProvider. Адаптер для сбора и передачи статистики в аналитическую систему, например, в AppMetrica. Если вы не хотите собирать статистику, передайте nil.

• reporter: VarioqubReporter. Адаптер для сбора и передачи статистики в аналитическую систему, например, в AppMetrica. Если вы не хотите собирать статистику, передайте nil.

  Важно

  reporter хранится как weak ссылка внутри Varioqub. Если вы передаете объект, предусмотрите, чтобы он не уничтожился раньше времени.

  import Varioqub
  import MetricaAdapterReflection
  
  let libraryClientId = "INSERT CLIENT ID"
  let libConfig: VarioqubConfig = {
    var vqCfg = VarioqubConfig.default
    vqCfg.clientFeatures["feature1"] = "value1"
    return vqCfg
  }()
  let libAdapter = {
      let adapter = AppmetricaAdapter()
      adapter.setCustomReporter("APP METRICA API KEY")
      return adapter
  }()
  
  let libInstance = VarioqubFacade.initializeInstance(
      clientId: libraryClientId,
      config: libConfig,
      idProvider: libAdapter,
      reporter: libAdapter
  )
  
  func libraryInit() {
    libInstance.activateConfigAndWait()
    libInstance.fetchConfig(nil)
  
    if libInstance.getBool(for: .myFlag) {
       // do something
    }
  }
  

Конфигурация VarioqubConfig

В конфигурации используются значения по умолчанию.

public struct VarioqubConfig {
    public var baseURL: URL?
    public var settings: VarioqubSettingsProtocol?
    public var network: NetworkRequestCreator?
    public var fetchThrottle: TimeInterval?
    public var clientFeatures: [String: String] = [:]
    public var varioqubQueue: DispatchQueue?
    public var outputQueue: DispatchQueue = .main

    public static var `default`: VarioqubConfig = VarioqubConfig()
}

Дополнительно можно передать:

• clientFeatures — список пользовательских параметров. Например, признак того, что пользователь подписан на рассылки.

  vqCfg.clientFeatures["feature1"] = "value1"
  

• fetchThrottle — ограничение частоты обновления конфига в секундах. Рекомендуется использовать только для тестирования.

  var vqCfg = VarioqubConfig.default
  vqCfg.fetchThrottle = 2 // seconds
  

Шаг 3. Задайте конфигурацию по умолчанию с помощью XML-файла

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

1. Скачайте XML-файл конфигурации со страницы Конфиг флагов и сохраните его в своем Xcode проекте.

2. Передайте загруженный XML-файл конфигурации с помощью метода loadXml.

let path = URL(fileURLWithPath: "/full/path/to/my/file/defaults.xml")
libInstance.loadXml(at: path, callback: nil)

Шаг 4. Запустите обновление конфигурации флагов в фоне

Чтобы использовать самую свежую конфигурацию флагов из интерфейса, запустите фоновое обновление конфигурации с помощью метода fetchConfig.

libInstance.fetchConfig({ status in
    switch status {
        case .success: print("success")
        case .throttled, .cached: print("already latest")
        case .error(let e): print("error: \(e)")
    }
})

Шаг 5. Активируйте конфигурацию

Активируйте конфигурацию с помощью метода activateConfigAndWait().

libInstance.shared.activateConfigAndWait()

Используйте метод activateConfigAndWait() каждый раз, когда необходимо активировать полученную/загруженную конфигурацию (например, при старте новой сессии).

Получение флагов из интерфейса

Значения флагов вычисляются и предоставляются в следующем порядке:

1. Флаг есть в эксперименте.
2. Флаг есть в загруженной конфигурации.
3. Флаг есть в конфигурации по умолчанию.

Методы для получения флагов:

• libInstance.getString(flag, defaultValue).

Пример кода:

extension VarioqubFlag {
    static let myFlag = VarioqubFlag(rawValue: "myFlag")
}

let flag = libInstance.getString(flag: .myFlag, defaultValue: "flag_value")

Получение ID устройства для проверки эксперимента

Для получения ID устройства используйте метод VarioqubInstance.varioqubId:

let varioqubId = libInstance.varioqubId

Подробнее о создании и проверке эксперимента читайте в разделе Создание эксперимента.