Примеры использования методов

Инициализация библиотеки с расширенной конфигурацией

Чтобы инициализировать библиотеку с расширенной стартовой конфигурацией, передайте в метод
YMMYandexMetrica.activateWithConfiguration(_ configuration: YMMYandexMetricaConfiguration)
объект класса YMMYandexMetricaConfiguration с необходимыми настройками. С помощью расширенной конфигурации можно, например, включить/отключить логирование, установить тайм-аут сессии, передать параметры для отслеживания предустановленных приложений и т. д.

Настройки расширенной конфигурации применяются с момента инициализации библиотеки.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : AnyObject]? = nil) -> Bool {
    // Creating an extended library configuration.
    let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API key")
    // Setting up the configuration. For example, to enable logging.
    configuration?.logs = true
    ...
    // Initializing the AppMetrica SDK.
    YMMYandexMetrica.activate(with: configuration!) 
    return true
}

Чтобы настроить библиотеку в процессе работы приложения, используйте методы класса YMMYandexMetrica.

Отправка статистики на дополнительный API key

Отправка данных на дополнительный API key позволяет собирать для каждого API key свою статистику. Это можно использовать для управления доступом к информации. Например, чтобы предоставить доступ к статистике для аналитиков, можно продублировать отправку маркетинговых данных на дополнительный API key и предоставить им доступ к этой статистике. Так у них будет доступ только к той информации, которая им необходима.

Для отправки данных на дополнительный API key необходимо использовать репортеры. С помощью них можно отправлять события, сообщения об ошибках, профили и информацию о покупках в приложении. Репортеры могут работать без инициализации AppMetrica SDK.

Чтобы инициализировать репортер с расширенной конфигурацией, передайте в метод
YMMYandexMetrica.activateReporterWithConfiguration(_ configuration: YMMReporterConfiguration)
объект класса YMMReporterConfiguration с необходимыми настройками. Конфигурация применяется для репортера с указанным API key. Для каждого дополнительного API key можно настроить свою конфигурацию.
Внимание. Инициализацию репортера с расширенной конфигурацией необходимо проводить до первого обращения к репортеру. Иначе репортер будет инициализирован без конфигурации.
// Creating an extended library configuration.
let reporterConfiguration = YMMReporterConfiguration.init(apiKey: "API key")
// Setting up the configuration. For example, to enable logging.
reporterConfiguration?.logs = true
...
// Initializing the AppMetrica SDK.
YMMYandexMetrica.activateReporterWithConfiguration(reporterConfiguration!)
Для отправки данных с помощью репортера, необходимо получить объект, который реализует протокол YMMReporterConfiguration с помощью метода
YMMYandexMetrica.reporterForApiKey(_ apiKey: String) -> YMMYandexMetricaReporting?

Если репортер не был инициализирован с расширенной конфигурацией, то вызов данного метода произведет инициализацию репортера для указанного API key.

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

Пример отправки отчетов:

let reporter = YMMYandexMetrica.reporterForApiKey("API_key")
reporter.reportEvent("Updates installed") { (error) in
    print("REPORT ERROR: %@", error?.localizedDescription)
}

Для корректного отслеживания сессий взаимодействия пользователя с приложением необходимо вручную настроить отправку событий о начале и приостановке сессии для каждого репортера:

let reporter = YMMYandexMetrica.reporterForApiKey("API_key")
reporter.resumeSession()
...
reporter.reportEvent("Updates installed") { (error) in
    print("REPORT ERROR: %@", error?.localizedDescription)
}
...
reporter.pauseSession()
Примечание. При перезагрузке приложения сессия будет прервана.

Отслеживание аварийных остановок приложения

Отчеты об аварийных остановках приложения отправляются по умолчанию.

Чтобы отключить автоматическое отслеживание, инициализируйте библиотеку с конфигурацией, в которой отправка информации об аварийных остановках приложения отключена. Для этого установите значение false для свойства crashReporting конфигурации YMMYandexMetricaConfiguration.

// Creating an extended library configuration.
let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API key")
// Disabling sending the information on emergency stops of the application.
configuration?.crashReporting = false
// Initializing the AppMetrica SDK.
YMMYandexMetrica.activate(with: configuration!)

Отправка местоположения устройства библиотекой

Местоположение устройства определяется библиотекой по умолчанию.
Внимание. AppMetrica SDK не запрашивает разрешение на получение данных о местоположении. Это необходимо сделать самостоятельно с помощью методов класса CLLocationManager в подходящее время.

AppMetrica позволяет управлять отправкой отчетов о местоположении устройства. Запрет отправки отключает все способы определения локации в AppMetrica. Пользователи с отключенной отправкой группируются и отображаются в отчетах по географии со значением «Не определено».

Отчеты о местоположении устройства отправляются по умолчанию.

Чтобы отключить отправку, инициализируйте библиотеку с конфигурацией, в которой отправка информации о местоположении устройства отключена. Для этого установите значение false для свойства locationTracking конфигурации YMMYandexMetricaConfiguration.
// Creating an extended library configuration.
let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API key")
// Disabling sending  information about the location of the device.
configuration?.locationTracking = false
// Initializing the AppMetrica SDK.
YMMYandexMetrica.activate(with: configuration!)

Чтобы отключить отправку в процессе работы приложения, используйте метод setLocationTracking(_ enabled: Bool) класса YMMYandexMetrica.

YMMYandexMetrica.setTrackLocationEnabled(false)

Установка местоположения устройства вручную

Перед отправкой собственной информации о местоположении устройства убедитесь, что отправка отчетов не была отключена.

По умолчанию местоположение устройства определяется библиотекой. Чтобы отправить собственную информацию о местоположении устройства, передайте объект класса CLLocation в метод YMMYandexMetrica.setLocation(_ location: CLLocation?).

func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
    YMMYandexMetrica.setLocation(locations.last)
}

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

Отправка собственного события

Чтобы отправить собственное событие без вложенных параметров, передайте в метод
YMMYandexMetrica.reportEvent(_ message: String, onFailure: ((NSError) -> Void)?)
следующие параметры:
  • message — короткое название или описание события;
  • onFailure — блок, в который передается ошибка. Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.
YMMYandexMetrica.reportEvent("Updates installed", onFailure: { (error) in
    print("DID FAIL REPORT EVENT: %@", message)
    print("REPORT ERROR: %@", error?.localizedDescription)
}

Отправка собственного события с вложенными параметрами

Чтобы отправить собственное событие с вложенными параметрами, передайте в метод
YMMYandexMetrica.reportEvent(_ message: String, parameters params: [NSObject : AnyObject]?, onFailure: ((NSError) -> Void)?)
следующие параметры:
  • message — короткое название или описание события;
  • params — вложенные параметры в виде пар «ключ-значение»;
  • onFailure — блок, в который передается ошибка. Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.
let params : [String : Any] = ["key1": "value1", "key2": "value2", "key3":["key4":"value4"]]
YMMYandexMetrica.reportEvent("EVENT", parameters: params, onFailure: { (error) in
    print("DID FAIL REPORT EVENT: %@", message)
    print("REPORT ERROR: %@", error?.localizedDescription)
})

Веб-интерфейс AppMetrica отображает до пяти уровней вложенности события. Если событие содержит шесть уровней и более, в отчете отобразятся пять верхних. С помощью API отчетов можно выгрузить до десяти уровней.

Подробнее о событиях в разделе Отправка собственных событий.

Отправка сообщения об ошибке

Чтобы отправить собственное сообщение об ошибке, передайте в метод

YMMYandexMetrica.reportError(_ message: String, exception: NSException?, onFailure: ((NSError) -> Void)?)
следующие параметры:
  • message — короткое название или описание события;
  • exception — объект типа NSException, который требуется передать на сервер. Может принимать значение nil;
  • onFailure — блок, в который передается ошибка. Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.
do {
    try self.doWork();
} catch let exception as NSException {
    YMMYandexMetrica.reportError("doWork failed", exception: exception, onFailure: nil)
}

Отправка атрибутов профиля

Чтобы отправить атрибуты профиля передайте в метод
YadnexMetrica.reportUserProfile(_ userProfile: YMMUserProfile, onFailure: ((NSError) -> Void)?)
следующие параметры:
  • userProfile — объект, который содержит массив обновлений атрибутов. Атрибуты профиля создаются с помощью методов класса YMMProfileAttribute.
  • onFailure — блок, в который передается ошибка. Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.
let profile = YMMMutableUserProfile()
// Updating a single user profile attribute.
let timeLeftAttribute: YMMCustomCounterAttribute = YMMProfileAttribute.customCounter("time_left")
profile.apply(timeLeftAttribute.withDelta(-4.42))
// Updating multiple attributes.
profile.applyFromArray([
    // Updating predefined attributes.
    YMMProfileAttribute.name().withValue("John"),
    YMMProfileAttribute.gender().withValue(YMMGenderType.Male),
    YMMProfileAttribute.birthDate().withAge(24),
    YMMProfileAttribute.notificationsEnabled().withValue(false),
    // Updating custom attributes.
    YMMProfileAttribute.customString("born_in").withValueIfUndefined("Moscow"),
    YMMProfileAttribute.customString("address").withValueReset(),
    YMMProfileAttribute.customNumber("age").withValue(24),
    YMMProfileAttribute.customCounter("logins_count").withDelta(1),
    YMMProfileAttribute.customBool("has_premium").withValue(true)
])
// ProfieID is set using the method of the YMMYandexMetrica class.
YMMYandexMetrica.setUserProfileID("id")

// Sending profile attributes.
YMMYandexMetrica.reportUserProfile(profile, onFailure: { (error) in
    print("REPORT ERROR: %@", error.localizedDescription)
})

Отправка ProfileId

Чтобы отправить ProfileId, используйте метод setUserProfileID(_ userProfileID: String?) класса YadnexMetrica.

Если отправка ProfileId не настроена, то в веб-интерфейсе будет отображаться appmetrica_device_id.
YandexMetrica.setUserProfileID("id")

Отправка Revenue

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

Примечание. Чтобы покупки валидировались, включите валидацию в настройках. Подробнее в разделе Отправка информации о покупке на iOS.

Шаг 1. Протестируйте отправку Revenue

В AppMetrica нет возможности сегментировать Revenue на «тестовые» и «не тестовые». Если для отладки покупок вы используете основной API key, то тестовые покупки будут попадать в общую статистику. Поэтому, чтобы отладить работу отправки Revenue, используйте отправку статистики на дополнительный API key с помощью репортера.

Ниже описаны этапы отправки Revenue на дополнительный API key:

Чтобы покупки на iOS валидировались, в собственной реализации завершения транзакции настройте отправку поля transactionID и receiptData:

  1. Инициализируйте объект YMMMutableRevenueInfo.
  2. Для валидации покупки укажите transactionID и receiptData. Их необходимо получить до вызова SKPaymentQueue.default().finishTransaction(transaction).
  3. Отправьте объект YMMMutableRevenueInfo на тестовый API key с помощью репортера YMMYandexMetricaReporting. Подробнее о работе репортеров в разделе Примеры использования.
func completeTransaction(_ transaction: SKPaymentTransaction) {
    ...
    let price = NSDecimalNumber(string: "2100.5")
    // Initializing the Revenue instance.
    let revenueInfo = YMMMutableRevenueInfo.init(priceDecimal: price, currency: "BYN")
    revenueInfo.productID = "TV soundbar"
    revenueInfo.quantity = 2
    revenueInfo.payload = ["source": "AppStore"]
    // Set purchase information for validation.
    if let url = Bundle.main.appStoreReceiptURL, let data = try? Data(contentsOf: url), let transactionID = transaction.transactionIdentifier {
        revenueInfo.transactionID = transactionID
        revenueInfo.receiptData = data
    }
    // Sending the Revenue instance using reporter.
    let reporter = YMMYandexMetrica.reporterForApiKey("API_key")
    reporter.reportRevenue(revenueInfo, onFailure: { (error) in
        print("REPORT ERROR: \(error.localizedDescription)")
    })
    // Remove the transaction from the payment queue.
    SKPaymentQueue.default().finishTransaction(transaction)
}

Шаг 2. Настройте отправку Revenue на основной API key

После успешного тестирования настройте отправку Revenue на основной API key.

Чтобы отправить объект YMMMutableRevenueInfo на основной API key, используйте метод +reportRevenue:onFailure: класса YMMYandexMetrica.

...
// Sending the Revenue instance.
YMMYandexMetrica.reportRevenue(revenueInfo, onFailure: { (error) in
    print("REPORT ERROR: \(error.localizedDescription)")
})

Установка длительности тайм-аута сессии

По умолчанию длительность тайм-аута сессии равна 10 секундам. Это минимально допустимое значение свойства sessionTimeout.

Чтобы изменить длительность тайм-аута, передайте значение в секундах в свойство sessionTimeout конфигурации YMMYandexMetricaConfiguration.

// Creating an extended library configuration.
let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API key")
// Setting the session timeout.
configuration?.sessionTimeout = 15
// Initializing the AppMetrica SDK.
YMMYandexMetrica.activate(with: configuration!)

Установка версии приложения

По умолчанию версия приложения задается в файле Info.plist (CFBundleShortVersionString).

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

// Creating an extended library configuration.
let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API key")
// Setting the app version.
configuration?.appVersion = "1.13.2"
// Initializing the AppMetrica SDK.
YMMYandexMetrica.activate(with: configuration!)

где 1.13.2 — версия приложения.

Отслеживание открытий приложения с помощью deeplink

Отслеживание открытий необходимо для корректного трекинга ремаркетинг-кампаний.

Примечание. Для работы с Universal Links добавьте их поддержку в вашем приложении.

Отслеживать открытия приложения с помощью deeplink или Universal Links можно с помощью метода handleOpenURL(_:)

Чтобы отслеживать открытия приложения с помощью deeplink, необходимо в UIApplicationDelegate добавить следующие изменения:

func application(_ application: UIApplication, handleOpenURL url: URL) -> Bool {
    return YMMYandexMetrica.handleOpen(url)
}

func application(_ application: UIApplication, openURL url: URL, sourceApplication: String?, annotation: AnyObject) -> Bool {
    return YMMYandexMetrica.handleOpen(url)
}

// Delegate for tracking Universal links.
func application(_ application: UIApplication, continueUserActivity userActivity: NSUserActivity, restorationHandler: ([AnyObject]?) -> Void) -> Bool {
    if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
        if let url = userActivity.webpageURL {
            YMMYandexMetrica.handleOpen(url)
        }
    }
    return true
}

Учет новых пользователей

По умолчанию в момент первого запуска приложения все пользователи определяются как новые. Если AppMetrica SDK подключается к приложению, у которого уже есть активные пользователи, то для корректного отслеживания статистики можно настроить учет новых и старых пользователей. Для этого необходимо инициализировать AppMetrica SDK, используя расширенную конфигурацию YMMYandexMetricaConfiguration:

var isFirstLaunch = false
// Creating an extended library configuration.
let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API key")
// Implement the logic for detecting whether the app is starting for the first time.
// For example, you can check for files (settings, databases, and so on),
// which the app creates on its first launch.
if conditions {
    isFirstLaunch = true;
}
configuration?.handleFirstActivationAsUpdateEnabled = !isFirstLaunch
// Initializing the AppMetrica SDK.
YMMYandexMetrica.activate(with: configuration!)

Отключение и включение отправки статистики

Если для отправки статистических данных требуется согласие пользователя, необходимо инициализировать библиотеку с отключенной опцией отправки статистики. Для этого установите значение false для свойства statisticsSending конфигурации YMMYandexMetricaConfiguration:

// Creating an extended library configuration.
let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API key")
// Disabling sending statistics.
configuration?.statisticsSending = false
// Initializing the AppMetrica SDK.
YMMYandexMetrica.activate(with: configuration!)

После того как пользователь дал согласие на отправку статистики (например, в настройках приложения или в соглашении при первом открытии), необходимо включить отправку с помощью метода YMMYandexMetrica.setStatisticsSending:(Bool)enabled.

// Checking the status of the boolean variable. It shows the user confirmation.
if flag {
    // Enabling sending statistics.
    YMMYandexMetrica.setStatisticsSending(true);
}