Michael Evans

A bunch of technobabble.

Understanding Referrals Using Google Play

| Comments

Tracking how users install your app can be tricky, especially when you want to measure the effectiveness of your campaigns or ads. That’s where the Google Play Install Referrer API comes in handy—it gives you reliable data about how users found your app.

If you’re developing an Android application, this guide will walk you through how to set up and use the InstallReferrerClient with Kotlin’s callbackFlow to make integration simpler and more maintainable.

What is the Install Referrer?

The install referrer contains information about the source of the app installation. For example, if a user clicks an ad campaign link that leads to your app’s Play Store page, the referrer might include details about the campaign source, medium, or other specifics.

Here’s how this data can help:

  • Attribution: Identify which campaigns drive installs.
  • Measure Success: Evaluate your marketing efforts’ impact.
  • Prevent Fraud: Verify referrer data to avoid fraudulent installs.

Setting Up and Using the InstallReferrerClient

Step 1: Add the Dependency

First, include the Install Referrer library in your build.gradle file:

1

implementation 'com.android.installreferrer:installreferrer:2.2'

Step 2: Use callbackFlow for our implementation

The InstallReferrerClient is callback-based, but Kotlin’s callbackFlow lets you handle this more elegantly. Here’s an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

import com.android.installreferrer.api.InstallReferrerClient
import com.android.installreferrer.api.InstallReferrerStateListener
import com.android.installreferrer.api.ReferrerDetails
import kotlinx.coroutines.channels.awaitClose
import kotlinx.coroutines.flow.callbackFlow

fun fetchInstallReferrer(context: Context) = callbackFlow {
    val referrerClient = InstallReferrerClient.newBuilder(context).build()

    val listener = object : InstallReferrerStateListener {
        override fun onInstallReferrerSetupFinished(responseCode: Int) {
            when (responseCode) {
                InstallReferrerClient.InstallReferrerResponse.OK -> {
                    try {
                        val response: ReferrerDetails = referrerClient.installReferrer
                        trySend(Result.success(response))
                    } catch (e: Exception) {
                        trySend(Result.failure(e))
                    } finally {
                        referrerClient.endConnection()
                    }
                }
                InstallReferrerClient.InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> {
                    trySend(Result.failure(UnsupportedOperationException("Feature not supported")))
                }
                InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE -> {
                    trySend(Result.failure(IllegalStateException("Service unavailable")))
                }
            }
        }

        override fun onInstallReferrerServiceDisconnected() {
            // Handle service disconnection if needed
        }
    }

    referrerClient.startConnection(listener)

    awaitClose {
        referrerClient.endConnection()
    }
}

Step 3: Consuming the Flow

Collect the flow to retrieve and process the install referrer details:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

fetchInstallReferrer(context).collect { result ->
        result.onSuccess { referrerDetails ->
            val referrerUrl = referrerDetails.installReferrer
            val clickTimestamp = referrerDetails.referrerClickTimestampSeconds
            val installTimestamp = referrerDetails.installBeginTimestampSeconds

            println("Referrer URL: $referrerUrl")
            println("Click Time: $clickTimestamp")
            println("Install Time: $installTimestamp")
        }

        result.onFailure { exception ->
            println("Error: ${exception.message}")
        }
    }

Wrapping Up

With this data, you’ll gain valuable insights into your app’s install sources, helping you make data-driven marketing decisions. Happy coding!

Comments