Merge pull request #29 from TelemetryDeck/feat/extend-configuration

Add the option to provide a custom salt for consistent user identifiers

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.0.0
+
+- https://github.com/TelemetryDeck/FlutterSDK/releases/tag/2.0.0
+- The KotlinSDK has been updated to [version 4.0.2](https://github.com/TelemetryDeck/KotlinSDK/releases/tag/4.0.2) introducing automatic generation of random user identifiers ([link](https://github.com/TelemetryDeck/KotlinSDK/issues/14)) and other improvements.
+- Added the option to provide a custom salt for consistent user identifiers.
+
 ## 1.0.0
 
 - https://github.com/TelemetryDeck/FlutterSDK/releases/tag/1.0.0

README.md

@@ -25,19 +25,19 @@ void main() {
 }
 ```
 
-## Permission for internet access
+### Permission for internet access
 
 Sending signals requires access to the internet so the following permissions should be granted. For more information, you can check [Flutter Cross-platform HTTP networking ](https://docs.flutter.dev/data-and-backend/networking).
 
-### Android
+#### Android
 
 Change the app's `AndroidManifest.xml` to include:
 
 ```xml
 <uses-permission android:name="android.permission.INTERNET" />
 ```
 
-### macOS
+#### macOS
 
 Set the `com.apple.security.network.client` entitlement to `true` in the `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements` files. You can also do this in Xcode by selecting the `macos` target, then the `Signing & Capabilities` tab, and checking `Outgoing connections (Client)` for both the Release and Debug targets of your app.
 
@@ -64,7 +64,7 @@ Telemetrydecksdk.send(
 
 The Flutter SDK uses the native SDKs for Android and iOS which offer a number of built-in attributes which are submitted with every signal.
 
-You can overwrite these attributes by providing a custom value with the same key. For more information on how each value is calcualted, check the corresponding platform library.
+For more information on how each value is calcualted, check the corresponding platform library.
 
 The Flutter SDK adds the following additional attributes:
 
@@ -118,6 +118,23 @@ Telemetrydecksdk.start(
 
 [Getting started with Test Mode](https://telemetrydeck.com/docs/articles/test-mode/)
 
+## Custom Salt
+
+By default, user identifiers are hashed by the TelemetryDeck SDK, and then sent to the Ingestion API, where we'll add a salt to the received identifier and hash it again.
+
+This is enough for most use cases, but if you want to extra privacy conscious, you can add in you own salt on the client side. The TelemetryDeck SDK will append the salt to all user identifers before hashing them and sending them to us.
+
+If you'd like to use a custom salt, you can do so by passing it on to the starting `TelemetryManagerConfiguration`:
+
+```dart
+Telemetrydecksdk.start(
+  TelemetryManagerConfiguration(
+    appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
+    salt: "<A RANDOM STRING>",
+  ),
+);
+```
+
 ## Custom Server
 
 A very small subset of our customers will want to use a custom signal ingestion server or a custom proxy server. To do so, you can pass the URL of the custom server to the `TelemetryManagerConfiguration`:

android/build.gradle

@@ -50,7 +50,7 @@ android {
     }
 
     dependencies {
-        implementation 'com.telemetrydeck:kotlin-sdk:3.0.3'
+        implementation 'com.telemetrydeck:kotlin-sdk:4.0.2'
         testImplementation 'org.jetbrains.kotlin:kotlin-test'
         testImplementation 'org.mockito:mockito-core:5.0.0'
     }

android/src/main/kotlin/com/telemetrydeck/telemetrydecksdk/TelemetrydecksdkPlugin.kt

@@ -169,6 +169,7 @@ class TelemetrydecksdkPlugin : FlutterPlugin, MethodCallHandler {
             val defaultUser = arguments["defaultUser"] as? String?
             val debug = arguments["debug"] as? Boolean
             val testMode = arguments["testMode"] as? Boolean
+            val salt = arguments["salt"] as? String?
 
 
             // Initialize the client
@@ -188,6 +189,9 @@ class TelemetrydecksdkPlugin : FlutterPlugin, MethodCallHandler {
             testMode?.let {
                 builder.testMode(it)
             }
+            salt?.let {
+                builder.salt(it)
+            }
 
             val application = applicationContext as Application
             TelemetryDeck.start(application, builder)

example/android/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,7 @@
-#Mon Dec 16 15:22:49 CET 2024
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.9-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-all.zip

example/lib/main.dart

@@ -7,10 +7,9 @@ void main() {
   WidgetsFlutterBinding.ensureInitialized();
   Telemetrydecksdk.start(
     const TelemetryManagerConfiguration(
-      appID: "22385F1C-3699-4F04-9D63-24CC0B2E62D8",
-      debug: true,
-      testMode: true,
-    ),
+        appID: "22385F1C-3699-4F04-9D63-24CC0B2E62D8",
+        debug: true,
+        testMode: true),
   );
   runApp(const MyApp());
 }

example/pubspec.lock

@@ -237,7 +237,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "0.6.0"
+    version: "1.0.0"
   term_glyph:
     dependency: transitive
     description:

ios/Classes/TelemetrydecksdkPlugin.swift

@@ -113,8 +113,10 @@ public class TelemetrydecksdkPlugin: NSObject, FlutterPlugin {
             baseURL = url
         }
 
+
+        let salt =  arguments["salt"] as? String
         let configuration = TelemetryManagerConfiguration.init(
-            appID: appID, salt: nil, baseURL: baseURL)
+            appID: appID, salt: salt, baseURL: baseURL)
 
         // other optional params
         if arguments.keys.contains("defaultUser") {

lib/src/telemetry_manager_configuration.dart

@@ -20,13 +20,15 @@ class TelemetryManagerConfiguration {
   /// If `testMode` is not set explicitly, the corresponding native SDK will automatically determine the value based on whether this is a debug or release build of the app.
   final bool? testMode;
 
-  const TelemetryManagerConfiguration({
-    required this.appID,
-    this.apiBaseURL,
-    this.defaultUser,
-    this.debug,
-    this.testMode,
-  });
+  final String? salt;
+
+  const TelemetryManagerConfiguration(
+      {required this.appID,
+      this.apiBaseURL,
+      this.defaultUser,
+      this.debug,
+      this.testMode,
+      this.salt});
 
   /// to map
   Map<String, dynamic> toMap() {
@@ -36,6 +38,7 @@ class TelemetryManagerConfiguration {
       'defaultUser': defaultUser,
       'debug': debug,
       'testMode': testMode,
+      'salt': salt
     };
   }
 }