Документация
Интеграция SDK

Операции

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

Инициализация библиотеки

Чтобы инициализировать библиотеку в приложении, передайте в метод activate класса YandexMetrica контекст приложения: YandexMetrica.activate(android.content.Context, java.lang.String).

Рекомендуем произвести инициализацию, переопределив метод onCreate() следующим образом:

public class MyApp extends Application {
      @Override
      public void onCreate() {
          super.onCreate();
          YandexMetrica.activate(getApplicationContext(), API_key
[no-highlight[

API key — это уникальный идентификатор приложения, который выдается в веб-интерфейсе AppMetrica при добавлении приложения.

]no-highlight]
);
} }

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

Данный способ инициализации позволяет задать параметры для отслеживания предустановленных приложений, а также передать другие параметры с помощью методов класса 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
[no-highlight[

API key — это уникальный идентификатор приложения, который выдается в веб-интерфейсе AppMetrica при добавлении приложения.

]no-highlight]
); //Задание необходимых параметров (например включение логирования) configBuilder.setLogEnabled(); ... //Создание объекта расширенной конфигурации 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 приложения
[no-highlight[

API key — это уникальный идентификатор приложения, который выдается в веб-интерфейсе AppMetrica при добавлении приложения.

]no-highlight]
можно использовать т. н. репортеры. Это может быть удобно для сбора статистики других библиотек.

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

  1. Скачайте SO-файлы (они доступны в описании релиза).
  2. Поместите файл libYandexMetricaNativeModule.so в каталог проекта (в соответствии с архитектурой проекта, которую вы используете).

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

YandexMetrica.setReportNativeCrashesEnabled(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);

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

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

Примечание. Если отправка местоположения библиотекой включена, для более точного определения местоположения рекомендуем добавить в файл 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()

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

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

YandexMetrica.setCollectInstalledApps(true);
Внимание! 

Чтобы отправлять сведения об установленных приложениях необходимо явно уведомить об этом пользователей (согласием с соответствующим пунктом пользовательского соглашения или прямо в интерфейсе приложения).

Допускается отправка сведений об установленных приложениях, если вашему приложению требуется список установленных приложений для базовой функциональности. Иначе приложение может быть заблокировано в GooglePlay.

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

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

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

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

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

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

<manifest ...>
    ...
    <application ...>
        ...
        <receiver
            android:name="com.yandex.metrica.MetricaEventHandler"
            android:enabled="true"
            android:exported="true">

            <!-- INSTALL_REFERRER необходим для трекинга кампаний -->
            <intent-filter>
                <action android:name="com.android.vending.INSTALL_REFERRER"/>
            </intent-filter>
        </receiver>
        <!-- end of Yandex Metrica -->   
        ...          
    </application>
</manifest>
Отключение трекинга

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

<manifest ...>
    ...
    <application ...>        
        ...
        <receiver android:name="com.yandex.metrica.MetricaEventHandler" tools:node="remove">
        </receiver>
        <!-- end of Yandex Metrica -->   
        ...          
    </application>
</manifest>

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

<manifest ...>
    ...
    <receiver
        android:name="com.yandex.metrica.MetricaEventHandler"
        android:enabled="true"
        android:exported="true">

        <!-- INSTALL_REFERRER необходим для трекинга кампаний -->
        <intent-filter>
            <action android:name="com.android.vending.INSTALL_REFERRER"/>
        </intent-filter>
    </receiver> 
    ...
</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());
  }
});