Android

Use this guide for complete steps to install Heap on Android. For a guide that covers both iOS and Android, see our mobile installation guide.

IMPORTANT

In the instructions below, remember to replace your app ID with the ID of the environment to which you want to send data. You can find this ID within your Account Settings under the Projects tab.

Android Gradle Plugin 3.5 + Android Studio

There is a known issue with building apps integrated with Heap using AGP 3.5 and Android Studio. As a workaround, builds will still function properly via the command-line. We plan to address this in a very near-term release, but in the meantime recommend that developers build from the command-line or remain on AGP 3.4.

Installation

Our Android integration works by inserting itself as a step in the app compilation process, and modifies the code before the app ships. Please review the following list of requirements and known limitations to ensure your project is set up for this installation process.

Requirements and Known Limitations

  • You'll need to be using Android Studio.
  • The integration only works with Gradle. Gradle is the build system that is used for Android
  • The build plugin only works on macOS and Linux.
  • The build plugin requires a system-level Python installation. This will be available on macOS by default, though it may need to be installed separately on Linux. Either Python 2 or 3 will work.
  • The integration does not support React Native.
  • The build plugin supports versions 3.0.x, 3.1.x, 3.2.1+, and 3.3.x of the Android Gradle plugin. AGP 2.x support has been deprecated.
  • The integration supports Android build tool version 24.0.3+ except for version 26.0.0 (26.0.1+ is fine).
  • The integration currently only captures sessions, screenviews, and clicks/taps.
  • When developing apps with Instant Run, Heap will only record sessions and screenviews—interaction events like taps will not be captured. To test interaction event capture during development, you should disable Instant Run.

Installation Instructions

The following instructions should support any Android app, though we assume a project structure with two build.gradle files, one at the root level and one in the same folder as the app's code.

  1. Create a new test environment in Heap and note the environment ID for initial Android testing. You're welcome to use your existing development environment, though we recommend a fresh environment for ease of testing iterations.
  2. In build.gradle at the root level of your project, modify the buildscript section as follows:
buildscript {
  // At the top of the buildscript block, add a property for the SDK version.
  ext.heapVersion = '1.2.0'
  // ...

  dependencies {
    // Within buildscript.dependencies, add the classpath dependency below.
    // Note the double quotes, which are required to interpolate the version.
    classpath "com.heapanalytics.android:heap-android-gradle:${heapVersion}"
  }
}
  1. Modify the app’s build.gradle, within whichever folder your app code lives (for example, /app/build.gradle):

    • Apply the Heap build plugin after the Android plugin:
apply plugin: 'com.android.application'
// Insert line below to apply our plugin
apply plugin: 'com.heapanalytics.android'
  • Add the client library as a dependency:
dependencies {
  // Insert line below to include our client library as a dependency. Note the
  // double quotes, which are required to interpolate the version.
  implementation "com.heapanalytics.android:heap-android-client:${heapVersion}"

  // If you are on an older version of the Gradle build plugin (pre-3.1) you should
  // use the commented line below instead of the one above. The "compile" directive
  // is deprecated as of 3.1.
  // compile "com.heapanalytics.android:heap-android-client:${heapVersion}"
  // ...
}

Initializing the Heap app

There are two ways to initialize the Heap app: via auto-init configs in build.gradle at build-time or using the client SDK at runtime. It is generally recommended to use the build-time auto-init method, but the SDK method is useful for programmatically specifying the Heap app ID.

Auto-init at Build-time

In the app's build.gradle file, add the following to the defaultConfig section:

android {
    defaultConfig {
        // Add this section to enable Heap event capture.
        ext {
          heapEnabled = true
          heapAutoInit = true
          heapEnvId = "<your-env-id>"
        }
        // ...
    }
    // ...
}

SDK Initialization at Runtime

In the app's build.gradle file, add the following to the defaultConfig section:

android {
    defaultConfig {
        // Add this section to enable Heap event capture.
        ext {
          heapEnabled = true
        }
        // ...
    }
    // ...
}

Modify the onCreate method of your app's entry point, either an Application subclass or the activity with the android.intent.action.MAIN action in its intent filter:

// Include this import line up top
import com.heapanalytics.android.Heap;
// ...

class MyMainActivity extends BaseActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // Insert line below replacing "MY ENV ID" with your Heap environment ID
    Heap.init(getApplicationContext(), "MY ENV ID");
    // ...
}

Completing Heap Setup

  1. Add internet permission for the app so it can send data to Heap's servers. In the manifest, add:
    <uses-permission android:name="android.permission.INTERNET" />
  2. Launch the application in the emulator or on a device. To see interaction events while developing, you must disable Instant Run.
  3. Data should be sent to Heap upon interactions! After a few minutes, navigate to Heap's users view to see your recent data and validate that event data is being sent properly.

Review our java documentation in our API docs to learn how to identify your users or send custom events and properties to Heap.

Licenses

  • To print license information included in the Heap Gradle plugin, please run gradlew tasks and refer to the "Heap tasks" section.

Sensitive Data

In Android, layouts can be declared either through XML at development time or through programmatic instantiation at runtime. Heap provides two mechanisms for ignoring text from layout elements for each of these definition mechanisms.

In Layout XML, you can add heapIgnore as a View tag, either via the attribute:


<!-- Interactions with this button are ignored by Heap. -->
<Button
    android:id="@+id/my_secret_button"
    android:tag="heapIgnore"
    android:text="@string/my_secret_button_text" />
    
<!-- All interactions in this subtree are ignored by Heap. -->
<LinearLayout
    android:id="@+id/my_secret_container"
    android:tag="heapIgnore">
</LinearLayout>

or via a tag element:


<!-- Interactions with this button are ignored by Heap. -->
<Button
    android:id="@+id/my_secret_button"
    android:text="@string/my_secret_button_text">
    <tag android:id="@id/heapIgnore" android:value="true" />
</Button>
    
<!-- All interactions in this subtree are ignored by Heap. -->
<LinearLayout
    android:id="@+id/my_secret_container"
    android:tag="heapIgnore">
    <tag android:id="@id/heapIgnore" android:value="true" />    
</LinearLayout>

When defining the layout programmatically, at runtime, you can call Heap.ignore(View) to ignore a view and its subtree. For example, in order to ignore only interactions with a button within a layout:


LinearLayout mySecretContainer = new LinearLayout(this);
LayoutParams layoutParams = new LayoutParams(LayoutParams.MATCH_PARENT, 
                                             LayoutParams.MATCH_PARENT); 

Button mySecretButton = new Button(this);
mySecretButton.setText("My Secret Button Text");
mySecretContainer.addView(mySecretButton, layoutParams);

// Ignore all interactions with mySecretButton
Heap.ignore(mySecretButton);

setContentView(mySecretContainer, layoutParams);

If you need to ignore interactions from a larger ViewGroup, you can do so by ignoring the view container:


LinearLayout mySecretContainer = new LinearLayout(this);
LayoutParams layoutParams = new LayoutParams(LayoutParams.MATCH_PARENT, 
                                             LayoutParams.MATCH_PARENT); 

Button mySecretButton = new Button(this);
mySecretButton.setText("My Secret Button Text");
mySecretContainer.addView(mySecretButton, layoutParams);

// Ignore all interactions with mySecretContainer, implicitly ignores
// interactions with mySecretButton
Heap.ignore(mySecretContainer);

setContentView(mySecretContainer, layoutParams);

IMPORTANT: There are certain situations in which getParent() may return null for a View. In these cases, Heap will not be able to ignore events for a View in the ignored subtree. Due to this caveat, it is a best practice for Heap.ignore() to be scoped as closely to the PII-containing View as possible.

Tracker Tech Specs

  • SDK size: Our SDK library is approximately 900 KB.
  • Cross-platform testing: We require API level 14, which is Android 4.0 / Ice Cream Sandwich. Additionally, we require that the minSdkVersion is not higher than 23, which is Android 6.0 / Marshmallow. This doesn’t prevent you from targeting higher versions if you need to.
  • Network impact: Events are batched and sent to our servers every 15 seconds. If no network connection is present, events are cached locally. Data will not be sent when the app is not being used. All data are sent to heapanalytics.com. Each interaction with your app will generate an event to be sent to Heap. A typical event on Android is around 0.5 kB.
  • Performance: Heap adds virtually zero performance overhead. Heap will never block the UI thread, and RAM is allocated only to process events before they are persisted (or while sending them to our servers). While we do a very small amount of view traversal on the UI thread for each event to fetch the properties from the UI objects, no disk or network IO happens on the UI thread. All blocking work of persisting data and sending data to Heap is all on background threads, and is primarily waiting on disk or network IO, and has very low CPU usage.
  • Storage: The data is stored in a SQLite database until it is successfully sent. Its size is a little larger than the aggregate sizes of all the events it stores. While online, this database should stay under a few hundred KiB. While offline, it will grow with the number of events stored. If we overestimate events at 1KiB each, this should be about a megabyte per 1k events.

Changelog

For notable updates to the Heap Android library, see the Android Changelog.

Android


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.