Once signed up, set up an Android source in the dashboard. You should be able to see a Write Key for this source, as shown below:
You will also need a data plane URL. Refer to the Glossary for more information on the data plane URL and where to find it.
The Setup tab in the RudderStack dashboard (seen above) has an SDK installation snippet containing both the write key and the data plane URL. You can use it to integrate the Android SDK into your project.
Installing the SDK
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:
implementation'com.rudderstack.android.sdk:core:1.7+'// add the following line if you don't have Gson included already
implementation'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.
Using the Android SDK on applications with 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:
privatefuntlsBackport(){try{ProviderInstaller.installIfNeeded(this)Log.e("Rudder","Play present")valsslContext:SSLContext=SSLContext.getInstance("TLSv1.2")sslContext.init(null,null,null)sslContext.createSSLEngine()}catch(e:GooglePlayServicesRepairableException){// Prompt the user to install/update/enable Google Play services.
GoogleApiAvailability.getInstance().showErrorNotification(this,e.connectionStatusCode)Log.e("Rudder","Play install")}catch(e:GooglePlayServicesNotAvailableException){// Indicates a non-recoverable error: let the user know.
Log.e("SecurityException","Google Play Services not available.");e.printStackTrace()}}
Finally, call the tlsBackport() function at the very beginning of your onCreate() method in MainActivity.
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
Import the library on the classes you desire to use RudderClient library
importcom.rudderstack.android.sdk.core.*;
Add the following code to the onCreate method in your Application class:
You can disable these events using the withTrackLifecycleEvents method and passing false. But it is highly recommended to keep them enabled.
Enabling/disabling user tracking via the optOut API (GDPR Support)
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:
rudderClient.optOut(true)
rudderClient.optOut(true);
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:
rudderClient.optOut(false)
rudderClient.optOut(false);
The optOut API is available in the RudderStack Android SDK from version 1.0.21.
Chromecast
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.
Track
You can record the users’ activity through the track method. Every user action is called an event.
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.
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.
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.
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.
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",newRudderTraits().putAge("24").putName("Test Group Name").putPhone("1234567891"));
Follow the method signatures below:
Name
Data Type
Required
Description
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.
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
Name
Data Type
Required
Description
newId
String
Yes
The new userId you want to assign to the user
options
RudderOption
No
Event level option
RudderStack replaces 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:
Parameter
Type
Description
Default value
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
autoSessionTracking
Boolean
Determines if the SDK automatically tracks the user sessions. Refer to Tracking user sessions for more information.
true
sessionTimeout
Integer
Maximum inactivity period before the session expires.
300000 ms (5 minutes)
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
Change this parameter only if you are self-hosting the control plane. Check the Self-hosted control plane section below for more information. The SDK will add /sourceConfig along with this URL to fetch the source configuration.
https://api.rudderlabs.com
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 the steps in this section 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.
Setting the 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.putDeviceToken("your_device_token")
RudderClient.putDeviceToken("your_device_token");
Setting the advertisement ID
By default, RudderStack collects the advertisement ID only if the following three conditions are met:
com.google.android.gms.ads.identifier.AdvertisingIdClient is present in your application’s class path.
limitAdTrackingis not enabled for your device.
To set your own advertisement ID, you can use the putAdvertisingId method:
RudderClient.putAdvertisingId(<ADVERTISING_ID>);
RudderStack sets gaid under context.device.advertisementId.
Anonymous 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.
An example of setting the anonymousId is shown below:
RudderClient.putAnonymousId(<ANONYMOUS_ID>);
To retrieve the anonymousId, you can use the following method:
RudderClient.getAnonymousId();
The method getAnonymousId is available from v1.0.11 onwards.
Filtering events
When sending events to a destination via device mode, you can explicitly specify which events should be discarded or allowed to flow through - by allowlisting or denylisting them.
The RudderStack Android SDK allows you to enable or disable event flow to a specific destination or all destinations to which the source is connected. You can specify these destinations by creating a RudderOption object as shown:
valoption=RudderOption()//default value for `All` is true
option.putIntegration("All",false)// specifying destination by its display name
option.putIntegration("Google Analytics",true)option.putIntegration(<DESTINATIONDISPLAYNAME>,<boolean>)// specifying destination by its Factory object
option.putIntegration(AppcenterIntegrationFactory.FACTORY,true);option.putIntegration(<RudderIntegration.FACTORY>,<boolean>);
RudderOptionoption=newRudderOption();// default value for `All` is true
option.putIntegration("All",false);// specifying destination by its display name
option.putIntegration("Google Analytics",true);option.putIntegration(<DESTINATIONDISPLAYNAME>,<boolean>);// specifying destination by its Factory object
option.putIntegration(AppcenterIntegrationFactory.FACTORY,true);option.putIntegration(<RudderIntegration.FACTORY>,<boolean>);
The keyword All in the above snippet represents all 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:
Pass destinations while initializing the SDK
This is helpful when you want to enable/disable sending the events across all event calls made using the SDK to the specified destination(s).
varrudderClient=RudderClient.getInstance(this,<write_key>,RudderConfig.Builder().withDataPlaneUrl(<data_plane_url>).withLogLevel(RudderLogger.RudderLogLevel.DEBUG).withTrackLifecycleEvents(false).withRecordScreenViews(false).build(),option// passing the rudderoption object containing the list of destination(s) you specified
)
RudderClientclient=RudderClient.getInstance(this,<write_key>,newRudderConfig.Builder().withEndPointUri(<end_point_url>).build(),option// passing the rudderoption object containing the list of destination(s) you specified
);
Pass destinations while making event calls
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.
rudderClient.track("Product Added",RudderProperty().putValue("product_id","product_001"),option// passing the rudderoption object containing the list of destination you specified
)
rudderClient.track("Product Added",newRudderProperty().putValue("product_id","product_001"),option// passing the rudderoption object containing the list of destination(s) you specified
);
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.
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.
By default, the Android SDK automatically tracks the user sessions. This means that RudderStack automatically determines the start and end of a user session depending on the inactivity time configured in the SDK (default time is 5 minutes).
To automatically track sessions in the Android SDK, withTrackLifecycleEvents should also be set to true. This is because RudderStack considers the Application Opened, Application Installed, or Application Updated events as the start of a new session.
valrudderClient=RudderClient.getInstance(this,WRITE_KEY,RudderConfig.Builder().withDataPlaneUrl(DATA_PLANE_URL).withAutoSessionTracking(true)// Set to false to disable automatic session tracking
.withSessionTimeoutMillis(5*60*1000).build())
RudderClientrudderClient=RudderClient.getInstance(this,WRITE_KEY,newRudderConfig.Builder().withDataPlaneUrl(DATA_PLANE_URL).withAutoSessionTracking(true)// Set to false to disable automatic session tracking
.withSessionTimeoutMillis(5*60*1000).build());
To disable automatic session tracking, set withAutoSessionTracking to false.
For more information on the user sessions and how to track them using the Android SDK, refer to the Session Tracking guide.
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:
importandroidx.annotation.NonNull;importandroidx.annotation.Nullable;importcom.rudderstack.android.sdk.core.RudderClient;importcom.rudderstack.android.sdk.core.RudderConfig;importcom.rudderstack.android.sdk.core.RudderIntegration;importcom.rudderstack.android.sdk.core.RudderLogger;importcom.rudderstack.android.sdk.core.RudderMessage;publicclassCustomFactoryextendsRudderIntegration<CustomFactory>{privatestaticfinalStringFACTORY_KEY="Custom Factory";publicstaticFactoryFACTORY=newFactory(){@OverridepublicRudderIntegration<?>create(Objectsettings,RudderClientclient,RudderConfigrudderConfig){returnnewCustomFactory(client,rudderConfig);}@OverridepublicStringkey(){returnFACTORY_KEY;}};privateCustomFactory(@NonNullRudderClientclient,RudderConfigconfig){}privatevoidprocessRudderEvent(RudderMessageelement){System.out.println("Processing RudderEvent of type "+element.getType());}@Overridepublicvoidreset(){System.out.println("Reset is called");}@Overridepublicvoidflush(){System.out.println("Flush is called");}@Overridepublicvoiddump(@NullableRudderMessageelement){try{if(element!=null){processRudderEvent(element);}}catch(Exceptione){RudderLogger.logError(e);}}@OverridepublicCustomFactorygetUnderlyingInstance(){returnthis;}}
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:
rudderClient.flush()
rudderClient.flush();
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:
Can I disable event tracking until the user gives their consent?
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:
rudderClient.optOut(true)
Once the user gives their consent, you can enable user tracking again:
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.
How does the SDK handle different client/server errors?
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).
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.