Getting started with Android SDK

Detailed technical documentation on RudderStack’s Android SDK using Android Studio to send events from your Android device to various destinations.

What is the RudderStack Android SDK?

The RudderStack Android SDK can be easily integrated to your Android application in order to track event data from your app. After integrating this SDK, you will also be able to send this data to your preferred analytics destination/s such as Google Analytics, Amplitude, and more.

You can check the codebase if you want to get more hands on or keen to know the SDK architecture.

SDK Setup Requirements

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:

Android Source Write Key after adding the Source
  • You will also need your Data-plane URL. The following screenshot shows the data plane URL for the managed hosting mode:

Data Plane URL

Installing the SDK

We distribute our Android SDK through Bintray. The recommended way to use our SDK is through Android Gradle build system. It's the easiest way to add the SDK to your project.

To add the dependencies, perform the following steps:

  1. Open your app/build.gradle (Module: app) file, and add the following lines of code:

    repositories {
    maven {
    url "https://dl.bintray.com/rudderstack/rudderstack"
    }
    }
  2. Add the dependency under dependencies as shown:

    implementation 'com.rudderlabs.android.sdk:rudder-sdk-core:0.1.4'
    // add the follwing line if you don't have Gson included already
    implementation 'com.google.code.gson:gson:2.8.6'

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.

Initializing the RudderStack Client

Add the following to the onCreate method in your Application class.

Don't have an Application class? Follow our Add an Application class to your Android Application guide to add one.

Kotlin
JAVA
Kotlin
val rudderClient = RudderClient.getInstance(
this,
"YOUR_WRITE_KEY",
RudderConfig.Builder()
.withEndPointUri("YOUR_DATA_PLANE_URL")
.withLogLevel(RudderLogger.RudderLogLevel.DEBUG)
.withTrackLifecycleEvents(true)
.withRecordScreenViews(true)
.build()
)
JAVA
RudderClient rudderClient = RudderClient.getInstance(
this,
"YOUR_WRITE_KEY",
new RudderConfig.Builder()
.withEndPointUri("YOUR_DATA_PLANE_URL")
.withLogLevel(RudderLogger.RudderLogLevel.DEBUG)
.withTrackLifecycleEvents(true)
.withRecordScreenViews(true)
.build()
);

We automatically track the following optional events:

  1. Application Installed

  2. Application Updated

  3. Application Opened

  4. Application Backgrounded

You can disable these events using withTrackLifecycleEvents method and passing false. But it is highly recommended to keep them enabled.

Setting the Android Permission

Add this line to your AndroidManifest.xml file of your application for internet permission.

<uses-permission android:name="android.permission.INTERNET"/>

Track

You can record the users' activity through track method. Every action performed by the user is called an event.

An example track event is as shown:

Kotlin
JAVA
Kotlin
rudderClient.track(
RudderMessageBuilder()
.setEventName("test_track_event")
.setUserId("test_user_id")
.setProperty(mapOf(
"test_key_1" to "test_value_1",
"test_key_2" to mapOf(
"test_child_key_1" to "test_child_value_1"
)
))
.build()
)
JAVA
Map<String,Object> properties = new HashMap<>();
properties.put("test_key_1", "test_value_1");
Map<String, String> childProperties = new HashMap<>();
childProperties.put("test_child_key_1", "test_child_value_1");
properties.put("test_key_2", childProperties);
rudderClient.track(
new RudderMessageBuilder()
.setEventName("test_track_event")
.setUserId("test_user_id")
.setProperty(properties)
.build()
);

The track method can be used in two ways.

Firstly, you can use TrackPropertyBuilder to create the property object and pass the RudderMessage object with the property to track method.

Alternatively you can follow the method signature as below:

Name

Data Type

Required

Description

name

String

YES

Name of the event you want to track

property

RudderProperty or Map<String, Object>

NO

Extra data properties you want to send along with the event

options

RudderOption

NO

Extra event options

Identify

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.

An example identify event is as shown:

Kotlin
JAVA
Kotlin
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)
JAVA
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);

The identify method can be used in two ways. Firstly, you can use RudderTraitsBuilder to create the traits object and pass RudderMessage object with the property to the identify method.

Alternatively, you can follow the method signatures below:

Name

Data Type

Required

Description

traits

RudderTraits

YES

Traits information for the user

options

RudderOption

NO

Extra options for the identify event

OR

Name

Data Type

Required

Description

userId

String

YES

Developer identity for the user

traits

RudderTraits

NO

Traits information for user

option

RudderOption

NO

Extra options for identify event

Screen

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:

Kotlin
JAVA
Kotlin
rudderClient.screen(
"MainActivity",
"HomeScreen",
RudderProperty().putValue("foo", "bar"),
null
)
JAVA
rudderClient.screen(
"MainActivity",
"HomeScreen",
new RudderProperty().putValue("foo", "bar"),
null
);

The screen method can be used in two ways. Firstly, you can use ScreenPropertyBuilder and pass the property in the RudderMessage, and use the screen method to track a screen view action.

Alternatively, you can use the following method signature:

Name

Data Type

Required

Description

screenName

String

YES

Name of the screen viewed

property

RudderProperty

NO

Extra property object that you want to pass along with the screen call

category

String

NO

Category of the screen visited, such as HomeScreen, LoginScreen. Useful for tracking multiple Fragment views under a single Activity

option

RudderOption

NO

Extra options to be passed along with screen event

Reset

You can use the reset method to clear the persisted traits for the identify call. This is required for Logout operations.

Kotlin
JAVA
Kotlin
rudderClient.reset()
JAVA
rudderClient.reset();

Configuring your RudderStack Client

You can configure your client based on the following parameters using RudderConfig.Builder

Parameter

Type

Description

Default Value

logLevel

int

Controls how much of the log you want to see from the SDK.

RudderLogger.RudderLogLevel.NONE

endPointUri

String

URL of your data-plane. Please refer above to see how to fetch the data plane URL.

https://api.rudderlabs.com

flushQueueSize

int

Number of events in a batch request to the server

30

dbThresholdCount

int

Number of events to be saved in the SQLite database. Once the limit is reached, older events are deleted from the DB

10000

sleepTimeout

int

Minimum waiting time to flush the events to the server.

10 seconds

configRefreshInterval

int

It will fetch the config from dashboard after this many hours

2

trackLifecycleEvents

boolean

Whether SDK will capture Application Life Cycle Events automatically.

true

recordScreenViews

boolean

Whether SDK will capture Screen View events automatically.

false

Debugging

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:

Kotlin
Java
Kotlin
val rudderClient: RudderClient = RudderClient.getInstance(
this,
WRITE_KEY,
RudderConfig.Builder()
.withEndPointUri(YOUR_DATA_PLANE_URL)
.withLogLevel(RudderLogger.RudderLogLevel.DEBUG)
.build()
)
Java
RudderClient rudderClient = RudderClient.getInstance(
this,
WRITE_KEY,
new RudderConfig.Builder()
.withEndPointUri(YOUR_DATA_PLANE_URL)
.withLogLevel(RudderLogger.RudderLogLevel.DEBUG)
.build()
);

FAQ

What is the minimum Android version required to set up the RudderStack Android SDK?

We currently support API 14: Android 4.0 (IceCreamSandwich) or higher.

I don't have an Application class to initialize my RudderStack client. What do I do?

Please follow our Adding an Application class to your Android Application guide to add an Application class.

How do I set the Android permissions?

Please refer to the Setting the Android Permission section above to do this.

Can I use the library with Maven?

Yes, you can use the library with maven.

<dependency>
<groupId>com.rudderlabs.android.sdk</groupId>
<artifactId>rudder-sdk-core</artifactId>
<version>0.1.4</version>
<type>pom</type>
</dependency>

Contact Us

In case of any queries, you can always reach out to us, or feel free to open an issue here in case of any discrepancy.