Merge pull request #98 from TelemetryDeck/feat/pirate-referral

Pirate metrics alignment

Author: kkostov

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

@@ -4,6 +4,7 @@ import android.content.Context
 import android.content.pm.ApplicationInfo
 import com.telemetrydeck.sdk.params.Acquisition
 import com.telemetrydeck.sdk.params.Activation
+import com.telemetrydeck.sdk.params.ErrorCategory
 import com.telemetrydeck.sdk.params.Navigation
 import com.telemetrydeck.sdk.params.Revenue
 import com.telemetrydeck.sdk.providers.AccessibilityProvider
@@ -72,7 +73,6 @@ class TelemetryDeck(
         navigate(navigationStatus.getLastDestination(), destinationPath, customUserID)
     }
 
-    @ExperimentalFeature
     override fun acquiredUser(channel: String, params: Map<String, String>, customUserID: String?) {
         val signalParams = mergeMapsWithOverwrite(params, mapOf(
             Acquisition.Channel.paramName to channel
@@ -84,7 +84,6 @@ class TelemetryDeck(
         )
     }
 
-    @ExperimentalFeature
     override fun leadStarted(leadId: String, params: Map<String, String>, customUserID: String?) {
         val signalParams = mergeMapsWithOverwrite(params, mapOf(
             Acquisition.LeadId.paramName to leadId
@@ -96,7 +95,6 @@ class TelemetryDeck(
         )
     }
 
-    @ExperimentalFeature
     override fun leadConverted(leadId: String, params: Map<String, String>, customUserID: String?) {
         val signalParams = mergeMapsWithOverwrite(params, mapOf(
             Acquisition.LeadId.paramName to leadId
@@ -108,7 +106,6 @@ class TelemetryDeck(
         )
     }
 
-    @ExperimentalFeature
     override fun onboardingCompleted(
         params: Map<String, String>,
         customUserID: String?
@@ -120,7 +117,6 @@ class TelemetryDeck(
         )
     }
 
-    @ExperimentalFeature
     override fun coreFeatureUsed(
         featureName: String,
         params: Map<String, String>,
@@ -155,6 +151,76 @@ class TelemetryDeck(
         )
     }
 
+    override fun referralSent(
+        receiversCount: Int,
+        kind: String?,
+        params: Map<String, String>,
+        customUserID: String?
+    ) {
+        val referralParams = mutableMapOf(
+            com.telemetrydeck.sdk.params.Referral.ReceiversCount.paramName to receiversCount.toString()
+        )
+        if (kind != null) {
+            referralParams[com.telemetrydeck.sdk.params.Referral.Kind.paramName] = kind
+        }
+        val signalParams = mergeMapsWithOverwrite(params, referralParams)
+        signal(
+            com.telemetrydeck.sdk.signals.Referral.Sent.signalName,
+            params = signalParams,
+            customUserID = customUserID
+        )
+    }
+
+    override fun userRatingSubmitted(
+        rating: Int,
+        comment: String?,
+        params: Map<String, String>,
+        customUserID: String?
+    ) {
+        if (rating < 0 || rating > 10) {
+            logger?.error("userRatingSubmitted: rating must be between 0 and 10, got $rating")
+            return
+        }
+        val referralParams = mutableMapOf(
+            com.telemetrydeck.sdk.params.Referral.RatingValue.paramName to rating.toString()
+        )
+        if (comment != null) {
+            referralParams[com.telemetrydeck.sdk.params.Referral.RatingComment.paramName] = comment
+        }
+        val signalParams = mergeMapsWithOverwrite(params, referralParams)
+        signal(
+            com.telemetrydeck.sdk.signals.Referral.UserRatingSubmitted.signalName,
+            params = signalParams,
+            customUserID = customUserID
+        )
+    }
+
+    override fun errorOccurred(
+        id: String,
+        category: ErrorCategory?,
+        message: String?,
+        parameters: Map<String, String>,
+        floatValue: Double?,
+        customUserID: String?
+    ) {
+        val errorParams = mutableMapOf(
+            com.telemetrydeck.sdk.params.Error.Id.paramName to id
+        )
+        if (category != null) {
+            errorParams[com.telemetrydeck.sdk.params.Error.Category.paramName] = category.rawValue
+        }
+        if (message != null) {
+            errorParams[com.telemetrydeck.sdk.params.Error.Message.paramName] = message
+        }
+        val signalParams = mergeMapsWithOverwrite(parameters, errorParams)
+        signal(
+            com.telemetrydeck.sdk.signals.Error.Occurred.signalName,
+            params = signalParams,
+            floatValue = floatValue,
+            customUserID = customUserID
+        )
+    }
+
     override suspend fun send(
         signalType: String,
         clientUser: String?,
@@ -448,7 +514,6 @@ class TelemetryDeck(
             getInstance()?.navigate(destinationPath, customUserID = customUserID)
         }
 
-        @ExperimentalFeature
         override fun acquiredUser(
             channel: String,
             params: Map<String, String>,
@@ -457,7 +522,6 @@ class TelemetryDeck(
             getInstance()?.acquiredUser(channel, params, customUserID)
         }
 
-        @ExperimentalFeature
         override fun leadStarted(
             leadId: String,
             params: Map<String, String>,
@@ -466,7 +530,6 @@ class TelemetryDeck(
             getInstance()?.leadStarted(leadId, params, customUserID)
         }
 
-        @ExperimentalFeature
         override fun leadConverted(
             leadId: String,
             params: Map<String, String>,
@@ -475,15 +538,13 @@ class TelemetryDeck(
             getInstance()?.leadConverted(leadId, params, customUserID)
         }
 
-        @ExperimentalFeature
         override fun onboardingCompleted(
             params: Map<String, String>,
             customUserID: String?
         ) {
             getInstance()?.onboardingCompleted(params, customUserID)
         }
 
-        @ExperimentalFeature
         override fun coreFeatureUsed(
             featureName: String,
             params: Map<String, String>,
@@ -500,6 +561,35 @@ class TelemetryDeck(
             getInstance()?.paywallShown(reason, params, customUserID)
         }
 
+        override fun referralSent(
+            receiversCount: Int,
+            kind: String?,
+            params: Map<String, String>,
+            customUserID: String?
+        ) {
+            getInstance()?.referralSent(receiversCount, kind, params, customUserID)
+        }
+
+        override fun userRatingSubmitted(
+            rating: Int,
+            comment: String?,
+            params: Map<String, String>,
+            customUserID: String?
+        ) {
+            getInstance()?.userRatingSubmitted(rating, comment, params, customUserID)
+        }
+
+        override fun errorOccurred(
+            id: String,
+            category: ErrorCategory?,
+            message: String?,
+            parameters: Map<String, String>,
+            floatValue: Double?,
+            customUserID: String?
+        ) {
+            getInstance()?.errorOccurred(id, category, message, parameters, floatValue, customUserID)
+        }
+
         override suspend fun send(
             signalType: String,
             clientUser: String?,

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

@@ -1,5 +1,6 @@
 package com.telemetrydeck.sdk
 
+import com.telemetrydeck.sdk.params.ErrorCategory
 import java.util.UUID
 
 interface TelemetryDeckClient {
@@ -34,35 +35,59 @@ interface TelemetryDeckClient {
     fun navigate(destinationPath: String, customUserID: String? = null)
 
     /**
-     * Send a `TelemetryDeck.Acquisition.userAcquired` signal with the provided channel.
+     * Tracks user acquisition through a specific marketing or organic channel.
+     *
+     * Sends signal: `TelemetryDeck.Acquisition.userAcquired`
+     *
+     * @param channel The acquisition channel (e.g., "organic", "facebook_ads", "google_search").
+     * @param params A map of additional string key-value pairs that provide further context about the signal.
+     * @param customUserID An optional string specifying a custom user identifier.
      */
-    @ExperimentalFeature
     fun acquiredUser(channel: String, params: Map<String, String> = emptyMap(), customUserID: String? = null)
 
 
     /**
-     * Send a `TelemetryDeck.Acquisition.leadStarted` signal with the provided leadId.
+     * Tracks when a potential customer begins the conversion process.
+     *
+     * Sends signal: `TelemetryDeck.Acquisition.leadStarted`
+     *
+     * @param leadId A unique identifier for the lead (e.g., email, signup ID).
+     * @param params A map of additional string key-value pairs that provide further context about the signal.
+     * @param customUserID An optional string specifying a custom user identifier.
      */
-    @ExperimentalFeature
     fun leadStarted(leadId: String, params: Map<String, String> = emptyMap(), customUserID: String? = null)
 
 
     /**
-     * Send a `TelemetryDeck.Acquisition.leadConverted` signal with the provided leadId.
+     * Tracks when a lead successfully converts to a user.
+     *
+     * Sends signal: `TelemetryDeck.Acquisition.leadConverted`
+     *
+     * @param leadId The unique identifier for the lead that converted.
+     * @param params A map of additional string key-value pairs that provide further context about the signal.
+     * @param customUserID An optional string specifying a custom user identifier.
      */
-    @ExperimentalFeature
     fun leadConverted(leadId: String, params: Map<String, String> = emptyMap(), customUserID: String? = null)
 
     /**
-     * Send a `TelemetryDeck.Activation.onboardingCompleted` signal.
+     * Tracks when a user successfully completes the onboarding process.
+     *
+     * Sends signal: `TelemetryDeck.Activation.onboardingCompleted`
+     *
+     * @param params A map of additional string key-value pairs that provide further context about the signal.
+     * @param customUserID An optional string specifying a custom user identifier.
      */
-    @ExperimentalFeature
     fun onboardingCompleted(params: Map<String, String> = emptyMap(), customUserID: String? = null)
 
     /**
-     * Send a `TelemetryDeck.Activation.coreFeatureUsed` signal.
+     * Tracks when a user engages with a core feature of the application.
+     *
+     * Sends signal: `TelemetryDeck.Activation.coreFeatureUsed`
+     *
+     * @param featureName The name of the core feature that was used.
+     * @param params A map of additional string key-value pairs that provide further context about the signal.
+     * @param customUserID An optional string specifying a custom user identifier.
      */
-    @ExperimentalFeature
     fun coreFeatureUsed(
         featureName: String,
         params: Map<String, String> = emptyMap(),
@@ -245,5 +270,62 @@ interface TelemetryDeckClient {
         customUserID: String? = null
     )
 
+    /**
+     * Tracks when a user sends a referral to others.
+     *
+     * Sends signal: `TelemetryDeck.Referral.sent`
+     *
+     * @param receiversCount The number of receivers the referral was sent to (defaults to 1).
+     * @param kind Optional string describing the kind of referral (e.g., "email", "social_share").
+     * @param params A map of additional string key-value pairs that provide further context about the signal.
+     * @param customUserID An optional string specifying a custom user identifier.
+     */
+    fun referralSent(
+        receiversCount: Int = 1,
+        kind: String? = null,
+        params: Map<String, String> = emptyMap(),
+        customUserID: String? = null
+    )
+
+    /**
+     * Tracks when a user submits a rating for the application.
+     *
+     * Sends signal: `TelemetryDeck.Referral.userRatingSubmitted`
+     *
+     * Note: Rating values are validated to be between 0 and 10 inclusive.
+     *
+     * @param rating The rating value (must be between 0 and 10 inclusive).
+     * @param comment Optional comment accompanying the rating.
+     * @param params A map of additional string key-value pairs that provide further context about the signal.
+     * @param customUserID An optional string specifying a custom user identifier.
+     */
+    fun userRatingSubmitted(
+        rating: Int,
+        comment: String? = null,
+        params: Map<String, String> = emptyMap(),
+        customUserID: String? = null
+    )
+
+    /**
+     * Tracks when an error occurs in the application.
+     *
+     * Sends signal: `TelemetryDeck.Error.occurred`
+     *
+     * @param id A unique identifier for the error (e.g., error code, exception class name).
+     * @param category The category of the error (e.g., thrown exception, user input, app state).
+     * @param message An optional error message describing what went wrong.
+     * @param parameters A map of additional string key-value pairs that provide further context about the error.
+     * @param floatValue An optional floating-point number that can be used to provide numerical data about the error.
+     * @param customUserID An optional string specifying a custom user identifier.
+     */
+    fun errorOccurred(
+        id: String,
+        category: ErrorCategory? = null,
+        message: String? = null,
+        parameters: Map<String, String> = emptyMap(),
+        floatValue: Double? = null,
+        customUserID: String? = null
+    )
+
     val configuration: TelemetryManagerConfiguration?
 }

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

@@ -1,6 +1,6 @@
 package com.telemetrydeck.sdk.params
 
-internal enum class AppInfo(val paramName: String) {
+enum class AppInfo(val paramName: String) {
     BuildNumber("TelemetryDeck.AppInfo.buildNumber"),
     Version("TelemetryDeck.AppInfo.version"),
     VersionAndBuildNumber("TelemetryDeck.AppInfo.versionAndBuildNumber"),

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

@@ -1,6 +1,6 @@
 package com.telemetrydeck.sdk.params
 
-internal enum class Calendar(val paramName: String) {
+enum class Calendar(val paramName: String) {
     DayOfMonth("TelemetryDeck.Calendar.dayOfMonth"),
     DayOfWeek("TelemetryDeck.Calendar.dayOfWeek"),
     DayOfYear("TelemetryDeck.Calendar.dayOfYear"),

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

@@ -1,7 +1,7 @@
 package com.telemetrydeck.sdk.params
 
 
-internal enum class Device(val paramName: String) {
+enum class Device(val paramName: String) {
     Architecture("TelemetryDeck.Device.architecture"),
     ModelName("TelemetryDeck.Device.modelName"),
     OperatingSystem("TelemetryDeck.Device.operatingSystem"),

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

@@ -0,0 +1,7 @@
+package com.telemetrydeck.sdk.params
+
+enum class Error(val paramName: String) {
+    Id("TelemetryDeck.Error.id"),
+    Category("TelemetryDeck.Error.category"),
+    Message("TelemetryDeck.Error.message"),
+}

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

@@ -0,0 +1,7 @@
+package com.telemetrydeck.sdk.params
+
+enum class ErrorCategory(val rawValue: String) {
+    ThrownException("thrown-exception"),
+    UserInput("user-input"),
+    AppState("app-state")
+}

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

@@ -1,6 +1,6 @@
 package com.telemetrydeck.sdk.params
 
-internal enum class Navigation(val paramName: String) {
+enum class Navigation(val paramName: String) {
     SchemaVersion("TelemetryDeck.Navigation.schemaVersion"),
     Identifier("TelemetryDeck.Navigation.identifier"),
     SourcePath("TelemetryDeck.Navigation.sourcePath"),

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

@@ -1,6 +1,6 @@
 package com.telemetrydeck.sdk.params
 
-internal enum class Purchase(val paramName: String) {
+enum class Purchase(val paramName: String) {
     Type("TelemetryDeck.Purchase.type"),
     CountryCode("TelemetryDeck.Purchase.countryCode"),
     CurrencyCode("TelemetryDeck.Purchase.currencyCode"),