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.