Merge pull request #4 from novas1r1/main

Basic cleanup, documentation corrections

Author: kkostov

CHANGELOG.md

@@ -1,26 +1,25 @@
-## 0.3.0
+## 0.4.0
+- https://github.com/TelemetryDeck/FlutterSDK/releases/tag/0.4.0
+- Updated `flutter_lints` dependency
+- Updated package to make it compliant with flutter package rules
+- Made all calls in `Telemetrydecksdk` class static - no need to create an instance anymore
+- `additionalPayload` takes a `Map<String, dynamic>`now instead of a `Map<String, String>` and values will now be stringified automatically
 
+## 0.3.0
 - https://github.com/TelemetryDeck/FlutterSDK/releases/tag/0.3.0
 
-
 ## 0.2.0
-
 - https://github.com/TelemetryDeck/FlutterSDK/releases/tag/0.2.0
 
-
 ## 0.1.0
-
 - TelemetryDeck SDK is now available for macOS apps
 - Improvements to documentation and pub.dev listing
 
 ## 0.0.5
-
 - https://github.com/TelemetryDeck/FlutterSDK/releases/tag/0.0.5
 
 ## 0.0.4
-
 - The initial release of TelemetryDeck SDK for Flutter
 
 ## 0.0.3
-
 - The initial release of TelemetryDeck SDK for Flutter

README.md

@@ -15,8 +15,12 @@ void main() {
   // ensure the platform channels are available
   WidgetsFlutterBinding.ensureInitialized();
   // configure and start the TelemetryClient
-  Telemetrydecksdk.start(TelemetryManagerConfiguration(
-      appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"));
+  Telemetrydecksdk.start(
+    TelemetryManagerConfiguration(
+      appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
+    ),
+  );
+
   runApp(const MyApp());
 }
 ```
@@ -42,17 +46,18 @@ Set the `com.apple.security.network.client` entitlement to `true` in the `macos/
 Send a signal using the following method:
 
 ```dart
-TelemetryManager.send("signal_type")
+Telemetrydecksdk.send("signal_type")
 ```
 
 ## Signals with additional attributes
 
 Append any number of custom attributes to a signal:
 
 ```dart
-TelemetryManager.send("signal_type",
-  additionalPayload: {"attributeName": "value"});
-}
+Telemetrydecksdk.send(
+  "signal_type",
+  additionalPayload: {"attributeName": "value"},
+);
 ```
 
 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:
@@ -81,7 +86,7 @@ The Flutter SDK uses the native SDKs for Android and iOS which offer a number of
 Prevent signals from being sent using the stop method:
 
 ```dart
-TelemetryManager.stop()
+Telemetrydecksdk.stop()
 ```
 
 In order to restart sending events, you will need to call the `start` method again.
@@ -92,10 +97,13 @@ If your app's build configuration is set to "Debug", all signals sent will be ma
 
 If you want to manually control whether test mode is active, you can set the `testMode` field:
 
-```swift
-Telemetrydecksdk.start(TelemetryManagerConfiguration(
-  appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
-  testMode: true));
+```dart
+Telemetrydecksdk.start(
+  TelemetryManagerConfiguration(
+    appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
+    testMode: true,
+  ),
+);
 ```
 
 [Getting started with Test Mode](https://telemetrydeck.com/docs/articles/test-mode/)
@@ -104,10 +112,13 @@ Telemetrydecksdk.start(TelemetryManagerConfiguration(
 
 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`:
 
-```swift
-Telemetrydecksdk.start(TelemetryManagerConfiguration(
-  appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
-  apiBaseURL: "https://nom.telemetrydeck.com"));
+```dart
+Telemetrydecksdk.start(
+  TelemetryManagerConfiguration(
+    appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
+    apiBaseURL: "https://nom.telemetrydeck.com",
+  ),
+);
 ```
 
 ## Logging output
@@ -116,8 +127,11 @@ By default, some logs helpful for monitoring TelemetryDeck are printed out to th
 
 ```dart
 void main() {
-  Telemetrydecksdk.start(TelemetryManagerConfiguration(
+  Telemetrydecksdk.start(
+    TelemetryManagerConfiguration(
       appID: "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
-      debug: true));
+      debug: true,
+    ),
+  );
 }
 ```

analysis_options.yaml

@@ -1,4 +1,3 @@
 include: package:flutter_lints/flutter.yaml
-
 # Additional information about this file can be found at
 # https://dart.dev/guides/language/analysis-options

example/lib/main.dart

@@ -1,13 +1,17 @@
-import 'package:flutter/material.dart';
 import 'dart:async';
 
-import 'package:telemetrydecksdk/telemetry_manager_configuration.dart';
+import 'package:flutter/material.dart';
 import 'package:telemetrydecksdk/telemetrydecksdk.dart';
 
 void main() {
   WidgetsFlutterBinding.ensureInitialized();
-  Telemetrydecksdk.start(TelemetryManagerConfiguration(
-      appID: "your TelemetryDeck App ID", debug: true, testMode: true));
+  Telemetrydecksdk.start(
+    const TelemetryManagerConfiguration(
+      appID: "A4CAE055-857C-45F8-8C6B-335E3617050D",
+      debug: true,
+      testMode: true,
+    ),
+  );
   runApp(const MyApp());
 }
 
@@ -19,8 +23,6 @@ class MyApp extends StatefulWidget {
 }
 
 class _MyAppState extends State<MyApp> {
-  final _telemetrydecksdkPlugin = Telemetrydecksdk();
-
   @override
   void initState() {
     super.initState();
@@ -47,16 +49,21 @@ class _MyAppState extends State<MyApp> {
             mainAxisSize: MainAxisSize.min,
             children: <Widget>[
               const Text('Hello !'),
-              const SizedBox(height: 10),
+              const SizedBox(height: 10), // Adds some space between the text and the button
               ElevatedButton(
                 onPressed: () {
                   // Send a signal type to TelemetryDeck
-                  _telemetrydecksdkPlugin.send("button_clicked");
+                  Telemetrydecksdk.send("button_clicked");
                   // You can optionally attach parameters to the signal
-                  _telemetrydecksdkPlugin.send("button_clicked",
-                      clientUser: "user");
-                  _telemetrydecksdkPlugin.send("button_clicked",
-                      additionalPayload: {"mapKey": "mapValue"});
+                  Telemetrydecksdk.send(
+                    "button_clicked",
+                    clientUser: "user",
+                  );
+                  // Provide additional payload information
+                  Telemetrydecksdk.send(
+                    "button_clicked",
+                    additionalPayload: {"mapKey": "mapValue"},
+                  );
                 },
                 child: const Text('Press Me'),
               ),

lib/version_reader.dart renamed to lib/src/dart_version_reader.dart

@@ -1,8 +1,11 @@
 import 'dart:io';
 
 class DartVersionReader {
+  const DartVersionReader();
+
   String readVersion() {
     final version = Platform.version;
+
     return version.replaceAll("\"", "'");
   }
 }

lib/telemetry_manager_configuration.dart renamed to lib/src/telemetry_manager_configuration.dart

@@ -1,24 +1,26 @@
 class TelemetryManagerConfiguration {
   /// Your app's ID for Telemetry.
-  String appID;
+  final String appID;
 
   /// The Telemetrydeck domain to send signals to.
-  String? apiBaseURL;
+  final String? apiBaseURL;
 
   /// Instead of specifying a user identifier with each `send` call, you can set your user's name/email/identifier here.
   /// The `defaultUser` value will be sent with every signal.
   ///
   /// Note that just as with specifying the user identifier with the `send` call, the identifier will never leave the device.
   /// Instead it is used to create a hash, which is included in your signal to allow you to count distinct users.
-  String? defaultUser;
+  final String? defaultUser;
 
   /// Log the current status to the signal cache to the console.
-  bool? debug;
+  /// Default is `false`.
+  final bool? debug;
 
   /// If `true` any signals sent will be marked as *Testing* signals.
-  bool? testMode;
+  /// Default is `false`.
+  final bool? testMode;
 
-  TelemetryManagerConfiguration({
+  const TelemetryManagerConfiguration({
     required this.appID,
     this.apiBaseURL,
     this.defaultUser,

lib/src/telemetry_provider.dart

@@ -0,0 +1,20 @@
+import 'package:telemetrydecksdk/src/dart_version_reader.dart';
+import 'package:telemetrydecksdk/src/versions.dart';
+
+class TelemetryProvider {
+  final DartVersionReader versionReader;
+
+  const TelemetryProvider({
+    this.versionReader = const DartVersionReader(),
+  });
+
+  /// Adds Flutter specific payload attributes to outgoing signals before passing them to the native platform API.
+  /// This method will overwrite the default `telemetryClientVersion`.
+  Future<Map<String, dynamic>> enrich(Map<String, dynamic>? payload) async {
+    Map<String, dynamic> result = payload ?? {};
+    result['telemetryClientVersion'] = "Flutter $telemetryClientVersion";
+    result['dartVersion'] = versionReader.readVersion();
+
+    return result;
+  }
+}

lib/src/telemetrydecksdk.dart

@@ -0,0 +1,46 @@
+import 'dart:async';
+
+import 'package:telemetrydecksdk/src/telemetry_manager_configuration.dart';
+import 'package:telemetrydecksdk/src/telemetry_provider.dart';
+
+import 'telemetrydecksdk_platform_interface.dart';
+
+abstract class Telemetrydecksdk {
+  const Telemetrydecksdk._();
+
+  static const _telemetryProvider = TelemetryProvider();
+
+  static Future<void> start(TelemetryManagerConfiguration configuration) async {
+    await TelemetrydecksdkPlatform.instance.start(configuration);
+  }
+
+  static Future<void> stop() async {
+    await TelemetrydecksdkPlatform.instance.stop();
+  }
+
+  static Future<void> send(
+    String signalType, {
+    String? clientUser,
+    Map<String, dynamic>? additionalPayload,
+  }) async {
+    final payload = await _telemetryProvider.enrich(additionalPayload);
+
+    final stringifiedPayload = payload.map(
+      (key, value) => MapEntry(key, value.toString()),
+    );
+
+    await TelemetrydecksdkPlatform.instance.send(
+      signalType,
+      clientUser: clientUser,
+      additionalPayload: stringifiedPayload,
+    );
+  }
+
+  static Future<void> generateNewSession() async {
+    await TelemetrydecksdkPlatform.instance.generateNewSession();
+  }
+
+  static Future<void> updateDefaultUser(String clientUser) async {
+    await TelemetrydecksdkPlatform.instance.updateDefaultUser(clientUser);
+  }
+}

lib/telemetrydecksdk_method_channel.dart renamed to lib/src/telemetrydecksdk_method_channel.dart

@@ -1,6 +1,6 @@
 import 'package:flutter/foundation.dart';
 import 'package:flutter/services.dart';
-import 'package:telemetrydecksdk/telemetry_manager_configuration.dart';
+import 'package:telemetrydecksdk/src/telemetry_manager_configuration.dart';
 
 import 'telemetrydecksdk_platform_interface.dart';
 
@@ -21,13 +21,19 @@ class MethodChannelTelemetrydecksdk extends TelemetrydecksdkPlatform {
   }
 
   @override
-  Future<void> send(String signalType,
-      {String? clientUser, Map<String, String>? additionalPayload}) async {
-    await methodChannel.invokeMethod<void>('send', {
-      'signalType': signalType,
-      'clientUser': clientUser,
-      'additionalPayload': additionalPayload
-    });
+  Future<void> send(
+    String signalType, {
+    String? clientUser,
+    Map<String, String>? additionalPayload,
+  }) async {
+    await methodChannel.invokeMethod<void>(
+      'send',
+      {
+        'signalType': signalType,
+        'clientUser': clientUser,
+        'additionalPayload': additionalPayload,
+      },
+    );
   }
 
   @override

lib/telemetrydecksdk_platform_interface.dart renamed to lib/src/telemetrydecksdk_platform_interface.dart

@@ -1,5 +1,5 @@
 import 'package:plugin_platform_interface/plugin_platform_interface.dart';
-import 'package:telemetrydecksdk/telemetry_manager_configuration.dart';
+import 'package:telemetrydecksdk/src/telemetry_manager_configuration.dart';
 
 import 'telemetrydecksdk_method_channel.dart';
 
@@ -32,8 +32,11 @@ abstract class TelemetrydecksdkPlatform extends PlatformInterface {
     throw UnimplementedError('stop() has not been implemented.');
   }
 
-  Future<void> send(String signalType,
-      {String? clientUser, Map<String, String>? additionalPayload}) async {
+  Future<void> send(
+    String signalType, {
+    String? clientUser,
+    Map<String, String>? additionalPayload,
+  }) async {
     throw UnimplementedError('send() has not been implemented.');
   }