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

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

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

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

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

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

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

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

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

Чтобы подключить библиотеку, добавьте в Podfile проекта зависимости:

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

При использовании этого метода убедитесь, что AppMetrica SDK подключяется явно, например,

pod 'AppMetricaAnalytics', '~> 5.10.0'

или неявно — через другие поды, например YandexMobileAds.

Чтобы подключить библиотеку, добавьте в Podfile проекта зависимости:

pod 'Varioqub', '~> 0.8'

Чтобы подключить библиотеку, добавьте в Podfile проекта зависимости:

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

Если при подключении возникает конфликт формата [!] The 'Pods-proj' target has frameworks with conflicting names: yandexmobilemetrica.xcframework, подключите библиотеку с помощью Cocoapods (без явной зависимости).

Для подключения библиотеки выполните следующее:

  1. Загрузите библиотеки YandexMobileMetrica, MetricaAdapter, Varioqub и VQSwiftProtobuf.

  2. Добавьте YandexMobileMetrica.framework, MetricaAdapter.framework, Varioqub.framework в проект.

  3. (Опционально) Для подключения обработки крэшей добавьте YandexMobileMetricaCrashes.framework.

Шаг 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.setCustomRepoter("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)

Примечание

Название файла defaults.xml и путь к файлу являются демонстрационными.

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

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

Примечание

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

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

Примечание

До первого успешного вызова fetchConfig метод Varioqub.getId() может возвращать пустой ответ.

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

Предыдущая