Installation and initialization
This is an archived version of documentation. You can find the current documentation for all platforms here.
The SDK for Android is an AAR library. The library is available in the Maven repository.
This section describes the steps to enable and initialize AppMetrica SDK:
Step 1. Add the library to your project
If you use Gradle for building the app, add this dependency to the build.gradle file:
dependencies { // AppMetrica SDK. implementation 'com.yandex.android:mobmetricalib:5.3.0' }
Copied to clipboard
Step 2. Initialize the library
Initialize the library in the app and set up user activity tracking. Extend the Application
class and override the onCreate()
method as follows:
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); } }
Copied to clipboard
The API key is a unique application identifier that is issued in the AppMetrica web interface during app registration.
Make sure you have entered it correctly.
AppMetrica allows tracking pre-installed apps. To use this feature, you should initialize the library with the extended configuration.
Optional
When using Firebase Performance Monitoring in Firebase version 31.0.0+, activate FirebaseApp for all processes, including the AppMetrica SDK process. In Application#onCreate(), call FirebaseApp.initializeApp(this) before activating the AppMetrica SDK. Otherwise, the AppMetrica SDK won't be activated.
Example:
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()
)
}
}
Step 3. (Optional) Configure location detection
Location allows you to estimate the geographical distribution of users. By default, AppMetrica determines the device location by the IP address with accuracy to the country.
To determine the device location down to the city level, open the AndroidManifest.xml file and add the uses-permission
element before the application
element:
<manifest> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> <application>...</application> </manifest>
Copied to clipboard
ACCESS_COARSE_LOCATION
allows you to track the device's location. For more information, see Android documentation.
Step 4. (Optional) Configure sending events, profile attributes, and Revenue
To collect information on user actions in the app, set up sending your own events. For more information, see Sending your own events.
To collect information about users, set up sending profile attributes. For more information, see Profiles.
To track in-app purchases, set up Revenue sending. For more information, see In-App purchases.
Step 5. Test the library operation
- Start the app with the AppMetrica SDK and use it for a while.
- Make sure your device is connected to the internet.
Troubleshooting
- Perform a minimum of 10 app actions that trigger the event sending.
It's necessary because AppMetrica accumulates events in the buffer and sends to the server in several parts.
- Wait for 10 minutes and check the report. Reports don't display events immediately.
Check your session tracking settings. For more information, see Tracking user activity.
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)
This error indicates that the method limit was exceeded at the DexIndexOverflowException stage of processing. We recommend reviewing the libraries used — perhaps they are very heavy. If they can't be replaced with lightweight alternatives, you can use multiple DEX files. This might increase the app loading time.
The code in the Application.onCreate()
method runs for all processes. If you encounter an initialization error after integrating a third-party library (such as Firebase Cloud Messaging), make sure that the third-party library is initialized only in the main process.
Error examples:
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.*
To fix the error, implement the main process check before initializing third-party libraries:
class MyApplication extends Application { @Override public void onCreate() { if (isMainProcess()) { // Initializing third-party libraries after verification. } } }
Copied to clipboard
If the manual tracking of the user session is incorrectly implemented, it may lead to an inaccurate determination of its duration.
If the user session duration data doesn't look correct, make sure that when the user session ends, the YandexMetrica.pauseSession() method is always called. If this method is not called, the library considers that the session is active and commits regular data exchange with the server part of AppMetrica.
It is recommended to check the duration of the session timeout. It is specified with the withSessionTimeout()
method. The timeout specifies the time interval during which the session will be considered active even after the application is closed.
If there is the increased power consumption of the library, make sure that when the user session ends, the YandexMetrica.pauseSession()
method is always called. If this method is not called, the library considers that the session is active and commits regular data exchange with the server part of AppMetrica.
It is recommended to check the duration of the session timeout. It is specified with the withSessionTimeout()
method. The timeout specifies the time interval during which the session will be considered active even after the application is closed.
- The source code snippet that shows the SDK integration to your app.
- Application ID in the AppMetrica web interface.
- Device ID.
- Install the AppMetrica app on the test device.
- Log in and select your app from the list.
- In the upper-left corner, click.
- The Google AID is shown in the AID field. Enter it in the AppMetrica web interface.
How to get the Google AIDNote. You can enable attribution testing in the AppMetrica app. To do this, turn on Attribution testing. - Device model and manufacturer, platform and OS version, AppMetrica SDK version.