Usage examples

To initialize the library with the extended startup configuration, create an instance of the YandexMetricaConfig class with appropriate settings and activate the library using the YandexMetrica.activate(Context context, YandexMetricaConfig config) method. With the extended configuration allows you to enable/disable logging, set session timeout, pass parameters for tracking pre-installed apps, and so on.

The parameters of the extended configuration are applied from the time of library initialization.

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        // Creating an extended library configuration.
        YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
                // Setting up the configuration. For example, to enable logging.
                .withLogs()
                ...
                .build();
        // Initializing the AppMetrica SDK.
        YandexMetrica.activate(getApplicationContext(), config);
        // Automatic tracking of user activity.
        YandexMetrica.enableActivityAutoTracking(this);
    }
}
Copied to clipboard

To configure the library while the application is running, use the methods of the YandexMetrica class.

Sending data to an additional API key allows you to collect own statistics for these API keys. You can use this to control access to information for other users. For example, to provide access to statistics for analysts you can duplicate sending marketing data for the additional API key. Thus they will only have access to the information they need.

To send data to an additional API key, you must use reporters. Just like for the main API key, you can set up an extended startup configuration for a reporter, send events, profile information, and data about in-app purchases. The reporter can work without the AppMetrica SDK initialization.

Reports on app crashes are sent by default.

To disable automatic monitoring, initialize the library with the configuration in which sending crashes is disabled. To do this, pass the false value to the withLocationTracking(boolean enabled) method when creating the extended library configuration.

// Creating an extended library configuration.
        YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Disabling the data sending about the app crashes.
        .withCrashReporting(false)
        .build();
// Initializing the AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);

If automatic monitoring is disabled, you can manually submit information about crashes.

Reports on app crashes are sent by default. To avoid exception events duplication, disable the automatic monitoring of the app crashes.

To send crash information manually, use the YandexMetrica.reportUnhandledException(Throwable exception) method.

final Thread.UncaughtExceptionHandler previousUncaughtExceptionHandler = Thread.getDefaultUncaughtExceptionHandler();
// Creating a new handler.
Thread.UncaughtExceptionHandler uncaughtExceptionHandler = new Thread.UncaughtExceptionHandler() {
    @Override
    public void uncaughtException(Thread thread, Throwable exception) {
        try {
            // Sending a message about an app crash to the AppMetrica server.
            YandexMetrica.reportUnhandledException(exception);
        } finally {
            // Sending a message about an app crash to the system handler.
            if (previousUncaughtExceptionHandler != null) {
                previousUncaughtExceptionHandler.uncaughtException(thread, exception);
            }
        }
    }
};
// Setting the default handler.
Thread.setDefaultUncaughtExceptionHandler(uncaughtExceptionHandler);
Copied to clipboard

Reports are sent automatically on native app crashes if the library's SO files are added to the project. By default, SO files are omitted. To add them, enable the library for tracking native crashes.

To enable the library, add the following dependency to the build.gradle file in the dependencies block:

dependencies {
    ...
    implementation 'com.yandex.android:mobmetricalib-ndk-crashes:1.1.0'
}
Copied to clipboard

If you don't use Gradle

Download the library and add it to the project.

It contains libraries for all the platforms (arm, armv7, mips, x86). Use abi splits to exclude unnecessary libraries.

To disable automatic monitoring, initialize the library with the configuration in which sending crashes is disabled. To do this, pass the false value to the withNativeCrashReporting(boolean enabled) method when creating the extended library configuration.

// Creating an extended library configuration.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Disabling the data sending about the native app crashes.
        .withNativeCrashReporting(false)
        .build();
// Initializing the AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);
Copied to clipboard

If automatic monitoring is disabled, you can manually submit information about native crashes.

Reports are sent automatically on native app crashes if the library's SO files are added to the project. If files have been added, you should disable the automatic monitoring of the app crashes to avoid exception events duplication.

To manually send information about native app crashes, use the YandexMetrica.reportNativeCrash(String nativeCrash) method.

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" +
"...";
// Sending native app crash information.
YandexMetrica.reportNativeCrash(nativeCrashContent);
Copied to clipboard

// Creating an extended library configuration.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Enabling the data sending about the device location.
        .withLocationTracking(true)
        .build();
// Initializing the AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);
Copied to clipboard

To enable sending while the app is running, use the YandexMetrica.setLocationTracking(boolean enabled) method:

YandexMetrica.setLocationTracking(true);
Copied to clipboard

Before sending custom information about the device location, make sure that reporting is enabled.

The library determines the device location on its own. To send your own device location information, pass an instance of the android.location.Location class into the YandexMetrica.setLocation(Location Location) method.

// Determining the location.
Location currentLocation = ...;
// Setting your own location information of the device.
YandexMetrica.setLocation(currentLocation);
Copied to clipboard

// Determining the location.
Location currentLocation = ...;

// Creating an extended library configuration.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Set your own location information of the device.
        .withLocation(currentLocation)
        .build();
// Initializing the AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);
Copied to clipboard

To resume location detection by the library, pass the null value to the YandexMetrica.setLocation(Location location) method and configure sending the device location data.

YandexMetrica.setLocation(null);
Copied to clipboard

To send your custom event without nested parameters, pass a short name or description of the event to the YandexMetrica.reportEvent(String eventName) method:

YandexMetrica.reportEvent("Updates installed");
Copied to clipboard

The AppMetrica SDK allows you to send your own events with nested parameters that can be set in the JSON format or as a set of attributes (Map).

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

YandexMetrica.reportEvent("New person", eventParameters);
Copied to clipboard

Map<String, Object> eventParameters = new HashMap<String, Object>();
eventParameters.put("name", "Alice");
eventParameters.put("age", 18);

YandexMetrica.reportEvent("New person", eventParameters);
Copied to clipboard

The AppMetrica web interface displays up to five nesting levels for events. So if an event has six or more levels, only the top five are shown in the report. You can use the Reporting API to get up to ten levels.

For more information about events, see Events.

The AppMetrica SDK lets you send client events from JavaScript code. Initialize the sending by calling the initWebViewReporting method:

WebView webView = (WebView) findViewById(R.id.myWebView);
// do your initialization here
webView.getSettings().setJavaScriptEnabled(true);
YandexMetrica.initWebViewReporting(webView);
webView.loadUrl(myURL);
Copied to clipboard

val webView = findViewById<WebView>(R.id.myWebView)
// do your initialization here
webView.settings.javaScriptEnabled = true
YandexMetrica.initWebViewReporting(webView)
webView.loadUrl(myURL)
Copied to clipboard

Call the initWebViewReporting method after calling the setJavaScriptEnabled method but before calling loadUrl.

To send an event from JavaScript code, use the reportEvent(name, value) method in the AppMetrica interface:

function buttonClicked() {
  AppMetrica.reportEvent('Button clicked!', '{}');
})
Copied to clipboard

Arguments of the reportEvent method:

• name — A string. Can't be null or empty.
• value — A JSON string. Can be null.

If you know the user profile ID before initializing the AppMetrica SDK, pass it before initialization (setUserProfileID) or during initialization with the extended configuration (withUserProfileID).

Otherwise, a user profile is created with the ID appmetrica_device_id.

You can update ProfileId at any time by calling setUserProfileID:

YandexMetrica.setUserProfileID("id");
Copied to clipboard

To send profile attributes, pass to the instance of the UserProfile class required attributes and send this instance using the YandexMetrica.reportUserProfile(UserProfile profile) method. To create profile attributes, use methods of the Attribute class.

// Creating the UserProfile instance.
UserProfile userProfile = UserProfile.newBuilder()
        // Updating predefined attributes.
        .apply(Attribute.name().withValue("John"))
        .apply(Attribute.gender().withValue(GenderAttribute.Gender.MALE))
        .apply(Attribute.birthDate().withAge(24))
        .apply(Attribute.notificationsEnabled().withValue(false))
        // Updating custom attributes.
        .apply(Attribute.customString("string_attribute").withValue("string"))
        .apply(Attribute.customNumber("number_attribute").withValue(55))
        .apply(Attribute.customCounter("counter_attribute").withDelta(1))
        .build();
// Setting the ProfileID using the method of the YandexMetrica class.
YandexMetrica.setUserProfileID("id");

// Sending the UserProfile instance.
YandexMetrica.reportUserProfile(userProfile);
Copied to clipboard

In AppMetrica, it is not possible to segment E-commerce events into “test” and “not test”. If you use the main API key for debugging purchases, the test events are included in general statistics. If you need to debug sending E-commerce events, use a reporter to send statistics to an additional API key.

AppMetrica supports the validation of purchases made using the Google Play Billing library. Validation lets you filter purchases made from hacked apps. If validation is enabled and a purchase fails it, this purchase isn't shown in reports.

By default, the session timeout is 10 seconds. The minimum acceptable value for the sessionTimeout parameter is 10 seconds.

To change the length of the timeout, pass the value in seconds to the withSessionTimeout(int sessionTimeout) method when creating the extended library configuration.

// Creating an extended library configuration.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Setting the length of the session timeout.
        .withSessionTimeout(15)
        .build();
// Initializing the AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);
Copied to clipboard

By default, the app version is set in the file build.gradle.

To specify the app version from the code, pass the app version to the withAppVersion(String appVersion) method when creating the extended library configuration.

// Creating an extended library configuration.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Setting the app version.
        .withAppVersion("1.13.2")
        .build();
// Initializing the AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);
Copied to clipboard

where 1.13.2 is the app version.

To determine the library version from the application code, use the YandexMetrica.getLibraryVersion() method:

String libraryVersion = YandexMetrica.getLibraryVersion();
Copied to clipboard

Tracking installation source in AppMetrica SDK is enabled by default.

<manifest
    ...
    xmlns:tools="http://schemas.android.com/tools">
    ...
    <application ...>
        ...
        <receiver android:name="com.yandex.metrica.MetricaEventHandler" tools:node="remove"/>
        ...
    </application>
</manifest>
Copied to clipboard

To track app openings that use deeplinks, you make changes in the Activity that handles deeplinks. You need to track app openings to correctly track remarketing campaigns.

Use the reportAppOpen() method to track app openings:

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(intent);
    }
}
Copied to clipboard

To request a deferred deeplink, pass a class instance that implements the DeferredDeeplinkListener interface to the YandexMetrica.requestDeferredDeeplink(DeferredDeeplinkListener listener) method. The method returns the deferred deeplink only at the initial application start after obtaining the Google Play Install Referrer.

YandexMetrica.requestDeferredDeeplink(new DeferredDeeplinkListener() {
    @Override
    public void onDeeplinkLoaded(String deeplink) {
        Log.i("Deeplink", "deeplink = " + deeplink);
    }

    @Override
    public void onError(Error error, String referrer) {
        Log.i("Deeplink", "Error: " + error.getDescription() + ", unparsed referrer: " + referrer);
    }
});
Copied to clipboard

YandexMetrica.requestDeferredDeeplink(object : DeferredDeeplinkListener {
    override fun onDeeplinkLoaded(deeplink: String) {
        Log.i("Deeplink", "deeplink = $deeplink")
    }

    override fun onError(error: DeferredDeeplinkListener.Error, referrer: String?) {
        Log.i("Deeplink", "Error: ${error.description}, unparsed referrer: $referrer")
    }
})
Copied to clipboard

For more information about deferred deeplinks, see Support for deferred deeplinks

To request parameters for a deferred deeplink, pass to the YandexMetrica.requestDeferredDeeplinkParameters(DeferredDeeplinkParametersListener listener) method an instance that implements the DeferredDeeplinkParametersListener interface. The method returns the deferred deeplink parameters only at the first application start after Google Play Install Referrer obtaining.

YandexMetrica.requestDeferredDeeplinkParameters(new DeferredDeeplinkParametersListener() {
    @Override
    public void onParametersLoaded(Map<String, String> parameters) {
        // Processing 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) {
        // Handling the error.
        Log.e("Error!", error.getDescription());
    }
});
Copied to clipboard

For more information about deferred deeplinks, see Support for deferred deeplinks

By default, when the app is first launched, all users are identified as new. If the AppMetrica SDK connects to an app that already has active users, you can configure it for new and old users to track statistics correctly. To set this up, initialize the AppMetrica SDK with the extended configuration YandexMetricaConfig:

boolean isFirstLaunch;
// Implement logic to detect whether the app is opening for the first time.
// For example, you can check for files (settings, databases, and so on),
// which the app creates on its first launch.
if (conditions) {
    isFirstLaunch = true;
}
// Creating an extended library configuration.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        .handleFirstActivationAsUpdate(!isFirstLaunch)
        .build();
// Initializing the AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);
Copied to clipboard

If you need confirmation from the user before sending statistical data, you should initialize the library with the disabled sending option. Pass the false value to the withStatisticsSending() method when creating the extended library configuration.

// Creating an extended library configuration.
YandexMetricaConfig config = YandexMetricaConfig.newConfigBuilder(API_key)
        // Disabling sending statistics.
        .withStatisticsSending(false)
        .build();
// Initializing the AppMetrica SDK.
YandexMetrica.activate(getApplicationContext(), config);
Copied to clipboard

// Checking the status of the boolean variable. It shows the user confirmation.
if (flag) {
    // Enabling sending statistics.
    YandexMetrica.setStatisticsSending(getApplicationContext(), true);
}
Copied to clipboard