From b77a05ce1ee4189061108a78f30a39f26114015f Mon Sep 17 00:00:00 2001 From: Greg Leonard <45019882+greg-el@users.noreply.github.com> Date: Wed, 13 Sep 2023 16:33:08 +0100 Subject: [PATCH] Add API to decorate link with user/session info --- Sources/Core/Tracker/Tracker.swift | 92 +++++++++++++- .../Core/Tracker/TrackerControllerImpl.swift | 8 ++ .../Controllers/TrackerController.swift | 54 +++++++++ .../CrossDeviceParameterConfiguration.swift | 36 ++++++ Tests/TestLinkDecorator.swift | 113 ++++++++++++++++++ Tests/Utils/String.swift | 19 +++ 6 files changed, 321 insertions(+), 1 deletion(-) create mode 100644 Sources/Snowplow/Tracker/CrossDeviceParameterConfiguration.swift create mode 100644 Tests/TestLinkDecorator.swift create mode 100644 Tests/Utils/String.swift diff --git a/Sources/Core/Tracker/Tracker.swift b/Sources/Core/Tracker/Tracker.swift index ee9dffa75..bf6bbe056 100644 --- a/Sources/Core/Tracker/Tracker.swift +++ b/Sources/Core/Tracker/Tracker.swift @@ -13,6 +13,24 @@ import Foundation +extension String { + func toBase64() -> String { + var encoded = Data(self.utf8).base64EncodedString() + // We need URL safe with no padding. Since there is no built-in way to do this, we transform + // the encoded payload to make it URL safe by replacing chars that are different in the URL-safe + // alphabet. Namely, 62 is - instead of +, and 63 _ instead of /. + // See: https://tools.ietf.org/html/rfc4648#section-5 + encoded = encoded + .replacingOccurrences(of: "/", with: "_") + .replacingOccurrences(of: "+", with: "-") + + // There is also no padding since the length is implicitly known. + encoded = encoded.trimmingCharacters(in: CharacterSet(charactersIn: "=")) + + return encoded + } +} + func uncaughtExceptionHandler(_ exception: NSException) { let symbols = exception.callStackSymbols let stacktrace = "Stacktrace:\n\(symbols)" @@ -43,7 +61,6 @@ class Tracker: NSObject { private var builderFinished = false - /// The object used for sessionization, i.e. it characterizes user activity. private(set) var session: Session? /// Previous screen view state. @@ -385,6 +402,79 @@ class Tracker: NSObject { emitter.resumeTimer() session?.startChecker() } + + enum PropertyError: Error { + case notSet(_ message: String) + } + + /// - Returns: The associated value of the extended parameter if enabled and set in the tracker, an empty string if the parameter is not enabled, or nil if parameter is enabled without an avilable value + func tryExtendedParameter(_ extendedParameterSet: Bool, _ value: String?) -> String? { + switch (extendedParameterSet, value) { + case (true, .some(let val)): + return val + case (true, .none): + return nil + case (false, _): + return "" + } + } + + @objc func decorateLink(_ url: URL, extendedParameters: CrossDeviceParameterConfiguration? = nil) -> URL? { + var userId: String + switch self.session { + case .none: + logError(message: "\(url) could not be decorated as session.userId is nil") + return nil + case .some(let s): + userId = s.userId + } + + let extendedParameters = extendedParameters ?? CrossDeviceParameterConfiguration() + + guard let sessionId = tryExtendedParameter(extendedParameters.sessionId, self.session?.state?.sessionId) else { + logError(message: "sessionId not set") + return nil + } + + guard let sourceId = tryExtendedParameter(extendedParameters.sourceId, self.appId) else { + logError(message: "appId not set") + return nil + } + + guard let sourcePlatform = tryExtendedParameter(extendedParameters.sourcePlatform, devicePlatformToString(self.devicePlatform)) else { + logError(message: "platform not set") + return nil + } + + guard let subjectUserId = tryExtendedParameter(extendedParameters.subjectUserId, self.subject?.userId) else { + logError(message: "subjectUserId not set") + return nil + } + + let reason = extendedParameters.reason ?? "" + + let spParameters = [ + userId, + String(Int(Date().timeIntervalSince1970 * 1000)), + sessionId, + subjectUserId.toBase64(), + sourceId.toBase64(), + sourcePlatform, + reason.toBase64() + ].joined(separator: ".").trimmingCharacters(in: ["."]) + + var components = URLComponents(url: url, resolvingAgainstBaseURL: false) + if var existingSp = components?.queryItems?.first(where: { $0.name == "_sp" }) { + existingSp.value = spParameters + } else { + var queryItems = components?.queryItems ?? [] + queryItems.append(URLQueryItem(name: "_sp", value: spParameters)) + components?.queryItems = queryItems + } + + return components?.url + } + // MARK: - Notifications management diff --git a/Sources/Core/Tracker/TrackerControllerImpl.swift b/Sources/Core/Tracker/TrackerControllerImpl.swift index afc0a5f90..3f90e7520 100644 --- a/Sources/Core/Tracker/TrackerControllerImpl.swift +++ b/Sources/Core/Tracker/TrackerControllerImpl.swift @@ -73,6 +73,14 @@ class TrackerControllerImpl: Controller, TrackerController { func track(_ event: Event) -> UUID? { return tracker.track(event) } + + func decorateLink(_ url: URL) -> URL? { + return tracker.decorateLink(url) + } + + func decorateLink(_ url: URL, extendedParameters: CrossDeviceParameterConfiguration) -> URL? { + return tracker.decorateLink(url, extendedParameters: extendedParameters) + } // MARK: - Properties' setters and getters diff --git a/Sources/Snowplow/Controllers/TrackerController.swift b/Sources/Snowplow/Controllers/TrackerController.swift index 3c5fcdf4c..735a12e10 100644 --- a/Sources/Snowplow/Controllers/TrackerController.swift +++ b/Sources/Snowplow/Controllers/TrackerController.swift @@ -75,4 +75,58 @@ public protocol TrackerController: TrackerConfigurationProtocol { /// The tracker will start tracking again. @objc func resume() + /// Adds user and session information to a URL. + /// + /// For example, calling decorateLink on `appSchema://path/to/page` will return: + /// + /// `appSchema://path/to/page?_sp=domainUserId.timestamp.sessionId..sourceId.` + /// + /// Filled by this method: + /// - `domainUserId`: Value of ``SessionController.userId`` + /// - `timestamp`: ms precision epoch timestamp + /// - `sessionId`: Value of ``SessionController.sessionId`` + /// - `sourceId`: Value of ``Tracker.appId`` + /// + /// - Parameter uri The URI to add the query string to + /// + /// - Returns Optional URL + /// - null if ``SnowplowTracker/SessionController/userId`` is null from `sessionContext(false)` being passed in ``TrackerConfiguration`` + /// - otherwise, decorated URL + @objc + func decorateLink(_ url: URL) -> URL? + /// Adds user and session information to a URL. + /// + /// For example, calling decorateLink on `appSchema://path/to/page` with all extended parameters enabled will return: + /// + /// `appSchema://path/to/page?_sp=domainUserId.timestamp.sessionId.subjectUserId.sourceId.platform.reason` + /// + /// Required (auto-filled by this method): + /// - `domainUserId`: Value of ``SessionController.userId`` + /// - `timestamp`: ms precision epoch timestamp + /// + /// Optional: + /// - `sessionId`: Value of ``SessionController.sessionId`` + /// - `subjectUserId`: Value of ``Subject.userId`` + /// - `sourceId`: Value of ``Tracker.appId`` + /// - `platform`: Value of ``Tracker.platform`` + /// - `reason`: Value of ``CrossDeviceParameterConfiguration/reason`` + /// + /// + /// - Parameter url The URL to add the query string to + /// - Parameter extendedParameters Any optional parameters to include in the query string. + /// + /// Optional parameters are: + /// - sessionId (``CrossDeviceParameterConfiguration.sessionId``) + /// - subjectUserId (``CrossDeviceParameterConfiguration.subjectUserId``) + /// - appId (``CrossDeviceParameterConfiguration.sourceId``) + /// - platform (``CrossDeviceParameterConfiguration.sourcePlatform``) + /// - reason (``CrossDeviceParameterConfiguration.reason``) + /// + /// Fields enabled by default are sourceId and sessionId + /// + /// - Returns Optional URL + /// - null if ``SnowplowTracker/SessionController/userId`` is null from `sessionContext(false)` being passed in ``TrackerConfiguration`` + /// - otherwise, decorated URL + @objc + func decorateLink(_ url: URL, extendedParameters: CrossDeviceParameterConfiguration) -> URL? } diff --git a/Sources/Snowplow/Tracker/CrossDeviceParameterConfiguration.swift b/Sources/Snowplow/Tracker/CrossDeviceParameterConfiguration.swift new file mode 100644 index 000000000..a1ca15fe7 --- /dev/null +++ b/Sources/Snowplow/Tracker/CrossDeviceParameterConfiguration.swift @@ -0,0 +1,36 @@ +// Copyright (c) 2013-2023 Snowplow Analytics Ltd. All rights reserved. +// +// This program is licensed to you under the Apache License Version 2.0, +// and you may not use this file except in compliance with the Apache License +// Version 2.0. You may obtain a copy of the Apache License Version 2.0 at +// http://www.apache.org/licenses/LICENSE-2.0. +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the Apache License Version 2.0 is distributed on +// an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either +// express or implied. See the Apache License Version 2.0 for the specific +// language governing permissions and limitations there under. + +import Foundation + +public class CrossDeviceParameterConfiguration : NSObject { + var sessionId: Bool + var subjectUserId: Bool + var sourceId: Bool + var sourcePlatform: Bool + var reason: String? + + init( + sessionId: Bool = true, + subjectUserId: Bool = false, + sourceId: Bool = true, + sourcePlatform: Bool = false, + reason: String? = nil + ) { + self.sessionId = sessionId + self.subjectUserId = subjectUserId + self.sourceId = sourceId + self.sourcePlatform = sourcePlatform + self.reason = reason + } +} diff --git a/Tests/TestLinkDecorator.swift b/Tests/TestLinkDecorator.swift new file mode 100644 index 000000000..2309fac2f --- /dev/null +++ b/Tests/TestLinkDecorator.swift @@ -0,0 +1,113 @@ +// Copyright (c) 2013-2023 Snowplow Analytics Ltd. All rights reserved. +// +// This program is licensed to you under the Apache License Version 2.0, +// and you may not use this file except in compliance with the Apache License +// Version 2.0. You may obtain a copy of the Apache License Version 2.0 at +// http://www.apache.org/licenses/LICENSE-2.0. +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the Apache License Version 2.0 is distributed on +// an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either +// express or implied. See the Apache License Version 2.0 for the specific +// language governing permissions and limitations there under. + +import XCTest +@testable import SnowplowTracker + +class TestLinkDecorator: XCTestCase { + let replacements = [".", "/", "?"] + func matches(for regex: String, in text: String) { + var regex = "^\(regex)$" + + do { + for replacement in replacements { + regex = regex.replacingOccurrences(of: replacement, with: "\\" + replacement) + } + let pattern = try NSRegularExpression(pattern: regex) + let nsString = text as NSString + let results = pattern.matches(in: text, range: NSRange(location: 0, length: nsString.length)) + let fullMatch = results.map { nsString.substring(with: $0.range)} + if (fullMatch.count == 0) { + XCTFail("URL does not match pattern:\n\(text)\n\(regex)") + } + XCTAssertEqual(fullMatch.count, 1) + } catch let error { + print("invalid regex: \(error.localizedDescription)") + } + } + + func testArgs() { + let tracker = getTracker() + let _ = tracker.track(ScreenView(name: "test")) + + let link = URL(string: "https://example.com")! + let userId = tracker.session!.userId! + let sessionId = tracker.session!.sessionId! + let epoch = "\\d{13}" + let appId = tracker.appId.toBase64() + let subjectUserId = tracker.subject!.userId!.toBase64() + let platform = devicePlatformToString(tracker.devicePlatform)! + let reason = "reason" + let reasonb64 = reason.toBase64() + + let testCases = [ + // All false + ( + config: CrossDeviceParameterConfiguration(sessionId: false, sourceId: false), + expected: "https://example.com?_sp=\(userId).\(epoch)" + ) + , + // Default + ( + config: CrossDeviceParameterConfiguration(), + expected: "https://example.com?_sp=\(userId).\(epoch).\(sessionId)..\(appId)" + ), + ( + config: CrossDeviceParameterConfiguration(subjectUserId: true), + expected: "https://example.com?_sp=\(userId).\(epoch).\(sessionId).\(subjectUserId).\(appId)" + ), + ( + config: CrossDeviceParameterConfiguration(subjectUserId: true, sourcePlatform: true), + expected: "https://example.com?_sp=\(userId).\(epoch).\(sessionId).\(subjectUserId).\(appId).\(platform)" + ), + ( + config: CrossDeviceParameterConfiguration(subjectUserId: true, sourcePlatform: true, reason: reason), + expected: "https://example.com?_sp=\(userId).\(epoch).\(sessionId).\(subjectUserId).\(appId).\(platform).\(reasonb64)" + ), + ( + config: CrossDeviceParameterConfiguration(sessionId: false, sourceId: false, reason: reason), + expected: "https://example.com?_sp=\(userId).\(epoch).....\(reasonb64)" + ) + ] + + for (config, expected) in testCases { + matches( + for: expected, + in: tracker.decorateLink(link, extendedParameters: config)!.absoluteString + ) + } + } + + func getTracker() -> TrackerController { + let networkConnection = MockNetworkConnection(requestOption: .post, statusCode: 200) + let emitterConfig = EmitterConfiguration() + emitterConfig.eventStore = MockEventStore() + emitterConfig.bufferOption = .single + let networkConfig = NetworkConfiguration(networkConnection: networkConnection) + + return createTracker(networkConfig: networkConfig, emitterConfig: emitterConfig) + } + + private func createTracker(networkConfig: NetworkConfiguration, emitterConfig: EmitterConfiguration) -> TrackerController { + let trackerConfig = TrackerConfiguration().sessionContext(true) + trackerConfig.installAutotracking = false + trackerConfig.screenViewAutotracking = false + trackerConfig.lifecycleAutotracking = false + let subjectConfig = SubjectConfiguration().userId("userId") + + let namespace = "testEmitter" + String(describing: Int.random(in: 0..<100)) + return Snowplow.createTracker(namespace: namespace, + network: networkConfig, + configurations: [trackerConfig, emitterConfig, subjectConfig])! + } +} diff --git a/Tests/Utils/String.swift b/Tests/Utils/String.swift new file mode 100644 index 000000000..25933262e --- /dev/null +++ b/Tests/Utils/String.swift @@ -0,0 +1,19 @@ +import Foundation + +extension String { + func toBase64() -> String { + var encoded = Data(self.utf8).base64EncodedString() + // We need URL safe with no padding. Since there is no built-in way to do this, we transform + // the encoded payload to make it URL safe by replacing chars that are different in the URL-safe + // alphabet. Namely, 62 is - instead of +, and 63 _ instead of /. + // See: https://tools.ietf.org/html/rfc4648#section-5 + encoded = encoded + .replacingOccurrences(of: "/", with: "_") + .replacingOccurrences(of: "+", with: "-") + + // There is also no padding since the length is implicitly known. + encoded = encoded.trimmingCharacters(in: CharacterSet(charactersIn: "=")) + + return encoded + } +}