Integration with Android

Android is the most used mobile platform in the world. We are very happy to having an official integration library for Android. If you are looking for React Native please check React Native and for other mobile integrations (iOS and others) please check mobile integration docs. If you are with Android, you are in the right place. Let's start!

Installation

Installation with Gradle

Step 1. Add the JitPack repository to your build file

Add `maven { url 'https://jitpack.io' }` it in your root build.gradle at the end of repositories:

gradle

        dependencyResolutionManagement {
          repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
          repositories {
            mavenCentral()
            maven { url 'https://jitpack.io' }
          }
        }
        

Step 2. Add the dependency to your app dependencies:

gradle

        dependencies {
	        implementation 'com.github.metricalp:android:1.3'
	}
        

Installation with Maven

Step 1. Add the JitPack repository to your build file

gradle

      <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
      </repositories>
        

Step 2. Add the dependency to your app dependencies:

gradle

    <dependency>
        <groupId>com.github.metricalp</groupId>
        <artifactId>android</artifactId>
        <version>1.3</version>
    </dependency>
        

Usage

We tried to make integration flexible and smooth to keep developer experience in best level. Here we will share a complete MainActivity.kt example to show how you can integrate Metricalp to your Android app. We will describe the code step by step as detailed below.

kotlin
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.Button
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import com.metricalp.android.Metricalp
import com.myapp.test.ui.theme.TestappTheme

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Metricalp.init(hashMapOf<String, String>("tid" to "mam48", "app" to "ExampleApp@1.0.0", "metr_user_language" to "English-US", "metr_unique_identifier" to "<GENEREATED_UUID>"), null)
        setContent {
            TestappTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    RenderButton()
                }
            }
        }
    }

    public override fun onStart() {
        super.onStart()
        Metricalp.screenViewEvent("MainScreen", null, null);
    }

    public override fun onStop() {
        super.onStop()
        Metricalp.sessionExitEvent("MainScreen", null, null);
    }
}

@Composable
fun RenderButton() {
    Button(onClick = { Metricalp.customEvent("button_click", hashMapOf<String, String>("path" to "HomepageScreen", "custom_prop1" to "top_button", "theme" to "dark"), null ) }) { Text("Button") }
}
        

We know it is a very ugly app but it will help to get it fundamentals, trust us. Firstly, we imported import com.metricalp.android.Metricalp library which we call methods through it.

The first method to call is Metricalp.init and the most important one is to properly integrate. We will init Metricalp to collect events. It is important to do this in entrypoint file (MainActivity). Metricalp.init takes attributes (HashMap<String,String>), initial screen path (for auto triggered first screen_view as optional). If provide initial screen as null, then it will skip auto triggered first screen_view event. Let's explain:

Metricalp.init() Attributes Argument Props

app

You should provide your app name and version. It is important to provide version to track it in dashboard. You can provide it as AppName@Version syntax ExampleApp@1.0.0 like above example.

metr_user_language

You should provide your current app language. You can provide it as Language (long name)-Country(ISO Code) syntax English-US like above example or Spanish-ES orTurkish-TR etc. If you are not sure about country, you can provide unknown. For example English-unknown

metr_unique_identifier

We need to explain this metr_unique_identifier prop. Normally in Web tracking, while Metricalp is not using cookies as we mentioned in many places, we are identifying users with their IP addresses in one-way hashes. The formula is something like this: hash(user_ip + user_agent + daily_salt). Here ip + user_agent is almost unique for every user. But in mobile apps, user agent strings are inconsistent and not reliable. So we need to have a unique identifier for every user. We left this unique identifier to you. You can use any unique identifier for your app. For example if it is an authorization app and you are tracking only after users logged-in, then you can provide user ids. Or you can use device related real unique identifiers (Android and iOS has some native methods to get it). Or, you can generate a random UUID when user first opens the app and store it in local storage. Then use it as metr_unique_identifier. Now, the hashing algorithm will be like hash(user_ip + metr_unique_identifier + daily_salt). In this approach, the metr_unique_identifier will be unchanged unless user removes and re-installs the app. But that is fair enough. If it is not enough for you, you can provide your own unique identifier as we mentioned above. User ID or device identifier or any other combination. If you just want to use IP then just pass empty string '' as metr_unique_identifier. But, we strongly suggest to use a unique identifier for better tracking. metr_unique_identifier is optional but suggested.

metr_bypass_ip

This is an optional prop. If you see above final hash example with metr_unique_identifier: hash(user_ip + metr_unique_identifier + daily_salt), we still have IP in hash function. So, when user for example in Wifi and then changed to mobile network, then IP will be changed. While metr_unique_identifier is same, because of IP change, it will count as another unique count for that day. But, you can by pass this IP uniqueness with this prop. If you set this as "true" (* a string not boolean), then we will not use IP in hash function: hash(metr_unique_identifier + daily_salt). It is again optional but if you provided metr_unique_identifier we are suggesting setting it true for better tracking. If you did not provide metr_unique_identifier, then you can not set this setting to "true".

tid (required)

You should provide your TID (a.k.a Tracking ID) to init method. You can get it from Metricalp dashboard. It is required. If you don't provide it, you will get an error. You can find your tid in Embed & Share Tracker page.

There are two important system events in Metricalp screen_view and session_exit. We are tracking visited screens, screen durations, bounce rates etc based on these events. So, we strongly suggesting that you should trigger these events in your app additional to any custom events. In your navigation logic, on every screen change by user you should trigger a screen_view event. When user leaves application (move to background or a complete exit) you should trigger a session_exit event. In above example, we are listening onStart and onStop changes by Android and triggering these events. You can use any other library or method to listen these events. You can also use any other method to trigger these events. But, you should trigger these events for better tracking.

kotlin
      ...
      ...
      public override fun onStart() {
          super.onStart()
          Metricalp.screenViewEvent("MainScreen", null, null);
      }
  
      public override fun onStop() {
          super.onStop()
          Metricalp.sessionExitEvent("MainScreen", null, null);
      }
      ...
      ...

Metricalp.screenViewEvent and Metricalp.sessionExitEvent methods provided by library to make it easier for you. You should provide current screen name (path) to these methods. You can also pass any additional data (custom props) to these methods as second argument (again HashMap<String,String>). The third argument is another HashMap if you wish override initial props (settings) for current event otherwise just pass null.

kotlin
Metricalp.screenViewEvent("MainScreen", hashMapOf<String, String>("custom_prop1" to "Unauthenticated User"), null);

or

kotlin
Metricalp.screenViewEvent("MainScreen", hashMapOf<String, String>("theme" to "Dark Theme"), null);

Here the theme is a custom prop alias. You can check Custom Event & Props docs for detailed info.

Basically that is all. You successfully integrated your Android app with Metricalp now. One more thing is, you can also create some custom events to get more deep insights.

Custom Events

There is also another method from library for custom events: Metricalp.customEvent. It takes event type as first argument and data attributes as second argument. The third argument is another HashMap if you wish override initial props (settings) for current event otherwise just pass null. You can use it like:

kotlin
Metricalp.customEvent("button_click", hashMapOf<String, String>("path" to "HomepageScreen", "custom_prop1" to "top_button", "theme" to "dark"), null )

Here we passed path info, also we passed top_button info as custom_prop. We passed another custom prop theme but we used alias this time. You can check Custom Event & Props for detailed info. Now with power of custom events and props you can track and analyze any event to get deep insights in your Android app easily.