Android SDK
Please reach out to MetaRouter before testing or implementing Analytics.js for Android.
What is in this guide?
This guide will cover how to implement the Analytics Android SDK for MetaRouter and begin sending events from your Android app into your MetaRouter cluster.
Installing the SDK
Follow the below steps to install the Analytics SDK into your app.
We recommend installing the library for Android with a build system like Gradle to make upgrading versions and adding destinations simple. The library is distributed via Maven Central.
Just add the analytics
module to your build.gradle
with:
dependencies { implementation 'com.metarouter.analytics.android:analytics:4.+' }
Initialize the Client
We recommend initializing the client in your Application
subclass. We will provide the code instructions, but here are the general templates:
JAVA:
// Create an analytics client with the given context and MetaRouter writeKey.
Analytics analytics = new Analytics.Builder(context, YOUR_WRITEKEY)
.trackApplicationLifecycleEvents() // Enable this to record certain application events automatically!
.recordScreenViews() // Enable this to record screen views automatically!
.connectionFactory(new ConnectionFactory() {
@Override protected HttpURLConnection openConnection(String url) throws IOException {
Uri parsedUri = Uri.parse(url);
String path = parsedUri.getPath();
String host = parsedUri.getHost();
if (host.equals("cdn-settings.metarouter.io")) {
return super.openConnection("YOUR_CDN_URL" + path);
} else if (host.equals("api.metarouter.io")) {
return super.openConnection("YOUR_INGESTION_URL" + path);
}
return super.openConnection(url);
}
}) // Required - Specify that events go to your MetaRouter Event Ingestion API
.build();
// Set the initialized instance as a globally accessible instance.
Analytics.setSingletonInstance(analytics);
Kotlin:
// Create an analytics client with the given context and MetaRouter writeKey.
val analytics = Analytics.Builder(context, YOUR_WRITEKEY)
.trackApplicationLifecycleEvents() // Enable this to record certain application events automatically!
.recordScreenViews() // Enable this to record screen views automatically!
.connectionFactory(object : ConnectionFactory() {
@Throws(IOException::class)
override fun openConnection(url: String): HttpURLConnection {
val parsedUri = Uri.parse(url)
val path = parsedUri.path
val host = parsedUri.host
if (host == "cdn-settings.metarouter.io") {
return super.openConnection("YOUR_CDN_URL$path")
} else if (host == "api.metarouter.io") {
return super.openConnection("YOUR_INGESTION_URL$path")
}
return super.openConnection(url)
}
}) // Required - Specify that events go to your MetaRouter Event Ingestion API
.build()
// Set the initialized instance as a globally accessible instance.
Analytics.setSingletonInstance(analytics)
Notes:
- Automatically tracking lifecycle events (
Application Opened
,Application Installed
,Application Updated
) is optional, but we highly recommend doing so to ensure you get the most out of MetaRouter!
Add Permissions
Ensure that the necessary permissions are declared in your application's
AndroidManifest.xml.
<!-- Required for internet. -->
<uses-permission android:name="android.permission.INTERNET"/>
Required SDK Edits
In the above SDKs, there are three places where you will need to add information custom to your MetaRouter implementation. Instructions for setting up your DNS, which includes the CDN URL and Ingestion Endpoint that you will insert into your SDK setup, can be found here. Your writeKey will indicate the specific pipeline you would like to feed your events into.
Call Methods
Use these events to identify your users, track the actions they are taking in your app, and record information about the screen they are viewing.
Identify
The identify
method helps you associate your users and their actions to a unique and recognizable userID
and any optional traits
that you know about them. We recommend calling an identify
a single time - when the user's account is first created and only again when their traits change.
It's up to you to call identify
based on how your users are authenticated, but doing it in the onCreate
method of your Application class is the most common (as long as you know who your user is). IF your user is still anonymous, you should skip this step and we'll attribute the subsequent events to an anonymousID
instead.
For example, a simple identify
looks something like this:
JAVA:
Analytics.with(this).identify("123456", new Traits().putName("John Doe").putEmail("[email protected]"), null);
Kotlin:
Analytics.with(this).identify("123456", Traits().putName("John Doe").putEmail("[email protected]"), null)
This call is identifying a user by her unique userID
(from your database) and associating her with name
, email
, and role
traits.
Once you have the identify
call implemented, you're ready to move on to the track
call.
Track
To get to a more complete event tracking analytics setup, you can add a track
call to your app. This will tell MetaRouter which actions users are performing in your app. With track
, each user action triggers an “event”, which can also have associated properties.
To start, our SDK can automatically track a few common events (e.g. Application_Installed, Application_Opened, and Application_Updated) - you will just need to enable this option during initialization.
JAVA:
Analytics analytics = new Analytics.Builder(context, appID).trackApplicationLifecycleEvents().build();
Kotlin:
val analytics = Analytics.Builder(context, appID).trackApplicationLifecycleEvents().build()
In addition to these, you will likely want to track some events that are success indicators for your app - like Viewed Product, Email Sign Up, Item Purchased, etc. You can always add more of these later!
For example, here's a sample track
call that records when a user signs up:
JAVA:
Analytics.with(context).track("Signed up", new Properties().putValue("plan", "Enterprise"));
Kotlin:
Analytics.with(context).track("Signed up", Properties().putValue("plan", "Enterprise"))
This track
just tells us that your user just triggered the Signed Up event and chose your hypothetical ‘Enterprise’ plan. Properties are simple key-value pairs that can be anything you want to record, for example:
JAVA:
Analytics.with(context).track("Viewed Product", new Properties()
.putValue("item", "Cat Feather Toy")
.putValue("category", "Pet Supplies")
.putValue("revenue", "9.99"));
Kotlin:
Analytics.with(context).track("Viewed Product", Properties()
.putValue("item", "Cat Feather Toy")
.putValue("category", "Pet Supplies")
.putValue("revenue", "9.99"))
You have now successfully implemented your Android app! Continue on to our Integrations Guides to learn more about connecting your SDK to an integration.
Updated 8 months ago