Интеграция SDK

Для работы Varioqub SDK подключите и инициализируйте библиотеку AppMetrica для iOS. Подробнее о том, как это можно сделать, читайте в документации AppMetrica SDK.

Требования к приложению:

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

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

  1. При старте новой сессии вызывайте метод activateConfigAndWait(), чтобы получить значения сохраненных флагов.
  2. Запускайте fetchConfig в фоне, чтобы выгрузить новые значения флагов с сервера и активировать их при старте следующей сессии.
  3. Не рекомендуется вызывать метод 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. Инициализируйте библиотеку

Для инициализации библиотеки используется метод

initialize(clientId: String, config: VarioqubConfig = .default, idProvider: VarioqubIdProvider?, reporter: VarioqubReporter?)

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

  • 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 SwiftUI
    import YandexMobileMetrica
    import YandexMobileMetricaCrashes
    import Varioqub
    import MetricaAdapter
    
    let adapter = AppmetricaAdapter()
    
    @main
    struct ExampleApp: App {
        init() {
        // Конфигурируем настройки Varioqub SDK
    
        var vqCfg = VarioqubConfig.default
    
        // Добавляем клиентские параметры
    
        vqCfg.clientFeatures["feature1"] = "value1"
    
        // Инициализируем Varioqub SDK
    
        VarioqubFacade.shared.initialize(clientId: "appmetrica.1234567", config: vqCfg, idProvider: adapter, reporter: adapter)
        }
    }
    

Конфигурация 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")
VarioqubFacade.shared.loadXml(at: path, callback: nil)

Примечание

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

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

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

Примечание

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

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

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

Совет

Основной сценарий использования:

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

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

VarioqubFacade.shared.activateConfigAndWait()

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

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

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

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

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

  • VarioqubFacade.shared.getString(flag, defaultValue).

Пример кода:

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

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

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

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

let varioqubId = VarioqubFacade.shared.varioqubId

Примечание

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

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