Merge remote-tracking branch 'origin/main' into feat/#51-duration-tracking

# Conflicts:
#	lib/build.gradle.kts
#	lib/src/test/java/com/telemetrydeck/sdk/TelemetryDeckTests.kt

Author: kkostov

.github/workflows/publish.yml

@@ -1,33 +1,33 @@
-name: Publish to Maven Central
-
-on:
-  push:
-    tags:
-      - "[0-9]+.[0-9]+.[0-9]+*"
-
-jobs:
-  publish:
-    name: Publish to Sonatype
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Configure JDK
-        uses: actions/setup-java@v4
-        with:
-          distribution: 'temurin'
-          java-version: '17'
-
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4
-
-      - name: Upload Artifacts
-        # gradle.properties must be set with SONATYPE_HOST=CENTRAL_PORTAL and RELEASE_SIGNING_ENABLED=true
-        run: ./gradlew publishAndReleaseToMavenCentral --no-configuration-cache
-        env:
-          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.ORG_GRADLE_PROJECT_mavenCentralUsername }}
-          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.ORG_GRADLE_PROJECT_mavenCentralPassword }}
-          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.ORG_GRADLE_PROJECT_signingInMemoryKey }}
-          ORG_GRADLE_PROJECT_signingInMemoryKeyId: ${{ secrets.ORG_GRADLE_PROJECT_signingInMemoryKeyId }}
-          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.ORG_GRADLE_PROJECT_signingInMemoryKeyPassword }}
+#name: Publish to Maven Central
+#
+#on:
+#  push:
+#    tags:
+#      - "[0-9]+.[0-9]+.[0-9]+*"
+#
+#jobs:
+#  publish:
+#    name: Publish to Sonatype
+#    runs-on: ubuntu-latest
+#    steps:
+#      - name: Checkout
+#        uses: actions/checkout@v4
+#
+#      - name: Configure JDK
+#        uses: actions/setup-java@v4
+#        with:
+#          distribution: 'temurin'
+#          java-version: '17'
+#
+#      - name: Setup Gradle
+#        uses: gradle/actions/setup-gradle@v4
+#
+#      - name: Upload Artifacts
+#        # gradle.properties must be set with SONATYPE_HOST=CENTRAL_PORTAL and RELEASE_SIGNING_ENABLED=true
+#        run: ./gradlew publishAndReleaseToMavenCentral --no-configuration-cache
+#        env:
+#          ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.ORG_GRADLE_PROJECT_mavenCentralUsername }}
+#          ORG_GRADLE_PROJECT_mavenCentralPassword: ${{ secrets.ORG_GRADLE_PROJECT_mavenCentralPassword }}
+#          ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.ORG_GRADLE_PROJECT_signingInMemoryKey }}
+#          ORG_GRADLE_PROJECT_signingInMemoryKeyId: ${{ secrets.ORG_GRADLE_PROJECT_signingInMemoryKeyId }}
+#          ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.ORG_GRADLE_PROJECT_signingInMemoryKeyPassword }}

README.md

@@ -10,7 +10,7 @@ The Kotlin SDK for TelemetryDeck is available from Maven Central and can be used
 
 ```groovy
 dependencies {
-    implementation 'com.telemetrydeck:kotlin-sdk:4.0.2'
+    implementation 'com.telemetrydeck:kotlin-sdk:4.0.5'
 }
 ```
 
@@ -148,9 +148,41 @@ By default, Kotlin SDK for TelemetryDeck will include the following environment
 
 See [Custom Telemetry](#custom-telemetry) on how to implement your own parameter enrichment.
 
+## Default Parameters
+
+If there are parameters you would like to include with every outgoing signal, you can use `DefaultParameterProvider` instead of passing them with every call.
+
+```kotlin
+// create an instance of [DefaultParameterProvider] and pass the key value you wish to be appended to every signal
+val provider = DefaultParameterProvider(mapOf("key" to "value"))
+
+// add the provider when configuring an instance of TelemetryDeck
+
+val builder = TelemetryDeck.Builder()
+    .appID("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
+    .addProvider(provider)
+```
+
+## Default prefix
+
+If you find yourself prepending the same prefix for to your custom signals or parameters, 
+you can optionally configure `TelemetryDeck` to do this for you by activating our `DefaultPrefixProvider`:
+
+
+```kotlin
+// create an instance of [DefaultPrefixProvider] with a signal or parameter prefix
+val provider = DefaultPrefixProvider("MyApp.", "MyApp.Params.")
+
+// add the provider when configuring an instance of TelemetryDeck
+
+val builder = TelemetryDeck.Builder()
+    .appID("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
+    .addProvider(provider)
+```
+
 ## Custom Telemetry
 
-Another way to send signals is to register a custom `TelemetryDeckProvider`.
+Another way to send signals is to implement a custom `TelemetryDeckProvider`.
 A provider uses the TelemetryDeck client in order to queue or send signals based on environment or other triggers.
 
 
@@ -216,6 +248,8 @@ You can also completely disable or override the default providers with your own.
 - `EnvironmentParameterProvider` - Adds environment and device information to outgoing Signals. This provider overrides the `enrich` method in order to append additional metadata for all signals before sending them.
 - `PlatformContextProvider` - Adds environment and device information which may change over time like the current timezone and screen metrics.
 
+For a complete list, check the `com.telemetrydeck.sdk.providers` package.
+
 ```kotlin
 // Append a custom provider
 val builder = TelemetryDeck.Builder()
@@ -303,7 +337,6 @@ After:
 
 ### Custom Telemetry
 
-
 Your custom providers must replace `TelemetryProvider` with `TelemetryDeckProvider`.
 
 To adopt the new interface:

build.gradle.kts

@@ -2,6 +2,5 @@ plugins {
     alias(libs.plugins.androidLibrary) apply false
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.kotlin.serialization) apply false
-    alias(libs.plugins.kotlin.compose) apply false
     alias(libs.plugins.vanniktech.publish) apply false
 }

gradle/libs.versions.toml

@@ -1,16 +1,16 @@
 [versions]
-agp = "8.7.3"
+agp = "8.8.0"
 kotlin = "2.0.20"
-coreKtx = "1.13.1"
+coreKtx = "1.15.0"
 junit = "4.13.2"
 junitVersion = "1.2.1"
 espressoCore = "3.6.1"
 lifecycleRuntimeKtx = "2.8.7"
-activityCompose = "1.9.3"
-composeBom = "2024.10.00"
+activityCompose = "1.10.0"
+composeBom = "2024.04.01"
 ktor = "3.0.2"
 kotlinx = "1.7.3"
-coroutines = "1.9.0"
+coroutines = "1.10.1"
 vanniktech-publish = "0.30.0"
 appcompat = "1.7.0"
 mockk = "1.13.13"
@@ -50,5 +50,4 @@ androidx-jUnitTestRules = { module = "androidx.test:rules", version.ref = "andro
 androidLibrary = { id = "com.android.library", version.ref = "agp" }
 kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
 kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
-vanniktech-publish = { id = "com.vanniktech.maven.publish", version.ref = "vanniktech-publish" }
-kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+vanniktech-publish = { id = "com.vanniktech.maven.publish", version.ref = "vanniktech-publish" }

lib/build.gradle.kts

@@ -5,7 +5,6 @@ plugins {
     alias(libs.plugins.androidLibrary)
     alias(libs.plugins.kotlin.android)
     alias(libs.plugins.kotlin.serialization)
-    alias(libs.plugins.kotlin.compose)
     alias(libs.plugins.vanniktech.publish)
 }
 
@@ -44,7 +43,7 @@ android {
         jvmTarget = "11"
     }
     buildFeatures {
-        compose = true
+        compose = false
         buildConfig = true
     }
 
@@ -68,10 +67,6 @@ dependencies {
     implementation(libs.androidx.core.ktx)
     implementation(libs.androidx.lifecycle.runtime.ktx)
     implementation(libs.androidx.lifecycle.process)
-    // explicit dependency on compose seems to be required to use the compose compiler
-    // this is not used by the library atm
-    implementation(libs.androidx.activity.compose)
-    implementation(platform(libs.androidx.compose.bom))
     implementation(libs.androidx.appcompat)
     implementation(libs.ktor.client.core)
     implementation(libs.kotlinx.coroutines.core)
@@ -86,14 +81,16 @@ dependencies {
 
     testImplementation(libs.junit)
     testImplementation(libs.androidx.arch.core)
-
+    // As of Kotlin 2.0, the Compose Compiler and runtime are required in the classpath https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-compiler.html
+    testImplementation(libs.androidx.activity.compose)
+    testImplementation(platform(libs.androidx.compose.bom))
     androidTestImplementation(libs.androidx.junit)
     androidTestImplementation(libs.androidx.espresso.core)
     androidTestImplementation(platform(libs.androidx.compose.bom))
     androidTestImplementation(libs.androidx.ui.test.junit4)
     androidTestImplementation(libs.androidx.jUnitTestRules)
-    debugImplementation(libs.androidx.ui.tooling)
-    debugImplementation(libs.androidx.ui.test.manifest)
+    androidTestImplementation(libs.androidx.ui.tooling)
+    androidTestImplementation(libs.androidx.ui.test.manifest)
 
     testImplementation(libs.mockk)
     testImplementation(libs.mockk.android)
@@ -102,7 +99,7 @@ dependencies {
 }
 
 mavenPublishing {
-    coordinates("com.telemetrydeck", "kotlin-sdk", "4.0.2")
+    coordinates("com.telemetrydeck", "kotlin-sdk", "4.0.5")
 
     pom {
         name = "TelemetryDeck SDK"

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

@@ -0,0 +1,3 @@
+package com.telemetrydeck.sdk
+
+data class SignalTransform(val signalType: String, val clientUser: String?, val additionalPayload: Map<String, String>, val floatValue: Double?)

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

@@ -178,19 +178,27 @@ class TelemetryDeck(
             enrichedPayload = provider.enrich(signalType, clientUser, enrichedPayload)
         }
 
-        val userValue = identityProvider.calculateIdentity(clientUser, configuration.defaultUser)
+        var signalTransform = SignalTransform(signalType, clientUser, enrichedPayload, floatValue)
+        for (provider in this.providers) {
+            signalTransform = provider.transform(signalTransform)
+        }
+        return signalFromTransform(signalTransform)
+    }
+
+    private fun signalFromTransform(signalTransform: SignalTransform): Signal {
+        val userValue = identityProvider.calculateIdentity(signalTransform.clientUser, configuration.defaultUser)
 
         val userValueWithSalt = userValue + (configuration.salt ?: "")
         val hashedUser = hashString(userValueWithSalt)
 
-        val payload = SignalPayload(additionalPayload = enrichedPayload)
+        val payload = SignalPayload(additionalPayload = signalTransform.additionalPayload)
         val signal = Signal(
             appID = configuration.telemetryAppID,
-            type = signalType,
+            type = signalTransform.signalType,
             clientUser = hashedUser,
             payload = payload.asMultiValueDimension,
             isTestMode = configuration.testMode.toString().lowercase(),
-            floatValue = floatValue
+            floatValue = signalTransform.floatValue
         )
         signal.sessionID = this.configuration.sessionID.toString()
         logger?.debug("Created a signal ${signal.type}, session ${signal.sessionID}, test ${signal.isTestMode}")

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

@@ -21,7 +21,7 @@ interface TelemetryDeckProvider {
      * A provider can override this method in order to append or remove telemetry metadata from Signals
      * before they are enqueued for broadcast.
      *
-     * TelemetryManager calls this method all providers in order of registration.
+     * TelemetryManager calls this method on all providers in order of registration.
      */
     fun enrich(
         signalType: String,
@@ -30,4 +30,17 @@ interface TelemetryDeckProvider {
     ): Map<String, String> {
         return additionalPayload
     }
-}
+
+    /**
+     * A provider can override this method in order apply a transformation on any part of the signal, including the signal name.
+     * [TelemetryDeck] calls this method on all providers in order of registration.
+     *
+     * This method is always called **after** [enrich].
+     */
+    fun transform(
+        signalTransform: SignalTransform
+    ): SignalTransform {
+        return signalTransform
+    }
+}
+

lib/src/main/java/com/telemetrydeck/sdk/providers/DefaultParameterProvider.kt

@@ -0,0 +1,38 @@
+package com.telemetrydeck.sdk.providers
+
+import android.app.Application
+import com.telemetrydeck.sdk.TelemetryDeckProvider
+import com.telemetrydeck.sdk.TelemetryDeckSignalProcessor
+
+
+/**
+ * [DefaultParameterProvider] is a [TelemetryDeckProvider] that adds default parameters
+ * to every telemetry signal. It ensures that signals are enriched with predefined data,
+ * unless the signal already contains a value for the same key.
+ *
+ * @property defaultParameters A map of key-value pairs representing the default parameters
+ *                            that will be added to each telemetry signal.
+ */
+class DefaultParameterProvider(val defaultParameters: Map<String, String>): TelemetryDeckProvider {
+    override fun register(ctx: Application?, client: TelemetryDeckSignalProcessor) {
+        // nothing to do
+    }
+
+    override fun stop() {
+        // nothing to do
+    }
+
+    override fun enrich(
+        signalType: String,
+        clientUser: String?,
+        additionalPayload: Map<String, String>
+    ): Map<String, String> {
+        val signalPayload = additionalPayload.toMutableMap()
+        for (item in defaultParameters) {
+            if (!signalPayload.containsKey(item.key)) {
+                signalPayload[item.key] = item.value
+            }
+        }
+        return signalPayload
+    }
+}