Merge pull request #76 from TelemetryDeck/feat/add-acquisition-helpers

Add acquisition helper methods

Author: kkostov

README.md

@@ -15,6 +15,7 @@ This package allows you to send signals to [TelemetryDeck](https://telemetrydeck
 * [Default Parameters](#default-parameters)
 * [Default Prefix](#default-prefix)
 * [Navigation Signals](#navigation-signals)
+* [Acquisition](#acquisition)
 * [Custom Telemetry](#custom-telemetry)
 * [Custom Logging](#custom-logging)
 * [Requirements](#requirements)
@@ -248,6 +249,33 @@ TelemetryDeck.navigate("/onboarding")
 TelemetryDeck.navigate("/home")
 ```
 
+
+## Acquisition
+
+The following helper methods are available
+
+```kotlin
+/**
+ * Send a `TelemetryDeck.Acquisition.userAcquired` signal with the provided channel.
+ */
+fun acquiredUser(channel: String,...)
+```
+
+```kotlin
+/**
+ * Send a `TelemetryDeck.Acquisition.leadStarted` signal with the provided leadId.
+ */
+fun leadStarted(leadId: String,...)
+```
+
+```kotlin
+/**
+ * Send a `TelemetryDeck.Acquisition.leadConverted` signal with the provided leadId.
+ */
+fun leadConverted(leadId: String,...)
+```
+
+
 ## Custom Telemetry
 
 Another way to send signals is to implement a custom `TelemetryDeckProvider`.

lib/src/main/java/com/telemetrydeck/sdk/TelemetryDeck.kt

@@ -2,6 +2,7 @@ package com.telemetrydeck.sdk
 
 import android.content.Context
 import android.content.pm.ApplicationInfo
+import com.telemetrydeck.sdk.params.Acquisition
 import com.telemetrydeck.sdk.params.Navigation
 import com.telemetrydeck.sdk.providers.AccessibilityProvider
 import com.telemetrydeck.sdk.providers.DurationSignalTrackerProvider
@@ -61,6 +62,39 @@ class TelemetryDeck(
         navigate(navigationStatus.getLastDestination(), destinationPath, customUserID)
     }
 
+    override fun acquiredUser(channel: String, params: Map<String, String>, customUserID: String?) {
+        val signalParams = mergeMapsWithOverwrite(params, mapOf(
+            Acquisition.Channel.paramName to channel
+        ))
+        signal(
+            com.telemetrydeck.sdk.signals.Acquisition.UserAcquired.signalName,
+            params = signalParams,
+            customUserID = customUserID
+        )
+    }
+
+    override fun leadStarted(leadId: String, params: Map<String, String>, customUserID: String?) {
+        val signalParams = mergeMapsWithOverwrite(params, mapOf(
+            Acquisition.LeadId.paramName to leadId
+        ))
+        signal(
+            com.telemetrydeck.sdk.signals.Acquisition.LeadStarted.signalName,
+            params = signalParams,
+            customUserID = customUserID
+        )
+    }
+
+    override fun leadConverted(leadId: String, params: Map<String, String>, customUserID: String?) {
+        val signalParams = mergeMapsWithOverwrite(params, mapOf(
+            Acquisition.LeadId.paramName to leadId
+        ))
+        signal(
+            com.telemetrydeck.sdk.signals.Acquisition.LeadConverted.signalName,
+            params = signalParams,
+            customUserID = customUserID
+        )
+    }
+
     override suspend fun send(
         signalType: String,
         clientUser: String?,
@@ -212,6 +246,13 @@ class TelemetryDeck(
             .fold("") { str, it -> str + "%02x".format(it) }
     }
 
+    private fun mergeMapsWithOverwrite(map1: Map<String, String>, map2: Map<String, String>): Map<String, String> {
+        val result = mutableMapOf<String, String>()
+        result.putAll(map1)
+        result.putAll(map2)
+        return result
+    }
+
     companion object : TelemetryDeckClient, TelemetryDeckSignalProcessor {
         internal val defaultTelemetryProviders: List<TelemetryDeckProvider>
             get() = listOf(
@@ -290,6 +331,30 @@ class TelemetryDeck(
             getInstance()?.navigate(destinationPath, customUserID = customUserID)
         }
 
+        override fun acquiredUser(
+            channel: String,
+            params: Map<String, String>,
+            customUserID: String?
+        ) {
+            getInstance()?.acquiredUser(channel, params, customUserID)
+        }
+
+        override fun leadStarted(
+            leadId: String,
+            params: Map<String, String>,
+            customUserID: String?
+        ) {
+            getInstance()?.leadStarted(leadId, params, customUserID)
+        }
+
+        override fun leadConverted(
+            leadId: String,
+            params: Map<String, String>,
+            customUserID: String?
+        ) {
+            getInstance()?.leadConverted(leadId, params, customUserID)
+        }
+
         override suspend fun send(
             signalType: String,
             clientUser: String?,

lib/src/main/java/com/telemetrydeck/sdk/TelemetryDeckClient.kt

@@ -33,6 +33,23 @@ interface TelemetryDeckClient {
      * */
     fun navigate(destinationPath: String, customUserID: String? = null)
 
+    /**
+     * Send a `TelemetryDeck.Acquisition.userAcquired` signal with the provided channel.
+     */
+    fun acquiredUser(channel: String, params: Map<String, String> = emptyMap(), customUserID: String? = null)
+
+
+    /**
+     * Send a `TelemetryDeck.Acquisition.leadStarted` signal with the provided leadId.
+     */
+    fun leadStarted(leadId: String, params: Map<String, String> = emptyMap(), customUserID: String? = null)
+
+
+    /**
+     * Send a `TelemetryDeck.Acquisition.leadConverted` signal with the provided leadId.
+     */
+    fun leadConverted(leadId: String, params: Map<String, String> = emptyMap(), customUserID: String? = null)
+
 
     /**
      * Send a signal immediately

lib/src/main/java/com/telemetrydeck/sdk/params/Acquisition.kt

@@ -2,4 +2,6 @@ package com.telemetrydeck.sdk.params
 
 enum class Acquisition(val paramName: String) {
     FirstSessionDate("TelemetryDeck.Acquisition.firstSessionDate"),
+    Channel("TelemetryDeck.Acquisition.channel"),
+    LeadId("TelemetryDeck.Acquisition.leadID"),
 }

lib/src/main/java/com/telemetrydeck/sdk/signals/Acquisition.kt

@@ -2,4 +2,7 @@ package com.telemetrydeck.sdk.signals
 
 internal enum class Acquisition(val signalName: String) {
     NewInstallDetected("TelemetryDeck.Acquisition.newInstallDetected"),
+    LeadStarted("TelemetryDeck.Acquisition.leadStarted"),
+    UserAcquired("TelemetryDeck.Acquisition.userAcquired"),
+    LeadConverted("TelemetryDeck.Acquisition.leadConverted"),
 }

lib/src/test/java/com/telemetrydeck/sdk/TelemetryDeckTests.kt

@@ -236,6 +236,51 @@ class TelemetryDeckTests {
         Assert.assertEquals("false", sut.cache?.empty()?.get(0)?.isTestMode)
     }
 
+    @Test
+    fun telemetryDeck_sends_userAcquired() {
+        val builder = TelemetryDeck.Builder()
+        val sut = builder
+            .appID("32CB6574-6732-4238-879F-582FEBEB6536")
+            .build(null)
+        sut.acquiredUser("channel 1")
+
+        val signal = sut.cache?.empty()?.firstOrNull()
+
+        Assert.assertNotNull(signal)
+        Assert.assertEquals("TelemetryDeck.Acquisition.userAcquired", signal?.type)
+        Assert.assertEquals("TelemetryDeck.Acquisition.channel:channel 1", signal?.payload?.firstOrNull { it.startsWith("TelemetryDeck.Acquisition.channel:") })
+    }
+
+    @Test
+    fun telemetryDeck_sends_leadStarted() {
+        val builder = TelemetryDeck.Builder()
+        val sut = builder
+            .appID("32CB6574-6732-4238-879F-582FEBEB6536")
+            .build(null)
+        sut.leadStarted("lead 1")
+
+        val signal = sut.cache?.empty()?.firstOrNull()
+
+        Assert.assertNotNull(signal)
+        Assert.assertEquals("TelemetryDeck.Acquisition.leadStarted", signal?.type)
+        Assert.assertEquals("TelemetryDeck.Acquisition.leadID:lead 1", signal?.payload?.firstOrNull { it.startsWith("TelemetryDeck.Acquisition.leadID:") })
+    }
+
+    @Test
+    fun telemetryDeck_sends_leadConverted() {
+        val builder = TelemetryDeck.Builder()
+        val sut = builder
+            .appID("32CB6574-6732-4238-879F-582FEBEB6536")
+            .build(null)
+        sut.leadConverted("lead 1")
+
+        val signal = sut.cache?.empty()?.firstOrNull()
+
+        Assert.assertNotNull(signal)
+        Assert.assertEquals("TelemetryDeck.Acquisition.leadConverted", signal?.type)
+        Assert.assertEquals("TelemetryDeck.Acquisition.leadID:lead 1", signal?.payload?.firstOrNull { it.startsWith("TelemetryDeck.Acquisition.leadID:") })
+    }
+
     @Test
     fun telemetryDeck_addProvider_appends_after_default_providers() {
         val builder = TelemetryDeck.Builder()