Android Getting Started

Integrating the IV Metrics SDK for Android is the first step towards recording user gameplay and tracking their progress in your mobile game.

Download the latest IV Metrics SDK

Prerequisites

The following prerequisites are needed to run IV Metrics:

Compile-Time

Minimum SDK version 21 or higher

Runtime

Gameplay recording requires a minimum 1.5 GB total device RAM

Configure Your App

Download the latest ivmetrics-core.aar library
Drag the downloaded library into your module’s “libs” folder
Add the dependencies for the IV Metrics SDK to your app-level build file:

dependencies {
    implementation 'com.squareup.okhttp3:okhttp:4.11.0' 
    implementation 'androidx.work:work-runtime:2.9.1' 
    implementation 'org.json:json:20250107'
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
    implementation 'androidx.activity:activity:1.6.1'
}

Click Sync Now. For details on syncing, see Sync projects with Gradle files.

Initialise the IV Metrics SDK

You must initialise the SDK as soon as you can within the app’s lifecycle, else you risk missing data that could be crucial to getting the full picture of each user’s experience within your game.

The following things are required to be passed through to the IVMetrics.Create(…); function, they MUST be NonNull:

Activity _mainActivity
1. The core activity that is active throughout the application’s lifecycle.
SurfaceView _mainSurfaceView
1. The core SurfaceView that the application uses to render the gameplay to the device.
IVMetricsCallbacks _callbacks
1. This is the callback for touch interaction from the SDK into your game, or for interaction with 3rd party SDKs. This SDK requires overriding the touch listener, so to access the touch data you need to implement this callback.
String _developerKey
1. You can find this Key on the IV Metrics panel.
String _projectKey
1. You can also find this Key on the IV Metrics panel.
boolean _verboseLogging
1. This should only be enabled for debugging purposes. You must set this to false when building for production
boolean _enableConsentForm
1. (Optional) You may wish to present a consent form to the user before the SDK is allowed to upload any recording data from the user. All data is anonymous no matter if this option is enabled or disabled.
IVConsentFormShowTrigger _consentShowTrigger
1. (Optional) If you enable the consent form, you can tell the SDK how you wish it to show the consent form.
String _privacyPolicyUrl
1. (Optional) The consent form contains a button that links the user to your company’s privacy policy. Set this to an empty string if the consent form is disabled.

An example of how you could initialise the SDK

import com.ivmetrics.core.IVMetrics;
import com.ivmetrics.core.IVMetricsCallbacks;

public class MainActivity extends AppCompatActivity
{
    private SurfaceView mySurfaceView;

    //
    protected void onCreate(Bundle _savedInstanceState) 
    {
        super.onCreate(_savedInstanceState);
        setContentView(R.layout.activity_main);

        IVMetrics.Create(this,
                         mySurfaceView,
                         "DEV-KEY-XXXX",
                         "PRJ-KEY-XXXX",
                         false, // Verbose Logging Disabled
                         true, // Consent Form Enabled
                         IVConsentFormShowTrigger.AutomaticWhenRequired,
                         "https://mycompany.com/privacyPolicy");
    }
}

Setup Complete

Your project is now set up to use IV Metrics when deploying to Android devices. You should begin to see devices appearing in requests on the panel when the project is ran on a device.

To begin receiving recordings from devices, go to the IV Metrics panel and create a new request.

It is not a requirement on Android to show the consent form before a recording can take place, however you may wish to show the builtin consent form manually, automatically when the SDK begins it’s first recording session for the user, or automatically when the SDK starts up for the first time on the user’s device.

IV Metrics v1.8.0 SDK has introduced more APIs for the consent form:

IVMetrics.GetConsentStatus()
- Returns: IVConsentStatus
- Description: Will return the consent status of the user stored by the SDK.
IVMetrics.SetConsentStatus(IVConsentStatus)
- Returns: void
- Description: Set the consent status for the user. Useful if you wish to show your own consent form.
IVMetrics.ShowConsentForm()
- Returns: void
- Description: Show the builtin consent form. Use if you set the consent show trigger to Manual.

Next Steps

Now the IV Metrics SDK is implemented, here’s some additional things you can do with the IV Metrics SDK:

Events API

Legacy Support Solutions

N/A