Интеграция SDK
- Общие рекомендации при интеграции
- Шаг 1. Подключите библиотеку в проект
- Шаг 2. Инициализируйте библиотеку
- Шаг 3. Задайте конфигурацию по умолчанию с помощью XML-файла
- Шаг 4. Запустите обновление конфигурации флагов в фоне
- Шаг 5. Активируйте конфигурацию
- Получение флагов из интерфейса
- Получение ID устройства для проверки эксперимента
Для работы Varioqub SDK подключите и инициализируйте библиотеку AppMetrica для iOS. Подробнее о том, как это можно сделать, читайте в документации AppMetrica SDK.
Требования к приложению:
- iOS, версия 12 и выше.
- Xcode 14.1 и выше.
Общие рекомендации при интеграции
- При старте новой сессии вызывайте метод
activateConfigAndWait()
, чтобы получить значения сохраненных флагов. - Запускайте
fetchConfig
в фоне, чтобы выгрузить новые значения флагов с сервера и активировать их при старте следующей сессии. - Не рекомендуется вызывать метод
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 (без явной зависимости).
Для подключения библиотеки выполните следующее:
-
Загрузите библиотеки YandexMobileMetrica, MetricaAdapter, Varioqub и VQSwiftProtobuf.
-
Добавьте
YandexMobileMetrica.framework
,MetricaAdapter.framework
,Varioqub.framework
в проект. -
(Опционально) Для подключения обработки крэшей добавьте
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-файла
Вы можете установить конфигурацию по умолчанию, чтобы ваше приложение использовало необходимые значения параметров до того, как оно подключится к серверу с удаленной конфигурацией.
-
Скачайте XML-файл конфигурации со страницы Конфиг флагов и сохраните его в своем Xcode проекте.
-
Передайте загруженный 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()
каждый раз, когда необходимо активировать полученную/загруженную конфигурацию (например, при старте новой сессии).
Получение флагов из интерфейса
Значения флагов вычисляются и предоставляются в следующем порядке:
- Флаг есть в эксперименте.
- Флаг есть в загруженной конфигурации.
- Флаг есть в конфигурации по умолчанию.
Методы для получения флагов:
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()
может возвращать пустой ответ.
Подробнее о создании и проверке эксперимента читайте в разделе Создание эксперимента.