Подключение и инициализация

Внимание.

Это архивная версия документации. Актуальная документация по всем платформам находится здесь.

SDK под Android предоставляется в виде библиотеки в формате AAR. Библиотека доступна в Maven-репозитории.

Ниже описаны этапы подключения и инициализации AppMetrica SDK:

  1. Шаг 1. Добавьте библиотеку в проект
  2. Шаг 2. Инициализируйте библиотеку
  3. Шаг 3. (Опционально) Настройте определение местоположения
  4. Шаг 4. (Опционально) Настройте отправку событий, атрибутов профиля и Revenue
  5. Шаг 5. Протестируйте работу библиотеки

Шаг 1. Добавьте библиотеку в проект

Если вы используете Gradle для сборки приложения, добавьте следующую зависимость в файле build.gradle:

dependencies {
    // AppMetrica SDK.
    implementation 'com.yandex.android:mobmetricalib:5.3.0'
}
Скопировано

Шаг 2. Инициализируйте библиотеку

Внимание. В библиотеке AppMetrica есть особенности, которые необходимо учитывать при инициализации. Подробнее в разделе Особенности библиотеки AppMetrica.

Инициализируйте библиотеку в приложении и настройте отслеживание активности пользователей. Для этого объявите производный класс от базового класса Application и переопределите метод onCreate() следующим образом: 

public class MyApp extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        // Creating an extended library configuration.
        YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key).build();
        // Initializing the AppMetrica SDK.
        YandexMetrica.activate(getApplicationContext(), config);
        // Automatic tracking of user activity.
        YandexMetrica.enableActivityAutoTracking(this);
        }
}
Скопировано
Что такое API key?

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

Убедитесь, что он указан верно.

AppMetrica позволяет отслеживать предустановленные приложения. Для этого инициализируйте библиотеку с расширенной конфигурацией.

Опционально

При использовании Firebase Performance Monitoring в Firebase версии 31.0.0+ необходимо активировать FirebaseApp для всех процессов, в том числе, процесса AppMetrica SDK. В Application#onCreate() необходимо вызвать FirebaseApp.initializeApp(this) строго до активации AppMetrica SDK. В противном случае SDK AppMetrica не будет активирован.

Пример:

class MainApplication : Application() {
    
    override fun onCreate() {
        super.onCreate()
        
        // Init FirebaseApp for all processes
        FirebaseApp.initializeApp(this)
        
        // Then activate AppMetrica SDK
        YandexMetrica.activate(
            this,
            YandexMetricaConfig.newConfigBuilder(API_KEY)
                .build()
        )
    }
}

Шаг 3. (Опционально) Настройте определение местоположения

Определение местоположения позволяет оценить географическое распределение пользователей. По умолчанию AppMetrica определяет местоположение устройства по IP-адресу с точность до страны.

Чтобы определять местоположение с точностью до города, в файле AndroidManifest.xml перед элементом application добавьте элемент uses-permission:

<manifest>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <application>...</application>
</manifest>
Скопировано

ACCESS_COARSE_LOCATION позволяет отслеживать местоположение устройства. Подробнее в документации Android.

Шаг 4. (Опционально) Настройте отправку событий, атрибутов профиля и Revenue

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

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

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

Чтобы отслеживать покупки в приложении, настройте отправку Revenue. Подробнее в разделе In-App покупки.

Шаг 5. Протестируйте работу библиотеки

Внимание. Перед проверкой работы библиотеки убедитесь, что SDK инициализирована с соблюдением рекомендаций.
Чтобы проверить работу библиотеки:
  1. Запустите приложение с AppMetrica SDK и используйте его некоторое время.
  2. Убедитесь, что устройство подключено к интернету.
  3. В интерфейсе AppMetrica убедитесь, что:
    • В отчете Аудитория появился новый пользователь.
    • В отчете Вовлечённость → Сессии увеличилось число сессий.
    • В отчете События и Профили появились отправленные события и атрибуты профиля.

Возможные проблемы и их решение

Не увеличивается число сессий

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

Нет событий
  1. Совершите в приложении минимум 10 действий, которые инициируют отправку событий.

    Это необходимо, потому что события накапливаются и отправляются на сервер по несколько штук.

  2. Подождите 10 минут и проверьте отчет. События отображаются в отчете не сразу.
Ошибка при добавлении библиотеки в проект
UNEXPECTED TOP-LEVEL EXCEPTION:
com.android.dex.DexIndexOverflowException: method ID not in [0, 0xffff]: 65536
at com.android.dx.merge.DexMerger$6.updateIndex(DexMerger.java:502)
at com.android.dx.merge.DexMerger.mergeMethodIds(DexMerger.java:491)
at com.android.dx.merge.DexMerger$IdMerger.mergeSorted(DexMerger.java:277)
at com.android.dx.command.dexer.Main.runMonoDex(Main.java:303)
at com.android.dx.command.dexer.Main.mergeLibraryDexBuffers(Main.java:454)
at com.android.dx.merge.DexMerger.mergeDexes(DexMerger.java:168)
at com.android.dx.merge.DexMerger.merge(DexMerger.java:189)
at com.android.dx.command.dexer.Main.run(Main.java:246)
at com.android.dx.command.dexer.Main.main(Main.java:215)
at com.android.dx.command.Main.main(Main.java:106)

Данная ошибка сообщает, что превышен лимит методов на этапе обработки DexIndexOverflowException. Рекомендуем пересмотреть используемые библиотеки — возможно, они очень тяжеловесны. Если их нельзя заменить легковесными аналогами, то можно использовать несколько DEX-файлов. Это может увеличить время загрузки приложения.

Ошибка инициализации AppMetrica со сторонними библиотеками

Код, который добавлен в метод Application.onCreate(), выполняется для всех процессов. Если после интеграции сторонней библиотеки (например, Firebase Cloud Messaging) возникает ошибка инициализации, убедитесь, что сторонняя библиотека инициализируется только в главном процессе.

Примеры ошибок:

  • Unable to create application your.package.name.YourApp: java.lang.IllegalStateException: Default FirebaseApp is not initialized in this process your.package.name:Metrica. Make sure to call FirebaseApp.initializeApp(Context) first.
  • android.database.sqlite.SQLiteException: table httpauth already exists (code 1)
  • Fatal Exception: java.lang.RuntimeException: Using WebView from more than one process at once with the same data directory is not supported.
  • ANR at com.google.android.gms.ads.*

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

class MyApplication extends Application {
    @Override
    public void onCreate() {
        if (isMainProcess()) {
            // Initializing third-party libraries after verification.
        }
    }
}
Скопировано
Примечание. Проверку главного процесса реализуйте самостоятельно. Например, как это сделано в ответе на Stack Overflow.
Некорректная длительность пользовательской сессии при ручном отслеживании

При неправильной реализации ручного отслеживания сессии возможно неточное определение ее длительности.

Если данные о длительности сессий выглядят некорректно, убедитесь, что при завершении пользовательской сессии всегда вызывается метод YandexMetrica.pauseSession(). Если метод не вызван, библиотека считает сессию активной и совершает регулярный обмен данными с серверной частью AppMetrica.

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

Высокое энергопотребление библиотекой AppMetrica

При повышенном энергопотреблении библиотекой, убедитесь, что при завершении пользовательской сессии всегда вызывается метод YandexMetrica.pauseSession(). Если метод не вызван, библиотека считает сессию активной и совершает регулярный обмен данными с серверной частью AppMetrica.

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

В списке нет моей проблемы
Если в списке нет вашей проблемы, обратитесь в службу поддержки. В обращении укажите:
  1. Пример интеграции SDK в вашем приложении.
  2. ID приложения в веб-интерфейсе AppMetrica.
  3. ID устройства.
    Как получить Google AID
    1. Установите приложение AppMetrica на тестовое устройство.
    2. Авторизуйтесь и выберите из списка ваше приложение в AppMetrica.
    3. В левом верхнем углу нажмите  → Устройство.
    4. Google AID указан в поле AID. Укажите его в веб-интерфейсе AppMetrica.
    Примечание. Тестирование атрибуции можно включить в приложении AppMetrica. Для этого включите Тест атрибуции.
  4. Производителя и модель устройства, платформу и версию ОС, версию AppMetrica SDK.

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