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

Данные операции позволяют настроить работу библиотеки.

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

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

Данный способ инициализации позволяет задать параметры для отслеживания предустановленных приложений, а также передать другие параметры с помощью методов класса com.yandex.metrica.YandexMetrica (например, отслеживание активности пользователей). Параметры расширенной конфигурации применяются с момента инициализации библиотеки. Параметры, заданные с помощью методов класса com.yandex.metrica.YandexMetrica могут применяться с некоторой задержкой.

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

Отправка статистики с использованием API key, отличного от API key приложения

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

Для применения API key, который отличается от API key приложения можно использовать т. н. репортеры. Это может быть удобно для сбора статистики других библиотек.

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

Чтобы использовать репортер, необходимо получить объект, реализующий интерфейс IReporter с помощью метода

public static IReporter getReporter(Context context, String apiKey);

Первый вызов произведет инициализацию репортера для указанного API key. Следующие вызовы вернут ссылку на уже инициализированный IReporter.

Полученный объект можно использовать для отправки данных с помощью методов интерфейса IReporter, передав в метод API key, для которого необходимо отправить данные.

Пример:

YandexMetrica.getReporter(this, API_key).reportEvent("Updates installed");

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

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

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

YandexMetrica.setReportCrashesEnabled(false);

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

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

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

Например:

Thread.setDefaultUncaughtExceptionHandler(myUncaughtExceptionHandler);
...
Thread.UncaughtExceptionHandler myUncaughtExceptionHandler = new Thread.UncaughtExceptionHandler() {
    @Override
    public void uncaughtException(Thread thread, Throwable exception) {
        YandexMetrica.reportUnhandledException(exception);
    }
}

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

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

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

compile 'com.yandex.android:mobmetricalib-ndk-crashes:1.0.0'

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

Чтобы отключить отслеживание, используйте метод YandexMetricaConfig.withNativeCrashReporting(boolean enabled).

YandexMetricaConfig.withNativeCrashReporting(false);

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

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

Чтобы отправлять информацию о нативных аварийных остановках приложения вручную, используйте метод 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);

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

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

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

Примечание. Если отправка местоположения библиотекой включена, для более точного определения местоположения рекомендуем добавить в файл AndroidManifest.xml следующее разрешение: android.permission.ACCESS_COARSE_LOCATION.

Отправка данных о местоположении включена по умолчанию. Для отключения используйте метод YandexMetrica.setTrackLocationEnabled(boolean enabled).

YandexMetrica.setTrackLocationEnabled(false);

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

Если вы хотите использовать собственные данные о местоположении устройства вместо автособираемых, используйте метод YandexMetrica.setLocation(android.location.Location);.

В качестве входных параметров передается объект android.location.Location:

Location currentLocation = ...;
YandexMetrica.setLocation(currentLocation);

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

YandexMetrica.setLocation(null);

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

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

YandexMetrica.reportEvent("Updates installed");

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

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

Доступно пять уровней вложенности JSON-объекта.

String eventParameters = "{\"name\":\"Alice\", \"age\":\"18\"}";

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

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

Отправка собственного события в виде набора атрибутов (Map)

Чтобы отправить произвольное сообщение о событии в виде Map, передайте в метод YandexMetrica.reportEvent(String eventName, Map<String, Object> attributes) краткое имя и описание события.

Map<String, Object> eventAttributes = new HashMap<String, Object> ();
eventAttributes.put("Application", "com.company.myapp.awesomeapp");
eventAttributes.put("Audience", 1000000000);
eventAttributes.put("Product price in $", 10000000.99);

YandexMetrica.reportEvent("Current app statistics", eventAttributes);

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

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

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

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

Задание длительности тайм-аута сессии

По умолчанию сессия заканчивается, если активность приложения отсутствует в течение 10 секунд. Чтобы изменить данный лимит времени, передайте в метод YandexMetrica.setSessionTimeout(int sessionTimeoutSeconds) свой лимит времени в секундах.

Минимально допустимое значение параметра sessionTimeoutSeconds составляет 10 секунд. При задании значения меньше 10, значение автоматически будет соответствовать 10 секундам.

YandexMetrica.setSessionTimeout(15);

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

По умолчанию версия приложения задается в файле AndroidManifest.xml. Если необходимо указать версию непосредственно из кода приложения, передайте в метод YandexMetrica.setCustomAppVersion(String appVersion) версию приложения.

YandexMetrica.setCustomAppVersion("1.13.2");

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

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

Уровень API указывается в разделе История изменений. Если вы хотите определить уровень API непосредственно из кода приложения, используйте данный метод:

YandexMetrica.getLibraryApiLevel()

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

Версия библиотеки указывается в разделе История изменений. Если вы хотите определить версию библиотеки непосредственно из кода приложения, используйте данный метод:

YandexMetrica.getLibraryVersion()

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

AppMetrica позволяет отслеживать INSTALL_REFERRER от GooglePlay. Эта информация полезна для анализа источников установки вашего приложения.

Включение трекинга

Если вы подключили библиотеку AppMetrica в AAR-формате, то отслеживание источников установки производится автоматически.

Отключение трекинга

Если вы подключили библиотеку AppMetrica в AAR-формате, внесите следующие изменения в код файла AndroidManifest.xml, чтобы отключить трекинг:

<manifest ...>
    ...
    <application ...>        
        ...
        <receiver android:name="com.yandex.metrica.MetricaEventHandler" tools:node="remove">
        </receiver>
        <!-- end of Yandex Metrica -->   
        ...          
    </application>
</manifest>
Одновременное использование нескольких систем трекинга

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

  1. Добавьте главный INSTALL_REFERRERBroadcastReceiver библиотеки AppMetrica в файл AndroidManifest.xml.
  2. Зарегистрируйте в библиотеке INSTALL_REFERRER BroadcastReceiver других систем трекинга, используя метод YandexMetrica.registerReferrerBroadcastReceivers(BroadcastReceiver... anotherReferrerReceivers) в Application.onCreate(). Например:

    public void YourApplication extends Application {
    
        @Override
        public void onCreate() {
            super.onCreate();
            ...
            YandexMetrica.activate(...);
            //Create referrer BroadcastReceiver from another tracking system
            AnotherTrackingReferrerReceiver anotherTrackingReferrerReceiver = new AnotherTrackingReferrerReceiver();
            //Register referrer BroadcastReceiver from another tracking system in AppMetrica
            YandexMetrica.registerReferrerBroadcastReceivers(anotherTrackingReferrerReceiver);
            ...
            }
    
    }

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

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

public class YourOwnReceiver extends BroadcastReceiver {

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

    // Pass the intent to other receivers.

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

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

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

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, необходимо создать объект класса, реализующий интерфейс DeferredDeeplinkParametersListerner и передать его в в метод requestDeferredDeeplinkParameters. Метод вернет параметры отложенного deeplink только при первом запуске приложения после получения Google Play Install Referrer.
Примечание. Если Install Referrer приходит сразу же после установки, система не сможет правильно распознать первый запуск приложения.

Подробнее об отложенных deeplinks смотрите Поддержка отложенных deeplinks

YandexMetrica.requestDeferredDeeplinkParameters(new DeferredDeeplinkParametersListener() {
  @Override
  public void onParametersLoaded(Map<String, String> parameters) {
    // handle deeplink parameters
    for (String key : parameters.keySet()) {
      Log.i("Deeplink params", "key: " + key + " value: " + parameters.get(key));
    }
  }
  @Override
  public void onError(Error error, String referrer) {
    // handle the error
    Log.e("Error!", error.getDescription());
  }
});

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

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

public class MyApp extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          // Создание конфигурации с отключенным сбором статистики.
          YandexMetricaConfig.Builder configBuilder = YandexMetricaConfig.newConfigBuilder("API_key");
          configBuilder.withStatisticsSending(false);
          YandexMetricaConfig config = configBuilder.build();

          // Инициализация AppMetrica SDK.
          YandexMetrica.activate(getApplicationContext(), config);
      }
}

После того как пользователь дал согласие на отправку статистики (например, в настройках приложении или в соглашении при первом открытии), необходимо вызвать метод setStatisticsSending() класса YandexMetrica.

Состояние согласия пользователя можно проверять, например, с помощью переменной типа boolean. После изменения настройки в интерфейсе, необходимо проверить состояние переменной и вызвать метод для включения отправки.

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