Android SDK

Instructions to integrate Chartbeat's Android SDK to your native app.

Overview

The Chartbeat Android SDK is a Java library that sends real-time engagement beacons ("pings") to Chartbeat so Android apps can be measured in the same dashboards as the publisher's web content. The entire public surface is exposed as static methods on the Tracker class.

• Package: com.chartbeat.androidsdk

• Main class: Tracker (all public methods are static)

• Distribution: JitPack — <https://jitpack.io/#chartbeat/android_sdk>

• Maven coordinates (release publication): com.github.chartbeat:android_sdk:<tag>

---

Installation

1. Add the JitPack repository

Gradle (Groovy) — root build.gradle:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

Gradle (Kotlin DSL) — settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

2. Add the dependency

Use a version tag from jitpack.io/#chartbeat/android_sdk:

dependencies {
    implementation 'com.github.chartbeat:android_sdk:1.8.0'
}

Getting Started

1. Initialize the tracker

Call Tracker.setupTracker(...) exactly once — typically in Application.onCreate() when the app is in the foreground. Subsequent calls are ignored.

Java:

@Override
public void onCreate() {
  String chartbeatAccountId = "12345";
  String chartbeatSiteId = "yoursite.com";
    
  super.onCreate();
  Tracker.setupTracker(chartbeatAccountId, chartbeatSiteId, this);
}

For example, this is the application-level Context.

Kotlin:

public class MyApp extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Tracker.setupTracker(
            "12345",               // accountId
            "yoursite.com",        // domain
            this,                  // Application context
            false                  // usePong — true to use the pong endpoint for IP truncation
        );
    }
}

Context rule: setupTracker requires an Application context. Passing an Activity throws IllegalArgumentException.

2. Track a view

Call Tracker.trackView in every screen's onCreate() or onResume():

@Override
protected void onResume() {
    super.onResume();
    Tracker.trackView(this, "/articles/hello-world", "Hello World");
}

3. Report that the user left the view

Call the userLeftView function (e.g. from your activities’ onPause functions) whenever the app leaves the foreground to stop the tracking for the current session.

@Override
protected void onPause() {
    super.onPause();
    Tracker.userLeftView("/articles/hello-world");
}

4. Track user interaction

Call the userInteracted function whenever the user interacts with your view to accurately measure user engagement with your content. Our recommendation is to call this from within the onUserInteraction function of your activity. Register writing engagement by calling the userTyped function whenever the user starts typing something.

@Override
public void onUserInteraction() {
    super.onUserInteraction();
    Tracker.userInteracted();
}

Usage Guide

Author/Section

Set metadata after trackView(), because view changes purge metadata.

Tracker.setAuthors(Arrays.asList("Jane Doe", "John Smith"));
Tracker.setSections(Arrays.asList("technology", "news"));

Push referrers

Tracker.setPushReferrer("push-campaign-42");        // URL-encoded, wrapped as push/?id=...

Scroll position

For scrollable views you aren't passing through trackView, call setPosition as the user scrolls. Negative values are not sent to the server.

Tracker.setPosition(scrollPositionTop, scrollWindowHeight,
                    totalContentHeight, fullyRenderedDocWidth);

User subscriber status

Set the Subscriber Status of the user.

Tracker.setUserPaid(); // for Subscriber
Tracker.setUserLoggedIn(); // for Registered
Tracker.setUserAnonymous(); // for Guest

IP Truncation

For clients in the EU, follow these steps to point traffic to our proxy layer that de-identifies IP addresses within the EU.When initializing the tracker, add true as the last variable in the Tracker.setupTracker() function:

Java:

@Override
public void onCreate() {
    String chartbeatAccountId = "12345";
    String chartbeatSiteId = "mysite.com";
    
    super.onCreate();
    Tracker.setupTracker(chartbeatAccountId, chartbeatSiteId, this, true);

---

ProGuard and R8

If you enable ProGuard or R8 in your release build, ensure the following rules are added to your proguard-rules.pro file to prevent issues with Retrofit and RxJava dependencies:

-dontwarn rx.**
-dontwarn retrofit2.**
-keep class retrofit2.** { *; }
-keep class rx.** { *; }
-keepattributes Signature, InnerClasses, EnclosingMethod

Next steps

Next up is our iOS SDK implementation steps, or skip to the integration QA article if your team will not implement tracking for an iOS app.