Android (View and Jetpack Compose) quick start

👍

Target Platforms

This quick start guide shows you how to get Heap set up in an Android application that uses a mixture of the Android View framework and Jetpack Compose for creating the user interface.

🚧

Compose Autocapture Beta

Autocapture functionality for Jetpack Compose is currently in beta. If you do not wish to use the autocapture beta in your production application, you have the option to install omit the Compose Autocapture SDK from the install instructions to still autocapture the View portions of your application.

After completing the setup process, you'll be able to:

• Take full advantage of the Heap API to track custom events and manage user identity.
• Automatically capture a wide variety of user interactions in your application with no additional code required.

📘

If you're using Heap Classic and thinking of switching to our latest offerings, check out the full breakdown of the differences between our SDKs here.

Before you begin

📘

The below guide assumes a standard <project>/<app> configuration and use of the most up-to-date Gradle syntax. If you're using the legacy Gradle syntax in your project, visit our custom configuration guide here.

All of our Android SDKs are distributed via Maven Central. To make sure your application can access the required artifacts, you will need to add Maven Central as a repository for both Gradle plugins and dependencies.

In your project-level settings.gradle file, add a reference to Maven Central:

pluginManagement {  
  repositories {  
    ...  
    mavenCentral()  
  }  
}

dependencyResolutionManagement {  
  repositories {  
    ...  
    mavenCentral()  
  }  
}

pluginManagement {  
  repositories {  
    ...  
    mavenCentral()  
  }  
}

dependencyResolutionManagement {  
  repositories {  
    ...  
    mavenCentral()  
  }  
}

Add the SDK to your application

👍

Unified SDK

These instructions install our new Unified SDK which includes product analytics powered by Heap and digital experience analytics powered by Contentsquare.

1. In your app-level build.gradle file, add the dependency for the Contentsquare Unified SDK and the Heap Compose Autocapture SDK.

dependencies {  
  implementation 'com.contentsquare.android:sdk:0.3.0'
  implementation 'io.heap.autocapture:heap-autocapture-compose:0.7.3'
}

dependencies {  
  implementation("com.contentsquare.android:sdk:0.3.0")
  implementation("io.heap.autocapture:heap-autocapture-compose:0.7.3")
}

2. Also in your app-level build.gradle file, add the Heap Gradle Plugin. This must come after the Android application plugin.

plugins {  
    id 'com.android.application'  
    ...  
    id 'io.heap.gradle' version '0.5.+'  
}

plugins {  
    id("com.android.application")
    ...  
    id("io.heap.gradle") version "0.5.+"
}

3. Once the dependencies and the plugin have been added, sync Gradle and rebuild your application.

4. To enable Heap and start automatically tracking supported user interactions, register the autocapture SDKs and call startRecording. This can go anywhere in your app, but we recommend doing this in the onCreate method of your app’s Application object to make sure tracking starts before the first UI element is shown.

import io.heap.autocapture.ViewAutocaptureSDK  
import io.heap.autocapture.compose.ComposeAutocaptureSDK
import io.heap.core.Heap

class MyApplication : Application() {  
  override fun onCreate() {  
    super.onCreate()  
    // Replace YOUR_ENVIRONMENT_ID with the ID of the Heap environment you wish to send data to.  
    Heap.startRecording(this, "YOUR_ENVIRONMENT_ID")  
    // Call ViewAutocaptureSDK.register() to enable autocapture for supported UI elements and pageviews.  
    ViewAutocaptureSDK.register()  
    // Call ComposeAutocaptureSDK.register to enable autocapture for Compose UI elements.
    ComposeAutocaptureSDK.register()
  }  
}

import io.heap.autocapture.ViewAutocaptureSDK;
import io.heap.autocapture.compose.ComposeAutocaptureSDK;
import io.heap.core.Heap;

public class MyApplication extends Application {  
  @Override
	public void onCreate() {  
    super.onCreate();
    // Replace YOUR_ENVIRONMENT_ID with the ID of the Heap environment you wish to send data to.  
    Heap.startRecording(this, "YOUR_ENVIRONMENT_ID");  
    // Call ViewAutocaptureSDK.register() to enable autocapture for supported UI elements.  
    ViewAutocaptureSDK.register();  
    // Call ComposeAutocaptureSDK.register to enable autocapture for Compose UI elements.
    ComposeAutocaptureSDK.register();
  }  
}

Once recording has started, you’re able to take full advantage of Heap’s API to identify users, track custom events, and more. Heap will also automatically start tracking a wide range of user interactions in your app, as well as tracking activity and fragment visibility changes and app version changes without any additional code.

What next?

To find out how to take full advantage of the Heap API to enhance your data capture, check out our mobile tracking guides here.

If you want to learn how Heap auto-captures data in the Android View framework, and how you can enhance your autocapture experience with minor updates to your code, check out our autocapture guide here.