What is the RudderStack Android SDK?

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.

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:

• You will also need your Data-plane URL. The following screenshot shows the data plane URL for the managed hosting mode:

• You will also need to install Android Studio on your system.

Installing the SDK

We distribute our Android SDK through Bintray. This is 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:

• 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.0.2-patch.5'
// add the follwing line if you don't have Gson included already
implementation 'com.google.code.gson:gson:2.8.6'

Setting Android Permission

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.

Initializing the RudderStack Client

Add the following code to the onCreate method in your Application class:

val rudderClient = RudderClient.getInstance(
    this,
    <YOUR_WRITE_KEY>,
    RudderConfig.Builder()
        .withDataPlaneUrl(<DATA_PLANE_URL>)
        .withLogLevel(RudderLogger.RudderLogLevel.DEBUG)
        .withTrackLifecycleEvents(true)
        .withRecordScreenViews(true)
        .build()
)

RudderClient rudderClient = RudderClient.getInstance(
        this,
        <YOUR_WRITE_KEY>,
        new RudderConfig.Builder()
                .withEndPointUri(<DATA_PLANE_URL>)
                .withLogLevel(RudderLogger.RudderLogLevel.DEBUG)
                .withTrackLifecycleEvents(true)
                .withRecordScreenViews(true)
                .build()
);

Track

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(
  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()
)

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:

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

2. Alternatively, you can follow the method signature as below:

Identify

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:

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

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

Alternatively, you can follow the method signatures below:

OR

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:

rudderClient.screen(
    "MainActivity",
    "HomeScreen",
    RudderProperty().putValue("foo", "bar"),
    null
)

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 property in RudderMessage, and use the screen method to track a screen view action.

Alternatively, you can use the following method signature:

Group

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")
);

Alternatively you can use the following method signature

We don't persist the traits for the group across the sessions.

Alias

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

We replace the old userId with the newUserId and we persist that identification across the sessions.

Reset

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();

Configuring your RudderStack Client

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

Setting Android Device Token

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!!.rudderContext.putDeviceToken("your_device_token")

rudderClient.getRudderContext().putDeviceToken("your_device_token")

Advertisement ID

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.

External 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_1")
)

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:

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()
);

FAQs

Do I need to add anything to my progaurd-rules?

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.** { *; }

What is the 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 guide on How to Add an Application Class to Your Android App 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>

How do I check whether a specific event is getting fired or not?

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:"

Contact us

In case of any queries, you can always reach out to us, or feel free to open an issue on our GitHub Issues page in case of any discrepancy.

​