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

  1. Инициализация библиотеки с расширенной конфигурацией
  2. Отправка статистики на дополнительный API key
  3. Отслеживание аварийных остановок приложения
  4. Отслеживание аварийных остановок приложения вручную
  5. Отслеживание нативных аварийных остановок приложения
  6. Отслеживание нативных аварийных остановок приложения вручную
  7. Отправка местоположения устройства библиотекой
  8. Установка местоположения вручную
  9. Отправка собственного события
  10. Отправка собственного события с вложенными параметрами
  11. Отправка собственного сообщения об ошибке
  12. Отправка атрибутов профиля
  13. Отправка ProfileId
  14. Установка длительности тайм-аута сессии
  15. Установка версии приложения
  16. Определение уровня API библиотеки
  17. Определение версии библиотеки
  18. Отслеживание источников установки
  19. Использование нескольких систем трекинга
  20. Отслеживание открытий приложения с помощью deeplink
  21. Запрос параметров отложенного deeplink
  22. Учет новых пользователей
  23. Отключение и включение отправки статистики

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

Чтобы инициализировать библиотеку с расширенной стартовой конфигурацией, создайте объект класса YandexMetricaConfig с необходимыми настройками и активируйте библиотеку с помощью метода YandexMetrica.activate(Context context, YandexMetricaConfig config). С помощью расширенной конфигурации можно, например, включить/отключить логирование, установить тайм-аут сессии, передать параметры для отслеживания предустановленных приложений и т. д.

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

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Создание расширенной конфигурации библиотеки.
        YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
                // Настройка конфигурации. Например, включение логирования.
                .withLogs()
                ...
                .build();
        // Инициализация AppMetrica SDK.
        YandexMetrica.activate(getApplicationContext(), config);
        // Автоматическое отслеживание активности пользователей.
        YandexMetrica.enableActivityAutoTracking(this);
    }
}

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

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

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

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

Чтобы инициализировать репортер с расширенной конфигурацией, создайте объект класса ReporterConfig с необходимыми настройками и активируйте репортер с помощью метода YandexMetrica.activateReporter(Context context, ReporterConfig config). Конфигурация применяется для репортера с указанным API key. Для каждого дополнительного API key можно настроить свою конфигурацию.
Внимание. Инициализацию репортера с расширенной конфигурацией необходимо проводить до первого обращения к репортеру. Иначе репортер будет инициализирован без конфигурации.
// Создание расширенной конфигурации репортера.
// Для создания необходимо передать API_key, отличный от API_key приложения.
ReporterConfig reporterConfig = ReporterConfig.newConfigBuilder(API_key)
        // Настройка конфигурации. Например, включение логирования.
        .withLogs()
        ...
        .build();
// Инициализация репортера.
YandexMetrica.activateReporter(getApplicationContext(), reporterConfig);

Для отправки данных с помощью репортера, необходимо получить объект, который реализует интерфейс IReporter с помощью метода YandexMetrica.getReporter(Context context, String apiKey) и использовать методы интерфейса для отправки отчетов. Если репортер не был инициализирован с расширенной конфигурацией, то вызов данного метода произведет инициализацию репортера для указанного API key.

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

YandexMetrica.getReporter(getApplicationContext(), API_key).reportEvent("Updates installed");
Для корректного отслеживания сессий взаимодействия пользователя с приложением необходимо настроить отправку событий о начале и приостановке сессии для каждого репортера. Для этого используйте методы resumeSession(Activity activity) и pauseSession(Activity activity) интерфейса IReporter в реализации onResume() и onPause() ваших Activity:
public class YourActivity extends Activity {
    ...
    @Override
    protected void onResume() {
        super.onResume();
        YandexMetrica.getReporter(getApplicationContext(), API_key).resumeSession();
    }

    @Override
    protected void onPause() {
        YandexMetrica.getReporter(getApplicationContext(), API_key).pauseSession();
        super.onPause();
    }
    ...
}

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

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

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

// Создание расширенной конфигурации библиотеки.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Отключение отправки информации об аварийных остановках приложения.
        .withCrashReporting(false)
        .build();
// Инициализация AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);

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

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

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

Чтобы отправлять информацию об аварийных остановках приложения вручную, используйте метод YandexMetrica.reportUnhandledException(Throwable exception):

final Thread.UncaughtExceptionHandler previousUncaughtExceptionHandler = Thread.getDefaultUncaughtExceptionHandler();
// Создание нового обработчика.
Thread.UncaughtExceptionHandler uncaughtExceptionHandler = new Thread.UncaughtExceptionHandler() {
    @Override
    public void uncaughtException(Thread thread, Throwable exception) {
        try {
            // Отправка сообщения об аварийной остановке на сервер AppMetrica.
            YandexMetrica.reportUnhandledException(exception);
        } finally {
            // Отправка сообщения об аварийной остановке предыдущему обработчику.
            if (previousUncaughtExceptionHandler != null) {
                previousUncaughtExceptionHandler.uncaughtException(thread, exception);
            }
        }
    }
};
// Установка обработчика по умолчанию.
Thread.setDefaultUncaughtExceptionHandler(uncaughtExceptionHandler);

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

Отчеты о нативных аварийных остановках приложения отправляются автоматически, если SO-файлы библиотеки добавлены в проект. По умолчанию SO-файлы отсутствуют. Чтобы добавить их, подключите библиотеку отслеживания нативных крешей.

Для подключения библиотеки добавьте следующую зависимость в файле build.gradle в блоке dependencies:

dependencies {
    ...
    implementation 'com.yandex.android:mobmetricalib-ndk-crashes:1.0.0'
}
Если вы не используете Gradle

Загрузите и добавьте библиотеку в проект.

Библиотека содержит в себе версии для всех платформ (arm, armv7, mips, x86). Используйте abi splits для исключения неиспользуемых библиотек.

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

// Создание расширенной конфигурации библиотеки.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Отключение отправки информации об нативных аварийных остановках приложения.
        .withNativeCrashReporting(false)
        .build();
// Инициализация AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);

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

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

Отчеты о нативных аварийных остановках приложения отправляются автоматически, если SO-файлы библиотеки добавлены в проект. Если файлы были добавлены, то необходимо отключить автоматическое отслеживание нативных аварийных остановок, чтобы избежать дублирования событий при ручной отправке.

Чтобы отправлять информацию о нативных аварийных остановках приложения вручную, используйте метод YandexMetrica.reportNativeCrash(String nativeCrash):

String nativeCrashContent =
"...\n" + 
"400ae000-400b7000 r-xp 00000000 103:0c 835       /system/lib/libcutils.so\n" + 
"400b7000-400b8000 r--p 00008000 103:0c 835       /system/lib/libcutils.so\n" +
"400b8000-400b9000 rw-p 00009000 103:0c 835       /system/lib/libcutils.so\n" +
"400b9000-400bc000 r-xp 00000000 103:0c 1454      /system/lib/liblog.so\n" +
"...";
// Отправка сообщения о нативной аварийной остановке приложения.
YandexMetrica.reportNativeCrash(nativeCrashContent);

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

Местоположение устройства определяется библиотекой по умолчанию. Для более точного определения местоположения добавьте в файл AndroidManifest.xml одно из следующих разрешений:

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

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

Чтобы отключить отправку, инициализируйте библиотеку с конфигурацией, в которой отправка информации о местоположении устройства отключена. Для этого передайте значение false в метод withLocationTracking(boolean enabled) при создании расширенной конфигурации библиотеки.
// Создание расширенной конфигурации библиотеки.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Отключение отправки информации о местоположении устройства.
        .withLocationTracking(false)
        .build();
// Инициализация AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);

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

YandexMetrica.setLocationTracking(false);

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

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

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

// Определение местоположения.
Location currentLocation = ...;
// Установка собственной информации о местоположении устройства.
YandexMetrica.setLocation(currentLocation);
Чтобы отправить собственную информацию о местоположении устройства с помощью стартовой конфигурации, передайте объект android.location.Location в метод withLocation(Location location) при создании расширенной конфигурации библиотеки.
// Определение местоположения.
Location currentLocation = ...;

// Создание расширенной конфигурации библиотеки.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Установка собственной информации о местоположении устройства.
        .withLocation(currentLocation)
        .build();
// Инициализация AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);

Чтобы возобновить определение местоположения библиотекой, передайте в метод YandexMetrica.setLocation(Location location) значение null:

YandexMetrica.setLocation(null);

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

Чтобы отправить собственное событие без вложенных параметров, передайте короткое название или описание события в метод YandexMetrica.reportEvent(String eventName):

YandexMetrica.reportEvent("Updates installed");

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

AppMetrica SDK позволяет отправлять собственные события с вложенными параметрами, которые могут быть заданы в формате JSON или в виде набора атрибутов (Map).

Чтобы передать вложенные параметры события в формате JSON, используйте метод YandexMetrica.reportEvent(String eventName, String jsonValue):

String eventParameters = "{\"name\":\"Alice\", \"age\":\"18\", \"favorite_games\":{\"strategies\":\"Age of Empires\"}}";

YandexMetrica.reportEvent("New person", eventParameters);

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

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

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

Чтобы отправить собственное сообщение об ошибке, передайте описание (message) и класс ошибки (error) в метод YandexMetrica.reportError(String message, Throwable error):

try {
    Integer.valueOf("00xffWr0ng");
} catch (Throwable error) {
    YandexMetrica.reportError("Error while parsing some integer number", error);
}

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

Чтобы отправить атрибуты профиля, передайте в объект UserProfile необходимые атрибуты и отправьте этот объект с помощью метода YandexMetrica.reportUserProfile(UserProfile profile). Атрибуты профиля создаются с помощью методов класса Attribute.

// Создание объекта UserProfile.
UserProfile userProfile = UserProfile.newBuilder()
        // Обновление предопределенных атрибутов.
        .apply(Attribute.name().withValue("John"))
        .apply(Attribute.gender().withValue(GenderAttribute.Gender.MALE))
        .apply(Attribute.birthDate().withAge(24))
        .apply(Attribute.notificationsEnabled().withValue(false))
        // Обновление собственных атрибутов.
        .apply(Attribute.customString("string_attribute").withValue("string"))
        .apply(Attribute.customNumber("number_attribute").withValue(55))
        .apply(Attribute.customCounter("counter_attribute").withDelta(1))
        .build();
// ProfileID задается через метод класса YandexMetrica.
YandexMetrica.setUserProfileID("id");

// Отправка объекта UserProfile.
YandexMetrica.reportUserProfile(userProfile);

Отправка ProfileId

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

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

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

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

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

// Создание расширенной конфигурации библиотеки.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Установка длительности тайм-аута сессии.
        .withSessionTimeout(15)
        .build();
// Инициализация AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);

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

По умолчанию версия приложения задается в файле AndroidManifest.xml.

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

// Создание расширенной конфигурации библиотеки.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Установка версии приложения.
        .withAppVersion("1.13.2")
        .build();
// Инициализация AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);

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

Определение уровня API библиотеки

Чтобы определить уровень API библиотеки из кода приложения, используйте метод YandexMetrica.getLibraryApiLevel().
int libraryApiLevel = YandexMetrica.getLibraryApiLevel();

Определение версии библиотеки

Чтобы определить версию библиотеки из кода приложения, используйте метод YandexMetrica.getLibraryVersion():

String libraryVersion = YandexMetrica.getLibraryVersion();

Отслеживание источников установки

AppMetrica SDK использует INSTALL_REFERRER Google Play для отслеживания источников установок приложения. Для повышения качества отслеживания рекомендуется подключить библиотеку Play Install Referrer.

Для подключения библиотеки добавьте следующую зависимость в файле build.gradle в блоке dependencies:
dependencies {
    ...
    implementation 'com.android.installreferrer:installreferrer:1.0'
}

Отслеживание источников установок в AppMetrica SDK работает по умолчанию.

Чтобы отключить отслеживание, внесите следующие изменения в файле AndroidManifest.xml:
<manifest
    ...
    xmlns:tools="http://schemas.android.com/tools">
    ...
    <application ...>
        ...
        <receiver android:name="com.yandex.metrica.MetricaEventHandler" tools:node="remove"/>
        ...
    </application>
</manifest>

Использование нескольких систем трекинга

При одновременном использовании нескольких систем трекинга статистика может собираться некорректно. Это происходит из-за того, что каждая система трекинга добавляет свой INSTALL_REFERRER BroadcastReceiver. А некоторые версии Google Play передают INSTALL_REFERRER только одной системе трекинга. Чтобы решить эту проблему, выполните следующие действия:

  1. Добавьте главный INSTALL_REFERRERBroadcastReceiver AppMetrica в файл AndroidManifest.xml:
    <manifest ...>
        ...
        <application ...>
            ...
            <receiver
                android:name="com.yandex.metrica.MetricaEventHandler"
                android:enabled="true"
                android:exported="true">
                <intent-filter>
                    <action android:name="com.android.vending.INSTALL_REFERRER"/>
                </intent-filter>
            </receiver>
            ...
        </application>
    </manifest>
  2. Зарегистрируйте INSTALL_REFERRER BroadcastReceiver других систем трекинга, используя метод YandexMetrica.registerReferrerBroadcastReceivers(BroadcastReceiver... anotherReferrerReceivers):
    public void YourApplication extends Application {
    
        @Override
        public void onCreate() {
            super.onCreate();
            // Инициализация AppMetrica SDK.
            ...
            // Создание INSTALL_REFERRER BroadcastReceiver для другой системы трекинга.
            AnotherReferrerReceiver anotherReferrerReceiver = new AnotherReferrerReceiver();
            // Регистрация созданного INSTALL_REFERRER BroadcastReceiver в Appmetrica.
            YandexMetrica.registerReferrerBroadcastReceivers(anotherReferrerReceiver);
            ...
        }
    }

Таким образом библиотека получит INSTALL_REFERRER, учтет его и передаст другим зарегистрированным трекерам. Тогда все трекеры в равных условиях смогут учесть INSTALL_REFERRER.

Если данное решение не подходит, можно отключить трекинг INSTALL_REFERRER в AppMetrica SDK и реализовать собственный BroadcastReceiver, который будет обеспечивать доставку INSTALL_REFERRER всем системам трекинга:

public class YourOwnReceiver extends BroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {

        // Здесь необходимо передать объект Intent другим системам трекинга.

        new MetricaEventHandler().onReceive(context, intent);
    }
}

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

Чтобы отслеживать открытия приложения с помощью deeplink, необходимо добавить изменения в Activity, которая обрабатывает deeplink. Отслеживание открытий необходимо для корректного трекинга ремаркетинг-кампаний.

Примечание. Для работы с deeplink поддержите их в вашем приложении.

Отслеживание открытий осуществляется с помощью метода reportAppOpen():

public class DeeplinkActivity extends Activity {

    @Override
    protected void onCreate(@Nullable final Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);    
        if (savedInstanceState == null) {
            YandexMetrica.reportAppOpen(this);
        }
    }
    @Override
    protected void onNewIntent(final Intent intent) {
        super.onNewIntent(intent);
        YandexMetrica.reportAppOpen(this);
    }
}

Запрос параметров отложенного deeplink

Чтобы запросить параметры отложенного deeplink, передайте в метод YandexMetrica.requestDeferredDeeplinkParameters(DeferredDeeplinkParametersListener listener) объект класса, реализующий интерфейс DeferredDeeplinkParametersListener. Метод возвращает параметры отложенного deeplink только при первом запуске приложения после получения Google Play Install Referrer.

Примечание. Если Google Play Install Referrer приходит сразу после установки, система не сможет правильно распознать первый запуск приложения.
YandexMetrica.requestDeferredDeeplinkParameters(new DeferredDeeplinkParametersListener() {
    @Override
    public void onParametersLoaded(Map<String, String> parameters) {
        // Обработка параметров deeplink.
        for (String key : parameters.keySet()) {
            Log.i("Deeplink params", "key: " + key + " value: " + parameters.get(key));
        }
    }

    @Override
    public void onError(Error error, String referrer) {
        // Обработка ошибки.
        Log.e("Error!", error.getDescription());
    }
});

Подробнее об отложенных deeplinks в разделе Поддержка отложенных deeplinks.

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

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

boolean isFirstLaunch;
// Реализуйте логику определения того, является ли запуск приложения первым.
// Например, можно проверить наличие файлов (настроек, баз данных и др.),
// которые приложение создает в свой первый запуск.
if (conditions) {
    isFirstLaunch = true;
}
// Создание расширенной конфигурации библиотеки.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        .handleFirstActivationAsUpdate(!isFirstLaunch)
        .build();
// Инициализация AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);

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

Если для отправки статистических данных требуется согласие пользователя, необходимо инициализировать библиотеку с отключенной опцией отправки статистики. Для этого передайте значение false в метод withStatisticsSending(boolean value) при создании расширенной конфигурации библиотеки.

// Создание расширенной конфигурации библиотеки.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Отключение отправки статистики.
        .withStatisticsSending(false)
        .build();
// Инициализация AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);
После того как пользователь дал согласие на отправку статистики (например, в настройках приложения или в соглашении при первом открытии), необходимо включить отправку с помощью метода YandexMetrica.setStatisticsSending(Context context, boolean enabled):
// Проверка переменной, которая отвечает за согласие пользователя.
if (flag) {
    // Включение отправки статистики.
    YandexMetrica.setStatisticsSending(getApplicationContext(), true); 
}