Add support for sessions

README.md

@@ -64,3 +64,42 @@ Telemetry Manager will automatically send a base payload with these keys:
 - targetEnvironment
 
 NOTE: Telemetry Manager will *not* send any signals if you are in DEBUG Mode. You can override this by setting `configuration.telemetryAllowDebugBuilds = true` on your `TelemetryManagerConfiguration` instance.
+
+## Sessions
+
+With each Signal, the client sends a hash of your user ID as well as a *session ID*. This gets automatically generated when the client is initialized, so if you do nothing, you'll get a new session each time your app is started from cold storage.
+
+If you want to manually start a new sesion, call `TelemetryManager.generateNewSession()`. For example, with mobile apps, you usually want to start a new session when the app returns from background. In Swiftui, you can do this by listening to the `scenePhase` property of a your `App`. Here's how to do that in your `Your_App.swift`, the main entry point into you app:
+
+```swift
+import SwiftUI
+import TelemetryClient
+
+@main
+struct TelemetryTestApp: App {
+    var body: some Scene {
+
+        // (1) Add the scenePhase env var to your App
+        @Environment(\.scenePhase) var scenePhase
+
+        WindowGroup {
+            ContentView()
+        }
+
+        // (2) Generate a new session whenever the scenePhase returns back to "active", i.e. the app returns from background
+        .onChange(of: scenePhase) { newScenePhase in
+            if newScenePhase == .active {
+                TelemetryManager.generateNewSession()
+            }
+        }
+    }
+
+    init() {
+        // Note: Do not add this code to `WindowGroup.onAppear`, which will be called 
+        //       *after* your window has been initialized, and might lead to out initialization
+        //       occurring too late.
+        let configuration = TelemetryManagerConfiguration(appID: "<YOUR-APP-ID>")
+        TelemetryManager.initialize(with: configuration)
+    }
+}
+```

Sources/TelemetryClient/TelemetryClient.swift

@@ -25,6 +25,7 @@ public final class TelemetryManagerConfiguration {
     public let telemetryAppID: String
     public let telemetryServerBaseURL: URL
     public var telemetryAllowDebugBuilds: Bool = false
+    public var sessionID: UUID = UUID()
 
     public init(appID: String, baseURL: URL? = nil) {
         telemetryAppID = appID
@@ -53,6 +54,18 @@ public class TelemetryManager {
 
         return telemetryManager
     }
+
+    /// Generate a new Session ID for all new Signals, in order to begin a new session instead of continuing the old one.
+    ///
+    /// It is recommended to call this function when returning from background. If you never call it, your session lasts until your
+    /// app is killed and the user restarts it. 
+    public static func generateNewSession() {
+        TelemetryManager.shared.generateNewSession()
+    }
+
+    public func generateNewSession() {
+        configuration.sessionID = UUID()
+    }
 
     public func send(_ signalType: TelemetrySignalType, for clientUser: String? = nil, with additionalPayload: [String: String] = [:]) {
         // Do not send telemetry in DEBUG mode
@@ -85,7 +98,12 @@ public class TelemetryManager {
                 "targetEnvironment": targetEnvironment,
             ].merging(additionalPayload, uniquingKeysWith: { _, last in last })
 
-            let signalPostBody = SignalPostBody(type: "\(signalType)", clientUser: sha256(str: clientUser ?? defaultUserIdentifier), payload: payLoad)
+            let signalPostBody = SignalPostBody(
+                type: "\(signalType)",
+                clientUser: sha256(str: clientUser ?? defaultUserIdentifier),
+                sessionID: configuration.sessionID.uuidString,
+                payload: payLoad
+            )
 
             urlRequest.httpBody = try! JSONEncoder().encode(signalPostBody)
 
@@ -110,6 +128,7 @@ public class TelemetryManager {
     private struct SignalPostBody: Codable {
         let type: String
         let clientUser: String
+        let sessionID: String
         let payload: [String: String]?
     }
 }