# Android SDK ### 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 — `` * **Maven coordinates (release publication):** `com.github.chartbeat:android_sdk:` *** ### Installation #### 1. Add the JitPack repository **Gradle (Groovy) — root** `build.gradle`: ```java allprojects { repositories { google() mavenCentral() maven { url 'https://jitpack.io' } } } ``` **Gradle (Kotlin DSL) —** `settings.gradle.kts`: ```java dependencyResolutionManagement { repositories { google() mavenCentral() maven { url = uri("https://jitpack.io") } } } ``` #### 2. Add the dependency Use a version tag from [jitpack.io/#chartbeat/android\_sdk](https://jitpack.io/#chartbeat/android_sdk): ```java 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**: ```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:** ```java 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()`: ```java @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. ```java @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. ```java @Override public void onUserInteraction() { super.onUserInteraction(); Tracker.userInteracted(); } ``` ### Usage Guide #### Author/Section Set metadata **after** trackView(), because view changes purge metadata. ```java Tracker.setAuthors(Arrays.asList("Jane Doe", "John Smith")); Tracker.setSections(Arrays.asList("technology", "news")); ``` #### Push referrers ```java 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. ```java Tracker.setPosition(scrollPositionTop, scrollWindowHeight, totalContentHeight, fullyRenderedDocWidth); ``` #### User subscriber status Set the [Subscriber Status](https://docs.chartbeat.com/cbp/tracking/standard-websites/subscriber-engagement) of the user. ```java 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](https://app.gitbook.com/o/-LYD2YiRqOYWSR79uOpv/s/-LYD2YiVXfNNRnSgJXb4/~/diff/~/changes/484/tracking/mobile-app-sdks/android-sdk#initialize-the-tracker), add `true` as the last variable in the `Tracker.setupTracker()` function: **Java:** {% code overflow="wrap" %} ```java @Override public void onCreate() { String chartbeatAccountId = "12345"; String chartbeatSiteId = "mysite.com"; super.onCreate(); Tracker.setupTracker(chartbeatAccountId, chartbeatSiteId, this, true); ``` {% endcode %} *** ### 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: ```java -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**](/cbp/tracking/mobile-app-sdks/qa-mobile-sdk-integration.md) if your team will not implement tracking for an iOS app. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.chartbeat.com/cbp/tracking/mobile-app-sdks/android-sdk.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.