The RudderStack Android SDK allows you to track event data from your app. It can be easily integrated into your Android application. After integrating this SDK, you will also be able to send the event data to your preferred analytics destination/s such as Google Analytics, Amplitude, and more.
You can check the GitHub codebase if you want to get more hands-on or keen to know the SDK architecture.
To set up the RudderStack Android SDK, there are a few prerequisites as mentioned below:
You will need to set up a RudderStack Account.
Once signed up, your Android
source writeKey
will appear in the Dashboard, as shown:
You will also need your Data Plane URL. Simply put, the Data Plane URL is used to connect to the RudderStack backend for processing and routing your events.
To get the Data Plane URL:
If you're using the open-source version of RudderStack, you are required to set up your own data plane by installing and setting up RudderStack in your preferred dev environment.
If you're using the enterprise version of RudderStack, please contact us for the data plane URL with the email ID used to sign up for RudderStack.
You will also need to install Android Studio on your system.
We distribute our Android SDK through Bintray. This is the recommended way to use our SDK is through the Android Gradle build system. It's the easiest way to add the SDK to your project.
To add the dependencies, perform the following steps:
Open your app/build.gradle (Module: app)
file, and add the following lines of code:
repositories {maven { url "https://dl.bintray.com/rudderstack/rudderstack" }}
Add the dependency under dependencies
as shown:
implementation 'com.rudderstack.android.sdk:core:1+'// add the follwing line if you don't have Gson included alreadyimplementation 'com.google.code.gson:gson:2+'
It is recommended to use the Core Android SDK without any device-mode
destination SDKs as you will have a better view on the captured data from the SDK.
Add this line to your AndroidManifest.xml
file of your application for internet
permission:
<uses-permission android:name="android.permission.INTERNET"/>
We also declare android.permission.BLUETOOTH
and android.permission.ACCESS_WIFI_STATE
as optional by mentioning required="false"
. If we get these permissions, we'll capture the Bluetooth status and the WiFi status of the device and pass it under context.network
.
Import the library on the classes you desire to use RudderClient
library
import com.rudderstack.android.sdk.core.*;
Add the following code to the onCreate
method in your Application
class:
Don't have an Application
class? Follow our guide on Adding an Application Class to Your Android Application to add one.
val rudderClient = RudderClient.getInstance(this,WRITE_KEY,RudderConfig.Builder().withDataPlaneUrl(DATA_PLANE_URL).withTrackLifecycleEvents(true).withRecordScreenViews(true).build())
RudderClient rudderClient = RudderClient.getInstance(this,WRITE_KEY,new RudderConfig.Builder().withEndPointUri(DATA_PLANE_URL).withTrackLifecycleEvents(true).withRecordScreenViews(true).build());
We automatically track the following optional events:
Application Installed
Application Updated
Application Opened
Application Backgrounded
You can disable these events using the withTrackLifecycleEvents
method and passing false
. But it is highly recommended to keep them enabled.
You can record the users' activity through the track
method. Every action performed by the user is called an event.
An example of the track
event is as shown:
rudderClient.track("Product Added",RudderProperty().putValue("product_id", "product_001"))
rudderClient.track("Product Added",new RudderProperty().putValue("product_id", "product_001"));
Follow the method signature as below:
Name | Data Type | Required | Description |
|
| Yes | Name of the event you want to track |
|
| No | Extra data properties you want to send along with the event |
|
| No | Extra event options |
We capture deviceId
and use that as anonymousId
for identifying the user. It helps to track the users across the application installation. To attach more information to the user, you can use the identify
method. Once you set the identify
information to the user, those will be passed to the successive track
or screen
calls. To reset the user identification, you can use the reset
method.
On the Android devices, the deviceId
is assigned during the first boot. It remains consistent across the applications and installs. It changes only after factory reset.
An example identify
event is as shown:
val traits = RudderTraits()traits.putBirthday(Date())traits.putEmail("abc@123.com")traits.putFirstName("First")traits.putLastName("Last")traits.putGender("m")traits.putPhone("5555555555")val address = RudderTraits.Address()address.putCity("City")address.putCountry("USA")traits.putAddress(address)traits.put("boolean", Boolean.TRUE)traits.put("integer", 50)traits.put("float", 120.4f)traits.put("long", 1234L)traits.put("string", "hello")traits.put("date", Date(System.currentTimeMillis()))rudderClient.identify("test_user_id", traits, null)
RudderTraits traits = new RudderTraits();traits.putBirthday(new Date());traits.putEmail("abc@123.com");traits.putFirstName("First");traits.putLastName("Last");traits.putGender("m");traits.putPhone("5555555555");RudderTraits.Address address = new RudderTraits.Address();address.putCity("City");address.putCountry("USA");traits.putAddress(address);traits.put("boolean", Boolean.TRUE);traits.put("integer", 50);traits.put("float", 120.4f);traits.put("long", 1234L);traits.put("string", "hello");traits.put("date", new Date(System.currentTimeMillis()));rudderClient.identify("test_user_id", traits, null);
Follow the method signatures below:
Name | Data Type | Required | Description |
|
| Yes | Traits information for the user |
|
| No | Extra options for the |
OR
Name | Data Type | Required | Description |
|
| Yes | Developer identity for the user |
|
| No | Traits information for user |
|
| No | Extra options for the |
You can use the screen
call to record whenever the user sees a screen on the mobile device. You can also send some extra properties along with this event.
An example of the screen
event is as shown:
rudderClient.screen("MainActivity","HomeScreen",RudderProperty().putValue("foo", "bar"),null)
rudderClient.screen("MainActivity","HomeScreen",new RudderProperty().putValue("foo", "bar"),null);
Follow the method signature below:
Name | Data Type | Required | Description |
|
| Yes | Name of the screen viewed. |
|
| No | Category of the screen visited, such as |
|
| No | Extra property object that you want to pass along with the |
|
| No | Extra options to be passed along with |
The group
call associates a user to a specific organization. A sample group
call for the API is below:
rudderClient.group("sample_group_id",RudderTraits().putAge("24").putName("Test Group Name").putPhone("1234567891"))
rudderClient.group("sample_group_id",new RudderTraits().putAge("24").putName("Test Group Name").putPhone("1234567891"));
Follow the method signatures below:
Name | Data Type | Required | Description |
|
| Yes | An ID of the organization with which you want to associate your user |
|
| No | Any other property of the organization you want to pass along with the call |
|
| No | Event level options |
We don't persist the traits for the group across the sessions
The alias
call associates the user with a new identification. A sample alias
call for the API is below:
rudderClient.alias("test_new_id")
rudderClient.alias("test_new_id");
Alternatively, you can use the following method signature
Name | Data Type | Required | Description |
|
| Yes | The new |
|
| No | Event level option |
We replace the old userId
with the newUserId
and we persist that identification across the sessions.
You can use the reset
method to clear the persisted traits
for the identify
call. This is required for Logout
operations.
rudderClient.reset()
rudderClient.reset();
You can configure your client based on the following parameters using RudderConfig.Builder
:
Parameter | Type | Description | Default Value |
|
| Controls how much of the log you want to see from the SDK. |
|
|
| URL of your | |
|
| Number of events in a batch request to the server. |
|
|
| Number of events to be saved in the |
|
|
| Minimum waiting time to flush the events to the server. |
|
|
| It will fetch the config from |
|
|
| Whether SDK will capture application life cycle events automatically. |
|
|
| Whether SDK will capture screen view events automatically. |
|
|
| This parameter should be changed only if you are self-hosting the Control Plane. Check the section Self-Hosted Control Plane below for more information. The SDK will add |
If you are using a device mode destination like Adjust, Firebase, etc., the Android SDK needs to fetch the required configuration from the Control Plane. If you are using the RudderStack Config Generator to host your own Control Plane, then follow this guide and specify controlPlaneUrl
in yourRudderConfig.Builder
that points to your hosted source configuration file.
You shouldn't pass the controlPlaneUrl
parameter during SDK initialization if you are using the dashboard from https://app.rudderstack.com. This parameter is supported only if you are using our open-source RudderStack Config Generator.
You can set your device-token
for push notification to be sent to the destinations that support Push Notification. We set the token
under context.device.token
.
Follow the code snippets below:
rudderClient.putDeviceToken("your_device_token")
rudderClient.putDeviceToken("your_device_token");
We collect the advertisementId
if it is enabled by the user and the App has the Google Play services Ads SDK embedded in the application. We set the gaid
under context.device.advertisementId
.
Apart from it, if you want to set the advertisingId
by yourself, you can do so using the updateWithAdvertisingId
method and passing the advertisingId
.
You need to call updateWithAdvertisingId
method before calling getInstance
An example of setting the advertisingId
is as below
RudderClient.updateWithAdvertisingId(<ADVERTISING_ID>);
We use the deviceId
as anonymousId
by default. You can use the following method to override and use your own anonymousId
with the SDK.
You need to call setAnonymousId
method before calling getInstance
An example of setting the anonymousId
is as below
RudderClient.setAnonymousId(<ANONYMOUS_ID>);
You can pass your custom userId
along with standard userId
in your identify
calls. We add those values under context.externalId
. The following code snippet shows a way to add externalId
to your identify
request.
rudderClient.identify("sampleUserId",RudderTraits().putFirstName("First Name"),RudderOption().putExternalId("brazeExternalId", "some_external_id"))
If you run into any issues regarding the RudderStack Android SDK, you can turn on the VERBOSE
or DEBUG
logging to find out what the issue is. To turn on the logging, change your RudderClient
initialization to the following:
val rudderClient: RudderClient = RudderClient.getInstance(this,YOUR_WRITE_KEY,RudderConfig.Builder().withDataPlaneUrl(DATA_PLANE_URL).withLogLevel(RudderLogger.RudderLogLevel.DEBUG).build())
RudderClient rudderClient = RudderClient.getInstance(this,YOUR_WRITE_KEY,new RudderConfig.Builder().withEndPointUri(DATA_PLANE_URL).withLogLevel(RudderLogger.RudderLogLevel.DEBUG).build());
If you are facing any issue regarding even delivery in production environment, add the following line in your progaurd rule.
-keep class com.rudderstack.android.** { *; }
We currently support API 14: Android 4.0 (IceCreamSandwich)
or higher.
Please follow our guide on How to Add an Application Class to Your Android App to add an Application
class.
Please refer to the Setting the Android Permission section above to do this.
Yes, you can use the library with maven
.
<dependency><groupId>com.rudderstack.android.sdk</groupId><artifactId>core</artifactId><version>latest_version</version><type>pom</type></dependency>
You can try searching in the Logcat using the following command once you set the logLevel
to VERBOSE
adb logcat -s RudderSDK:V \-v tag -e "EventRepository: dump: message:"
In case of any queries, you can always contact us, or open an issue on our GitHub Issues page in case of any discrepancy.