Android
Detailed technical documentation on RudderStack’s Android SDK using Android Studio to send events from your Android device to various destinations.
Last updated
Was this helpful?
Detailed technical documentation on RudderStack’s Android SDK using Android Studio to send events from your Android device to various destinations.
Last updated
Was this helpful?
The RudderStack Android SDK lets you track event data from your Android applications and send it to your specified destinations via RudderStack.
You can check the GitHub codebase to get more a hands-on understanding of the SDK and its architecture.
To set up the RudderStack Android SDK, the following prerequisites must be met:
You will need to set up a RudderStack account.
Once signed up, set up an Android source in the dashboard. For more information, follow this guide. You should then see a Write Key for this source, as shown below:
You will also need a data plane URL. Follow this section for more information on the data plane URL and where to get it.
Finally, you will also need to install Android Studio on your system.
As Bintray has sunset from 1st May, we're moving the Android SDK to Maven Central. All the versions from 1.0.10 are available in Maven Central only.
We distribute the Android SDK through Maven Central. The recommended and easiest way to add the SDK to your project is through the Android Gradle build system.
Follow these steps:
Open your project level build.gradle
file, and add the following lines of code:
Then open your app/build.gradle
and add the dependency under dependencies
as shown below:
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.
minSDKVersion
less than 20
By default, the Android SDK does not support applications with minSDKVersion
less than 20
. You can add this support by following the steps below:
Add the following dependency to the build.gradle
file of your application:
Add the function tlsBackport()
in your MainActivity
as shown:
Finally, call the tlsBackport()
function at the very beginning of your onCreate()
method in MainActivity
.
For more details, refer to this Android documentation.
Add this line to your AndroidManifest.xml
file of your application for internet
permission:
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
Add the following code to the onCreate
method in your Application
class:
Follow our guide on Adding an Application Class to Your Android Application for more information.
Kotlin JAVA
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.
RudderStack gives the users (e.g., an EU user) the ability to opt out of tracking any user activity until the user gives their consent. You can do this by leveraging RudderStack's optOut
API.
The optOut
API takes true
or false
as a Boolean value to enable or disable tracking user activities. This flag persists across device reboots.
The following snippet highlights the use of the optOut
API to disable user tracking:
Kotlin JAVA
Once the user grants their consent, you can enable user tracking once again by using the optOut
API with false
as a parameter sent to it, as shown:
Kotlin JAVA
The optOut
API is available in the RudderStack Android SDK from version 1.0.21
.
Google Chromecast is a device that plugs into your TV or monitor with an HDMI port, and can be used to stream content from your phone or computer.
RudderStack supports integrating the Android SDK with your Cast app. Follow these instructions to build your Android sender app. Then, add the Android SDK to it.
Follow the Google Cast developer guide for more details.
You can record the users' activity through the track
method. Every user action is called an event.
A sample track
event is as shown below:
Kotlin JAVA
Follow the method signature as below:
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
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 sample identify
event is as shown:
Kotlin JAVA
Follow the method signatures below:
traits
RudderTraits
Yes
Traits information for the user
options
RudderOption
No
Extra options for the identify
event
OR
userId
String
Yes
Developer identity for the user
traits
RudderTraits
No
Traits information for user
option
RudderOption
No
Extra options for the identify
event
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
Follow the method signature below:
screenName
String
Yes
Name of the screen viewed.
category
String
No
Category of the screen visited, such as HomeScreen
, LoginScreen
. Useful for tracking multiple Fragment
views under a single Activity
.
property
RudderProperty
No
Extra property object that you want to pass along with the screen
call.
option
RudderOption
No
Extra options to be passed along with screen
event.
The group
call associates a user to a specific organization. A sample group
call for the API is below:
Kotlin JAVA
Follow the method signatures below:
groupId
String
Yes
An ID of the organization with which you want to associate your user
traits
RudderTraits
No
Any other property of the organization you want to pass along with the call
options
RudderOption
No
Event level options
RudderStack doesn'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:
Kotlin JAVA
Alternatively, you can use the following method signature
newId
String
Yes
The new userId
you want to assign to the user
options
RudderOption
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.
Kotlin JAVA
You can configure your client based on the following parameters using RudderConfig.Builder
:
logLevel
Integer
Controls how much of the log you want to see from the SDK.
RudderLogger.RudderLogLevel.NONE
dataPlaneUrl
String
Your data plane URL.
https://hosted.rudderlabs.com
flushQueueSize
Integer
Number of events in a batch request to the RudderStack server.
30
dbThresholdCount
Integer
Number of events to be saved in the SQLite
database. Once the limit is reached, older events are deleted from the database.
10000
sleepcount
Integer
Minimum waiting time to flush the events to the RudderStack server. The minimum value can be set to 1 second
.
10 seconds
configRefreshInterval
Integer
The SDK will fetch the config from dashboard
after the specified time
2 hours
trackLifecycleEvents
Boolean
Determines if the SDK will automatically capture the application lifecycle events.
true
recordScreenViews
Boolean
Determines if the SDK will automatically capture the screen view events.
false
autoCollectAdvertId
Boolean
Determines if the SDK will collect the advertisement ID.
false
controlPlaneUrl
String
A sample code snippet to configure your client using RudderConfig.Builder
is shown below:
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 Control Plane Lite utility 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 RudderStack Cloud Dashboard. This parameter is supported only if you are using our open-source Control Plane Lite to self-host your Control Plane.
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:
Kotlin JAVA
By default, RudderStack collects the advertisement ID only if the following three conditions are met:
withAutoCollectAdvertId
is set to true
during the SDK initialization, as shown:
com.google.android.gms.ads.identifier.AdvertisingIdClient
is present in your application's class path.
limitAdTracking
is not enabled for your device.
To set your own advertisement ID, you can use the putAdvertisingId
method, as shown:
RudderStack sets gaid
under context.device.advertisementId
.
We use the deviceId
as anonymousId
by default. You can use the following method to override and use your own anonymousId
with the SDK.
An example of setting the anonymousId
is shown below:
To retrieve the anonymousId
, you can use the following method:
The method getAnonymousId
is available from v1.0.11 onwards.
When sending events to a destination via the device mode, you can explicitly specify which events should be discarded or allowed to flow through - by whitelisting or blacklisting them.
Refer to the Client-side Event Filtering guide for more information on this feature.
The RudderStack Android SDK allows you to enable or disable event flow to a specific destination or all the destinations to which the source is connected. You can specify these destinations by creating a RudderOption
object as shown:
Kotlin Java
The keyword All
in the above snippet represents all the destinations the source is connected to. Its value is set to true
by default.
Make sure the destination display name
that you pass while specifying the destinations should exactly match the destination name as shown here.
You can pass the destination(s) specified in the above snippet to the SDK in two ways:
This is helpful when you want to enable/disable sending the events across all the event calls made using the SDK to the specified destination(s).
Kotlin Java
This approach is helpful when you want to enable/disable sending only a particular event to the specified destination(s) or if you want to override the specified destinations passed with the SDK initialization for a particular event.
Kotlin Java
If you specify the destinations both while initializing the SDK as well as while making an event call, then the destinations specified at the event level only will be considered.
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.
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
You can easily develop a device mode destination in case RudderStack doesn't support it already, by following the steps listed in this section.
More information on the RudderStack device mode can be found in the RudderStack Connection Modes guide.
Create a CustomFactory
class by extending RudderIntegration.java
, as shown:
Some pointers to keep in mind:
You can use the constructor of the CustomFactory
class to initialize the native SDK of the Device Mode destination you are working on.
RudderStack's Android SDK dumps every event it receives to the dump()
method of the CustomFactory
class. From here, you can process the event and hand it over to the native SDK of the Device Mode destination.
The SDK also triggers the reset()
method of the CustomFactory
class on every reset()
call made via the SDK. You can use this to handle the destination-specific reset.
RudderStack's Android SDK also triggers the flush()
method of the CustomFactory
class on every flush()
call made via the SDK which you can use to handle the destination-specific reset logic. You can make a flush
call using the SDK as shown below:
Kotlin JAVA
Make sure you return a valid value from getUnderlyingInstance()
as it is used by the Android SDK to validate CustomFactory
.
Make sure you do not duplicate the value of FACTORY_KEY
across multiple CustomFactory
that you develop.
Register CustomFactory
with the RudderStack Android SDK during its initialization, as shown:
That's it! Your Device Mode destination is good to go.
If you are facing any issues regarding event delivery in a production environment, add the following line in your proguard rule:
We currently support API 14: Android 4.0 (IceCreamSandwich)
or higher.
Application
class to initialize my RudderStack client. What do I do?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
.
Using the following command in the Logcat tool once you set the logLevel
to VERBOSE
.
traits
after making the identify
call?You can get the user traits after making an identify
call as shown in the following snippet:
Kotlin JAVA
Yes, you can. RudderStack gives you the ability to disable tracking any user activity until the user gives their consent, by leveraging the optOut
API. This is required in cases where your app is audience-dependent (e.g. minors) or where you're using the app to track the user events (e.g. EU users) to meet the data protection and privacy regulations. The optOut
API takes true
or false
as a Boolean value to enable or disable tracking user activities. So, to disable user tracking, you can use the optOut
API as shown:
Once the user gives their consent, you can enable user tracking again, as shown:
For more information on the optOut
API, refer to the Enabling/Disabling User Tracking via optOut API section above.
You only need to call the optOut
API with the required parameter once, as the information persists within the device even if you reboot it.
In case of client-side errors, e.g. if the source write key passed to the SDK is incorrect, RudderStack gives you a 400 Bad Request response and aborts the operation immediately.
For other types of network errors (e.g. Invalid Data Plane URL), the SDK tries to flush the events to RudderStack in an incremental manner (every 1 second, 2 seconds, 3 seconds, and so on).
For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.
If you come across any issues while using the Android SDK, you can open a new issue on our GitHub Issues page.
Change this parameter only if you are self-hosting the control plane. Check the section below for more information. The SDK will add /sourceConfig
along with this URL to fetch the source configuration.