Edit me

Getting Started with MetaRouter - Android

Using our analytics-android library, you can start sending customer data from your app to MetaRouter, giving you valuable user data that yields actionable insights for your business. Follow the instructions below to get started in only a few minutes.

Create an Android Source in the MetaRouter UI

After logging in with your MetaRouter credentials, add a new Source → Android. Give your source a friendly name and copy that Source ID for the next step.

Install the SDK

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 {
  compile 'io.astronomer.analytics.android:analytics:4.+'
}

Initialize the Client

We recommend initializing the client in your Application subclass.

// Create an analytics client with the given context and MetaRouter Source ID.
Analytics analytics = new Analytics.Builder(context, YOUR_SOURCE_ID)
  .trackApplicationLifecycleEvents() // Enable this to record certain application events automatically!
  .recordScreenViews() // Enable this to record screen views automatically!
  .endpoint("https://e.metarouter.io") // Required - Specify that events go to the 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 recommending doing so to ensure you get the most out of MetaRouter!
  • This only installs the MetaRouter destination, meaning all your data will be sent server side to tools.

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

Identify Your Users

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:

Analytics.with(context).identify("123456", new Traits().putName("Dagny Smith").putEmail("dagny@metarouter.io").putRole("buyer"));

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 Your Users’ Actions

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.

Analytics analytics = new 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:

 Analytics.with(context).track("Signed up", new 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:

Analytics.with(context).track("Viewed Product", new Properties()
  .putValue("item", "Cat Feather Toy")
  .putValue("category", "Pet Supplies")
  .putValue("revenue", "9.99"));

You have now successfully implemented your Android app! Now you’re ready to head back to the MetaRouter UI and start switching on some destinations.