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

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

Чтобы инициализировать библиотеку с расширенной стартовой конфигурацией:

  1. Инициализируйте объект класса YMMYandexMetricaConfigurationYMMYandexMetricaConfiguration.
  2. Задайте настройки конфигурации с помощью методов класса YMMYandexMetricaConfiguration. Например, включите логирование или установите тайм-аут сессии.
  3. Передайте объект YMMYandexMetricaConfiguration в метод +activateWithConfiguration:activateWithConfiguration(_:) класса YMMYandexMetricaYMMYandexMetrica.

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

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // Creating an extended library configuration.
    YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
    // Setting up the configuration. For example, to enable logging.
    configuration.logs = YES;
    ...
    // Initializing the AppMetrica SDK.
    [YMMYandexMetrica activateWithConfiguration:configuration];
}
Скопировано
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
}
Скопировано

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

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

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

Шаг 1. (Опционально) Инициализируйте репортер с расширенной конфигурацией

Внимание. Инициализацию репортера с расширенной конфигурацией необходимо проводить до первого обращения к репортеру. Иначе репортер будет инициализирован без конфигурации.

Чтобы инициализировать репортер с расширенной конфигурацией:

  1. Инициализируйте объект класса YMMReporterConfigurationYMMReporterConfiguration.
  2. Задайте настройки конфигурации с помощью методов класса YMMReporterConfiguration. Например, включите логирование или установите тайм-аут сессии.
  3. Передайте объект YMMReporterConfiguration в метод +activateReporterWithConfiguration:activateReporterWithConfiguration(_:) класса YMMYandexMetricaYMMYandexMetrica.

Конфигурация применяется для репортера с указанным API key. Для каждого дополнительного API key можно настроить свою конфигурацию.

// Creating an extended library configuration.
// To create it, pass an API_key that is different from the app's API_key.
YMMReporterConfiguration *reporterConfiguration = [[YMMReporterConfiguration alloc] initWithApiKey:API_key];
// Setting up the configuration. For example, to enable logging.
reporterConfiguration.logs = YES;
...
// Initializing a reporter.
[YMMYandexMetrica activateReporterWithConfiguration:[reporterConfiguration copy]];
Скопировано
// Creating an extended library configuration.
// To create it, pass an API_key that is different from the app's API_key.
let reporterConfiguration = YMMReporterConfiguration.init(apiKey: "API key")
// Setting up the configuration. For example, to enable logging.
reporterConfiguration?.logs = true
...
// Initializing a reporter.
YMMYandexMetrica.activateReporterWithConfiguration(reporterConfiguration!)
Скопировано

Шаг 2. Настройте отправку данных с помощью репортера

Чтобы отправить данные на другой API key:

  1. С помощью метода -reporterForApiKey:reporterForApiKey(_:) класса YMMYandexMetricaYMMYandexMetrica получите объект, который реализует протокол YMMYandexMetricaReportingYMMYandexMetricaReporting.

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

  2. Используйте методы протокола YMMYandexMetricaReporting для отправки ошибок, событий и Revenue.
  3. Чтобы сессии отслеживались правильно, настройте отправку событий о начале и приостановке сессии для каждого репортера.
id<YMMYandexMetricaReporting> reporter = [YMMYandexMetrica reporterForApiKey:API_key];
[reporter resumeSession];
...
[reporter reportEvent:@"Updates installed" onFailure:^(NSError *error) {
    NSLog(@"REPORT ERROR: %@", [error localizedDescription]);
}];
...
[reporter pauseSession];
Скопировано
let reporter = YMMYandexMetrica.reporterForApiKey("API_key")
reporter.resumeSession()
...
reporter.reportEvent("Updates installed") { (error) in
    print("REPORT ERROR: %@", error?.localizedDescription)
}
...
reporter.pauseSession()
Скопировано

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

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

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

// Creating an extended library configuration.
YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
// Disabling sending the information on crashes of the application.
configuration.crashReporting = NO;
// Initializing the AppMetrica SDK.
[YMMYandexMetrica activateWithConfiguration:configuration];
Скопировано
// Creating an extended library configuration.
let configuration = YMMYandexMetricaConfiguration.init(apiKey: "API_key")
// Disabling sending the information on crashes of the application.
configuration?.crashReporting = false
// Initializing the AppMetrica SDK.
YMMYandexMetrica.activate(with: configuration!)
Скопировано

Определение местоположения

Точность определения местоположения зависит от конфигурации, с которой инициализируется библиотека:
С включенной опцией locationTracking

Местоположение определяется с точностью до города.

Приложение запрашивает доступ к GPS. Расход заряда аккумулятора может увеличиться.

С отключенной опцией locationTracking
Местоположение определяется по IP-адресу с точностью до страны.

Приложение не запрашивает доступ к GPS. Расход заряда аккумулятора не увеличивается.

Примечание. Если у вас включена маскировка IP-адреса, местоположение определяется так же с точностью до страны по немаскированной части IP-адреса.

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

Чтобы инициализировать библиотеку с отключенным locationTracking, установите значение NO для свойства locationTrackinglocationTracking конфигурации YMMYandexMetricaConfigurationYMMYandexMetricaConfiguration.

// Creating an extended library configuration.
YMMYandexMetricaConfiguration *configuration = [[YMMYandexMetricaConfiguration alloc] initWithApiKey:API_key];
// Disabling sending information about the device location.
configuration.locationTracking = NO;
// Initializing the AppMetrica SDK.
[YMMYandexMetrica activateWithConfiguration:configuration];
Скопировано
// 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!)
Скопировано

Чтобы отключить locationTracking после инициализации библиотеки, используйте метод +setLocationTracking:setLocationTracking(_:) класса YMMYandexMetricaYMMYandexMetrica:

[YMMYandexMetrica setTrackLocationEnabled:NO];
Скопировано
YMMYandexMetrica.setLocationTracking(false)
Скопировано

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

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

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

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

- (void)locationManager:(CLLocationManager *)manager
    didUpdateToLocation:(CLLocation *)newLocation
           fromLocation:(CLLocation *)oldLocation
{
    [YMMYandexMetrica setLocation:newLocation];
}
Скопировано
func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
    YMMYandexMetrica.setLocation(locations.last)
}
Скопировано

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

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

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

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

Чтобы отправить собственное событие с вложенными параметрами, передайте в метод +reportEvent:params:onFailure:reportEvent(_:params:onFailure:) класса YMMYandexMetricaYMMYandexMetrica следующие параметры:
  • message — короткое название или описание события;
  • params — вложенные параметры в виде пар «ключ-значение»;

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

  • onFailure — блок, в который передается ошибка. Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.
NSDictionary *params = @{@"key1": @"value1", @"key2": @"value2"};
[YMMYandexMetrica reportEvent:@"EVENT"
                   parameters:params
                    onFailure:^(NSError *error) {
                        NSLog(@"error: %@", [error localizedDescription]);
                    }];
Скопировано
let params : [String : Any] = ["key1": "value1", "key2": "value2"]
YMMYandexMetrica.reportEvent("EVENT", parameters: params, onFailure: { (error) in
    print("DID FAIL REPORT EVENT: %@", message)
    print("REPORT ERROR: %@", error?.localizedDescription)
})
Скопировано

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

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

Чтобы отправить собственное сообщение об ошибке, передайте в метод +reportError:exception:onFailure:reportError(_:exception:onFailure:) класса YMMYandexMetricaYMMYandexMetrica следующие параметры:

  • message — короткое название или описание события;
  • exception — объект типа NSException, который требуется передать на сервер. Может принимать значение nil;
  • onFailure — блок, в который передается ошибка. Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.
@try {
    [self doWork];
}
@catch (NSException *exception) {
    [YMMYandexMetrica reportError:@"doWork failed"
                        exception:exception
                        onFailure:nil];
}
Скопировано
do {
    try self.doWork();
} catch let exception as NSException {
    YMMYandexMetrica.reportError("doWork failed", exception: exception, onFailure: nil)
}
Скопировано

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

Чтобы отправить атрибуты профиля, передайте в метод +reportUserProfile:onFailure:reportUserProfile(_:onFailure:) класса YMMYandexMetricaYMMYandexMetrica следующие параметры:

  • userProfile — объект YMMUserProfileYMMUserProfile, который содержит массив обновлений атрибутов. Атрибуты профиля создаются с помощью методов класса YMMProfileAttributeYMMProfileAttribute.
  • onFailure — блок, в который передается ошибка. Если вы не хотите отслеживать ошибку, то передайте в качестве блока значение nil.
YMMMutableUserProfile *profile = [[YMMMutableUserProfile alloc] init];
// Updating a single user profile attribute.
id<YMMCustomCounterAttribute> timeLeftAttribute = [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:YMMGenderTypeMale],
    [[YMMProfileAttribute birthDate] withAge:24],
    [[YMMProfileAttribute notificationsEnabled] withValue:NO],
    // 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:YES]
]];
// ProfieID is set using the method of the YMMYandexMetrica class.
[YMMYandexMetrica setUserProfileID:@"id"];

// Sending profile attributes.
[YMMYandexMetrica reportUserProfile:[profile copy] onFailure:^(NSError *error) {
    NSLog(@"Error: %@", error);
}];
Скопировано
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:setUserProfileID(_:) класса YMMYandexMetricaYMMYandexMetrica.

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

[YMMYandexMetrica setUserProfileID:@"id"];
Скопировано
YMMYandexMetrica.setUserProfileID("id")
Скопировано

Отправка Revenue

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

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

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

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

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

Чтобы покупки на iOS валидировались, в собственной реализации завершения транзакции настройте отправку поля transactionIDtransactionID и receiptDatareceiptData:
  1. Инициализируйте объект YMMMutableRevenueInfoYMMMutableRevenueInfo.
  2. Для валидации покупки укажите transactionIDtransactionID и receiptDatareceiptData. Их необходимо получить до вызова [[SKPaymentQueue defaultQueue] finishTransaction:transaction].
  3. Отправьте объект YMMMutableRevenueInfo на тестовый API key с помощью репортера YMMYandexMetricaReportingYMMYandexMetricaReporting. Подробнее о работе репортеров в разделе Отправка статистики на дополнительный API key.
- (void)completeTransaction:(SKPaymentTransaction *)transaction
{
    ...
    NSDecimalNumber *price = [NSDecimalNumber decimalNumberWithString:@"2100.5"];
    // Initializing the Revenue instance.
    YMMMutableRevenueInfo *revenueInfo = [[YMMMutableRevenueInfo alloc] initWithPriceDecimal:price currency:@"BYN"];
    revenueInfo.productID = @"TV soundbar";
    revenueInfo.quantity = 2;
    revenueInfo.payload = @{ @"source": @"AppStore" };
    // Set purchase information for validation.
    revenueInfo.transactionID = transaction.transactionIdentifier;
    revenueInfo.receiptData = [NSData dataWithContentsOfURL:[[NSBundle mainBundle] appStoreReceiptURL]];
    // Sending the Revenue instance using reporter.
    id<YMMYandexMetricaReporting> reporter = [YMMYandexMetrica reporterForApiKey:@"Testing API key"];
    [reporter reportRevenue:[revenueInfo copy] onFailure:^(NSError *error) {
        NSLog(@"Revenue error: %@", error);
    }];
    // Remove the transaction from the payment queue.
    [[SKPaymentQueue defaultQueue] finishTransaction: transaction];
}