Track install referrer details entity along with the application install event if available (close #249)

snowplow-demo-kotlin/build.gradle

@@ -41,4 +41,5 @@ dependencies {
     implementation 'androidx.preference:preference:1.2.0'
     implementation 'androidx.browser:browser:1.5.0'
     implementation 'com.google.android.gms:play-services-appset:16.0.2'
+    implementation "com.android.installreferrer:installreferrer:2.2"
 }

snowplow-tracker/src/androidTest/java/com/snowplowanalytics/snowplow/event/ApplicationInstallEventTest.kt

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2015-2023 Snowplow Analytics Ltd. All rights reserved.
+ *
+ * This program is licensed to you under the Apache License Version 2.0,
+ * and you may not use this file except in compliance with the Apache License Version 2.0.
+ * You may obtain a copy of the Apache License Version 2.0 at http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the Apache License Version 2.0 is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
+ */
+package com.snowplowanalytics.snowplow.event
+
+import android.content.Context
+import androidx.preference.PreferenceManager
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import com.snowplowanalytics.snowplow.Snowplow.createTracker
+import com.snowplowanalytics.snowplow.configuration.*
+import com.snowplowanalytics.snowplow.controller.TrackerController
+import com.snowplowanalytics.snowplow.network.HttpMethod
+import com.snowplowanalytics.snowplow.tracker.MockNetworkConnection
+import org.junit.Assert
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(AndroidJUnit4::class)
+class ApplicationInstallEventTest {
+
+    @Before
+    fun setUp() {
+        cleanSharedPreferences()
+    }
+
+    // Tests
+    @Test
+    fun testTracksInstallEventOnFirstLaunch() {
+        // plugin to check if event was tracked
+        var eventTracked = false
+        val plugin = PluginConfiguration("testPlugin")
+        plugin.afterTrack { eventTracked = true }
+
+        // create tracker with install autotracking
+        val trackerConfiguration = TrackerConfiguration("appId")
+            .installAutotracking(true)
+        createTracker(listOf(trackerConfiguration, plugin))
+
+        Thread.sleep(500)
+
+        // check if event was tracked
+        Assert.assertTrue(eventTracked)
+    }
+
+    @Test
+    fun testDoesntTrackInstallEventIfPreviouslyTracked() {
+        // plugin to check if event was tracked
+        var eventTracked = false
+        val plugin = PluginConfiguration("testPlugin")
+        plugin.afterTrack { eventTracked = true }
+
+        // create tracker with install autotracking
+        val trackerConfiguration = TrackerConfiguration("appId")
+            .installAutotracking(true)
+        createTracker(listOf(trackerConfiguration, plugin))
+
+        Thread.sleep(500)
+
+        // check if event was tracked
+        Assert.assertTrue(eventTracked)
+
+        // reset flag
+        eventTracked = false
+
+        // create tracker again
+        createTracker(listOf(trackerConfiguration, plugin))
+
+        Thread.sleep(500)
+
+        // check if event was tracked
+        Assert.assertFalse(eventTracked)
+    }
+
+    private fun cleanSharedPreferences() {
+        val sharedPreferences = PreferenceManager.getDefaultSharedPreferences(context)
+        sharedPreferences.edit().clear().commit()
+    }
+
+    private fun createTracker(configurations: List<Configuration>): TrackerController {
+        val networkConfig = NetworkConfiguration(MockNetworkConnection(HttpMethod.POST, 200))
+        return createTracker(
+            context,
+            namespace = "ns" + Math.random().toString(),
+            network = networkConfig,
+            configurations = configurations.toTypedArray()
+        )
+    }
+
+    private val context: Context
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+}

snowplow-tracker/src/main/java/com/snowplowanalytics/core/tracker/ApplicationInstallEvent.kt

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2015-2023 Snowplow Analytics Ltd. All rights reserved.
+ *
+ * This program is licensed to you under the Apache License Version 2.0,
+ * and you may not use this file except in compliance with the Apache License Version 2.0.
+ * You may obtain a copy of the Apache License Version 2.0 at http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the Apache License Version 2.0 is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
+ */
+package com.snowplowanalytics.core.tracker
+
+import android.content.Context
+import androidx.preference.PreferenceManager
+import com.snowplowanalytics.core.constants.TrackerConstants
+import com.snowplowanalytics.core.emitter.Executor
+import com.snowplowanalytics.core.utils.NotificationCenter.postNotification
+import com.snowplowanalytics.snowplow.event.AbstractSelfDescribing
+import java.util.*
+
+/**
+ * An event tracked on the first launch of the app in case install autotracking is enabled.
+ * It is accompanied by an install referrer entity (`InstallReferrerDetails`) if available.
+ */
+class ApplicationInstallEvent : AbstractSelfDescribing() {
+
+    override val schema: String
+        get() = TrackerConstants.SCHEMA_APPLICATION_INSTALL
+
+    override val dataPayload: Map<String, Any?>
+        get() = emptyMap()
+
+    companion object {
+        private val TAG = ApplicationInstallEvent::class.java.simpleName
+
+        /**
+         * Asynchronous function that tracks an `application_install` event if it wasn't tracked yet.
+         * @param context the Android context
+         */
+        fun trackIfFirstLaunch(context: Context) {
+            Executor.execute(TAG) {
+                if (isNewInstall(context)) {
+                    sendInstallEvent(context)
+                }
+            }
+        }
+
+        private fun isNewInstall(context: Context): Boolean {
+            val sharedPreferences = PreferenceManager.getDefaultSharedPreferences(context)
+            // if the value was missing in sharedPreferences, we're assuming this is a new install
+            return sharedPreferences.getString(TrackerConstants.INSTALLED_BEFORE, null) == null;
+        }
+
+        private fun sendInstallEvent(context: Context) {
+            val event = ApplicationInstallEvent()
+
+            // add install referrer entity if available
+            InstallReferrerDetails.fetch(context) { referrer ->
+                referrer?.let { event.entities.add(it) }
+
+                val notificationData: MutableMap<String, Any> = HashMap()
+                notificationData["event"] = event
+                postNotification("SnowplowInstallTracking", notificationData)
+
+                saveInstallTrackedInfo(context)
+            }
+        }
+
+        /**
+         * Save install event tracked info to shared preferences
+         */
+        private fun saveInstallTrackedInfo(context: Context) {
+            val sharedPreferences = PreferenceManager.getDefaultSharedPreferences(context)
+            val editor = sharedPreferences.edit()
+            editor?.putString(TrackerConstants.INSTALLED_BEFORE, "YES")
+            editor?.apply()
+        }
+    }
+}

snowplow-tracker/src/main/java/com/snowplowanalytics/core/tracker/InstallReferrerDetails.kt

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2015-2023 Snowplow Analytics Ltd. All rights reserved.
+ *
+ * This program is licensed to you under the Apache License Version 2.0,
+ * and you may not use this file except in compliance with the Apache License Version 2.0.
+ * You may obtain a copy of the Apache License Version 2.0 at http://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the Apache License Version 2.0 is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
+ */
+
+package com.snowplowanalytics.core.tracker
+
+import android.content.Context
+import android.os.RemoteException
+import com.android.installreferrer.api.InstallReferrerClient
+import com.android.installreferrer.api.InstallReferrerStateListener
+import com.android.installreferrer.api.InstallReferrerClient.InstallReferrerResponse
+import com.android.installreferrer.api.ReferrerDetails
+import com.snowplowanalytics.core.utils.Util
+import com.snowplowanalytics.snowplow.payload.SelfDescribingJson
+
+/**
+ * Entity tracked along with the `application_install` event to give information about the Play Store referrer.
+ * Only tracked in case `com.android.installreferrer` package is added to app dependencies.
+ * 
+ * Schema: iglu:com.android.installreferrer.api/referrer_details/jsonschema/1-0-0
+ *
+ * @param installReferrer The referrer URL of the installed package
+ * @param referrerClickTimestamp The timestamp when referrer click happens
+ * @param installBeginTimestamp The timestamp when the app installation began
+ * @param googlePlayInstantParam Boolean indicating if the user has interacted with the app's instant experience in the past 7 days
+ */
+class InstallReferrerDetails(
+    installReferrer: String,
+    referrerClickTimestamp: Long,
+    installBeginTimestamp: Long,
+    googlePlayInstantParam: Boolean
+) : SelfDescribingJson(
+    "iglu:com.android.installreferrer.api/referrer_details/jsonschema/1-0-0",
+    mapOf(
+        "installReferrer" to installReferrer,
+        "referrerClickTimestamp" to if (referrerClickTimestamp > 0) { Util.getDateTimeFromTimestamp(referrerClickTimestamp) } else { null },
+        "installBeginTimestamp" to if (installBeginTimestamp > 0) { Util.getDateTimeFromTimestamp(installBeginTimestamp) } else { null },
+        "googlePlayInstantParam" to googlePlayInstantParam,
+    )
+) {
+    companion object {
+        private val TAG = InstallReferrerDetails::class.java.simpleName
+
+        fun fetch(context: Context, callback: (installReferrer: InstallReferrerDetails?) -> Unit) {
+            if (!isInstallReferrerPackageAvailable()) {
+                callback(null)
+                return
+            }
+
+            val referrerClient = InstallReferrerClient.newBuilder(context).build()
+            referrerClient.startConnection(object : InstallReferrerStateListener {
+
+                override fun onInstallReferrerSetupFinished(responseCode: Int) {
+                    when (responseCode) {
+                        InstallReferrerResponse.OK -> {
+                            // Connection established.
+                            try {
+                                val response: ReferrerDetails = referrerClient.installReferrer
+                                val referrer = InstallReferrerDetails(
+                                    installReferrer = response.installReferrer,
+                                    referrerClickTimestamp = response.referrerClickTimestampSeconds,
+                                    installBeginTimestamp = response.installBeginTimestampSeconds,
+                                    googlePlayInstantParam = response.googlePlayInstantParam
+                                )
+                                callback(referrer)
+                            } catch (_: RemoteException) {
+                                Logger.d(TAG, "Install referrer API remote exception.")
+                                callback(null)
+                            }
+                        }
+                        InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> {
+                            Logger.d(
+                                TAG,
+                                "Install referrer API not available on the current Play Store app."
+                            )
+                            callback(null)
+                        }
+                        InstallReferrerResponse.SERVICE_UNAVAILABLE -> {
+                            Logger.d(
+                                TAG,
+                                "Install referrer API connection couldn't be established."
+                            )
+                            callback(null)
+                        }
+                    }
+                }
+
+                override fun onInstallReferrerServiceDisconnected() {
+                }
+            })
+        }
+
+        fun isInstallReferrerPackageAvailable(): Boolean {
+            try {
+                Class.forName("com.android.installreferrer.api.InstallReferrerStateListener")
+                return true
+            } catch (_: Exception) {
+            }
+            return false
+        }
+    }
+}