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

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

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

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

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Создание расширенной конфигурации библиотеки.
    YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
    // Настройка конфигурации. Например, включение логирования.
    configuration.logs = YES;
    ...
    // Инициализация AppMetrica SDK.
    [YMMYandexMetrica activateWithConfiguration:[configuration copy]];
}

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

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

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

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

Чтобы инициализировать репортер с расширенной конфигурацией, передайте в метод
[YMMYandexMetrica activateReporterWithConfiguration:(YMMReporterConfiguration *)configuration];
объект класса YMMReporterConfiguration с необходимыми настройками. Конфигурация применяется для репортера с указанным API key. Для каждого дополнительного API key можно настроить свою конфигурацию.
Внимание. Инициализацию репортера с расширенной конфигурацией необходимо проводить до первого обращения к репортеру. Иначе репортер будет инициализирован без конфигурации.
// Создание расширенной конфигурации библиотеки.
// Для создания необходимо передать API_key, отличный от API_key приложения.
YMMReporterConfiguration *reporterConfiguration = [[YMMReporterConfiguration alloc] initWithApiKey:API_key];
// Настройка конфигурации. Например, включение логирования.
reporterConfiguration.logs = YES;
...
// Инициализация репортера.
[YMMYandexMetrica activateReporterWithConfiguration:[reporterConfiguration copy]];
Для отправки данных с помощью репортера, необходимо получить объект, который реализует протокол YMMYandexMetricaReporting с помощью метода [YMMYandexMetrica reporterForApiKey:(NSString *)apiKey];

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

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

Пример отправки события:

YMMYandexMetricaReporting reporting = [YMMYandexMetrica reporterForApiKey:API_key];
[reporting reportEvent:@"Updates installed" onFailure:^(NSError *error) {
    NSLog(@"DID FAIL REPORT EVENT: %@", message);
    NSLog(@"REPORT ERROR: %@", [error localizedDescription]);
}];

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

YMMYandexMetricaReporting reporting = [YMMYandexMetrica reporterForApiKey:API_key];
[reporting resumeSession];
...
[reporting reportEvent:@"Updates installed" onFailure:^(NSError *error) {
    NSLog(@"DID FAIL REPORT EVENT: %@", message);
    NSLog(@"REPORT ERROR: %@", [error localizedDescription]);
}];
...
[reporting pauseSession];
Примечание. При перезагрузке приложения сессия будет прервана.

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

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

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

// Создание расширенной конфигурации библиотеки.
YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
// Отключение отправки информации об аварийных остановках приложения.
configuration.crashReporting = NO;
// Инициализация AppMetrica SDK.
[YMMYandexMetrica activateWithConfiguration:[configuration copy]];

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

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

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

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

Чтобы отключить отправку, инициализируйте библиотеку с конфигурацией, в которой отправка информации о местоположении устройства отключена. Для этого установите значение NO для свойства locationTracking конфигурации YMMYandexMetricaConfiguration.
// Создание расширенной конфигурации библиотеки.
YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
// Отключение отправки информации о местоположении устройства.
configuration.locationTracking = NO;
// Инициализация AppMetrica SDK.
[YMMYandexMetrica activateWithConfiguration:[configuration copy]];

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

[YMMYandexMetrica setTrackLocationEnabled:NO];

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

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

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

- (void)locationManager:(CLLocationManager *)manager
    didUpdateToLocation:(CLLocation *)newLocation
           fromLocation:(CLLocation *)oldLocation
{
   [YMMYandexMetrica setLocation:newLocation];
}

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

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

Чтобы отправить собственное событие без вложенных параметров, передайте в метод

[YMMYandexMetrica reportEvent:(NSString *)message
                    onFailure:(void (^)(NSError *error))onFailure];
следующие параметры:
  • message — короткое название или описание события;
  • onFailure — блок, в который передается ошибка.

Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.

[YMMYandexMetrica reportEvent:@"Updates installed" onFailure:^(NSError *error) {
    NSLog(@"DID FAIL REPORT EVENT: %@", message);
    NSLog(@"REPORT ERROR: %@", [error localizedDescription]);
}];

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

Чтобы отправить собственное событие с вложенными параметрами, передайте в метод
[YMMYandexMetrica reportEvent:(NSString *)message
                   parameters:(NSDictionary *)params
                    onFailure:(void (^)(NSError *error))onFailure];
следующие параметры:
  • message — короткое название или описание события;
  • params — вложенные параметры в виде пар «ключ-значение»;
  • onFailure — блок, в который передается ошибка.

Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.

NSDictionary *params = @{@"key1": @"value1", @"key2": @"value2"};
[YMMYandexMetrica reportEvent:@"EVENT"
                   parameters:params
                    onFailure:^(NSError *error) {
                        NSLog(@"error: %@", [error localizedDescription]);
                    }];

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

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

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

Чтобы отправить собственное сообщение об ошибке, передайте в метод
[YMMYandexMetrica reportError:(NSString *)message
                    exception:(NSException *)exception
                      failure:(NSError * __ autoreleasing *)onFailure];
следующие параметры:
  • message — короткое название или описание события;
  • exception — объект типа NSException, который требуется передать на сервер. Может принимать значение nil;
  • onFailure — блок, в который передается ошибка.

Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.

@try {
    [self doWork];
}
@catch (NSException *exception) {
    [YMMYandexMetrica reportError:@"doWork failed"
                        exception:exception
                        onFailure:nil];
}

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

Чтобы отправить атрибуты профиля передайте в метод

[YMMYandexMetrica reportUserProfile:(YMMUserProfile *)userProfile
                          onFailure:(void (^)(NSError *error))onFailure];

следующие параметры:

  • userProfile — объект, который содержит массив обновлений атрибутов. Атрибуты профиля создаются с помощью методов класса YMMProfileAttribute.
  • onFailure — блок, в который передается ошибка.

Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.

YMMMutableUserProfile *profile = [[YMMMutableUserProfile alloc] init];
// Обновление одного атрибута пользовательского профиля.
id<YMMCustomCounterAttribute> timeLeftAttribute = [YMMProfileAttribute customCounter:@"time_left"];
[profile apply:[timeLeftAttribute withDelta:-4.42]];
// Обновление нескольких атрибутов пользовательского профиля.
[profile applyFromArray:@[
    // Обновление предопределенных атрибутов.
    [[YMMProfileAttribute name] withValue:@"John"],
    [[YMMProfileAttribute gender] withValue:YMMGenderTypeMale],
    [[YMMProfileAttribute birthDate] withAge:24],
    [[YMMProfileAttribute notificationsEnabled] withValue:NO],
    // Обновление собственных атрибутов.
    [[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:YES]
]];
// ProfieID задается через метод класса YMMYandexMetrica.
[YMMYandexMetrica setUserProfileID:@"id"];

// Отправка атрибутов профиля.
[YMMYandexMetrica reportUserProfile:[profile copy] onFailure:^(NSError *error) {
    NSLog(@"Error: %@", error);
}];

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

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

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

// Создание расширенной конфигурации библиотеки.
YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
// Установка длительности тайм-аута сессии.
configuration.sessionTimeout = 15;
// Инициализация AppMetrica SDK.
[YMMYandexMetrica activateWithConfiguration:[configuration copy]];

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

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

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

// Создание расширенной конфигурации библиотеки.
YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
// Установка версии приложения.
configuration.appVersion = @"1.13.2";
// Инициализация AppMetrica SDK.
[YMMYandexMetrica activateWithConfiguration:[configuration copy]];

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

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

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

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

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

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

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
{
    return [YMMYandexMetrica handleOpenURL:url];
}
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    return [YMMYandexMetrica handleOpenURL:url];
}

// Делегат для трекинга Universal links.
- (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
    restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler
{
    if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) {
        [YMMYandexMetrica handleOpenURL:userActivity.webpageURL];
    }
    return YES;
}

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

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

BOOL isFirstLaunch = NO;
// Создание расширенной конфигурации библиотеки.
YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
// Реализуйте логику определения того, является ли запуск приложения первым.
// Например, можно проверить наличие файлов (настроек, баз данных и др.),
// которые приложение создает в свой первый запуск.
if (conditions) {
    isFirstLaunch = YES;
}
configuration.handleFirstActivationAsUpdateEnabled = !isFirstLaunch;
// Инициализация AppMetrica SDK.
[YMMYandexMetrica activateWithConfiguration:[configuration copy]];

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

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

// Создание расширенной конфигурации библиотеки.
YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
// Отключение отправки статистики.
configuration.statisticsSending = NO;
// Инициализация AppMetrica SDK.
[YMMYandexMetrica activateWithConfiguration:[configuration copy]];

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

// Проверка переменной, которая отвечает за согласие пользователя.
if (flag) {
    // Включение отправки статистики.
    [YMMYandexMetrica setStatisticsSending:YES];
}