chore: Implement analytics for Checkout Components #1379

borisprimer · 2025-10-14T18:10:32Z

Overview

This PR implements a comprehensive analytics system for CheckoutComponents following the event definitions specification. The analytics system tracks all key lifecycle events throughout the checkout
and payment flow, providing crucial insights into user behavior and system performance.

What Changed

Initial Implementation

Built the complete analytics infrastructure from the ground up:

Core Components

AnalyticsEventService: HTTP-based service for sending events to analytics backend
DefaultAnalyticsInteractor: Domain layer coordinator for analytics operations
DeviceInfoProvider: Comprehensive device information extraction (model, OS version, device type)
AnalyticsEnvironmentProvider: Environment detection (production vs sandbox)
UUIDGenerator: V7 UUID generation for event IDs

Data Models

AnalyticsEventType: Enum defining all 13 trackable events
AnalyticsEventMetadata: Metadata container for optional event attributes
AnalyticsPayload: Complete payload structure for backend submission
AnalyticsSessionConfig: Session configuration with account/client token info

Event Integration

Integrated analytics tracking across the CheckoutComponents flow:

SDK initialization lifecycle (SDK_INIT_START, SDK_INIT_END)
Checkout flow tracking (CHECKOUT_FLOW_STARTED)
Payment method selection (PAYMENT_METHOD_SELECTION)
Card form interactions (PAYMENT_DETAILS_ENTERED, PAYMENT_SUBMITTED)
Payment processing (PAYMENT_PROCESSING_STARTED)
3DS challenges (PAYMENT_THREEDS)
Third-party redirects (PAYMENT_REDIRECT_TO_THIRD_PARTY)
Payment outcomes (PAYMENT_SUCCESS, PAYMENT_FAILURE)
Flow exits (PAYMENT_FLOW_EXITED)

Dependency Injection

Registered analytics components in the DI container with proper lifecycle management

Tests

Added comprehensive test coverage:

AnalyticsEventServiceTests (267 tests)
DeviceInfoProviderTests (579 tests)
AnalyticsModelsTests (409 tests)
CheckoutComponentsAnalyticsInteractorTests (217 tests)
AnalyticsEnvironmentProviderTests (234 tests)
UUIDGeneratorTests (189 tests)

Discriminated Union Refactoring (Based on Review Feedback)

Context: Following code review feedback from @NQuinn27, refactored AnalyticsEventMetadata from an optional-heavy struct to a type-safe discriminated union.

Problem: The original struct design had 10 optional fields, allowing invalid combinations like 3DS metadata on general events.

Solution: Implemented Swift enum with associated values for each event category:

public enum AnalyticsEventMetadata {
    case general(GeneralEvent)      // Checkout flow, SDK lifecycle
    case payment(PaymentEvent)      // Payment events with method + ID
    case threeDS(ThreeDSEvent)      // 3DS with provider + response
    case redirect(RedirectEvent)    // Third-party redirects with URL
}

Benefits:

✅ Type Safety: Compiler prevents invalid field combinations
✅ No Optional Pollution: Each event has only its relevant fields (no more paymentId on 3DS events)
✅ Self-Documenting: Clear what each event type requires
✅ Compile-Time Guarantees: Missing required fields = build error
✅ Future-Proof: New event types don't bloat existing ones

Event Coverage

Implemented Events ✅

SDK_INIT_START - SDK initialization begins
SDK_INIT_END - SDK initialization completes
CHECKOUT_FLOW_STARTED - UI becomes interactive
PAYMENT_METHOD_SELECTION - User selects payment method
PAYMENT_DETAILS_ENTERED - Payment details validated
PAYMENT_SUBMITTED - User taps Pay
PAYMENT_PROCESSING_STARTED - Payment processing begins
PAYMENT_REDIRECT_TO_THIRD_PARTY - Redirect to third-party initiated
PAYMENT_THREEDS - 3DS challenge presented
PAYMENT_SUCCESS - Payment completes successfully
PAYMENT_FAILURE - Payment fails
PAYMENT_FLOW_EXITED - User exits checkout

Not Implemented ⏸️

PAYMENT_REATTEMPTED - Requires retry feature (not yet available)

Technical Details

Architecture

Clean Architecture with domain/data/presentation layers
Dependency injection for testability
Protocol-based design for flexibility
AsyncStream for state observation

Event Flow

SDK Init → Checkout Ready → Payment Method Selection →
Details Entry → Submit → Processing → [3DS/Redirect] →
Success/Failure → Exit

Metadata Schema

All events include:

Required: id, eventName, timestamp, checkoutSessionId, clientSessionId, sdkType, sdkVersion, primerAccountId
Optional: userLocale, paymentMethod, paymentId, redirectDestinationUrl, threedsProvider, threedsResponse, device, deviceType

Testing

✅ 1,895+ new unit tests added
✅ All analytics components have 100% test coverage
✅ Event metadata validation tests included
✅ Device info extraction tested across all iOS versions

References

📋 Ticket: ACC-5729
📖 Spec: Event Definitions
🏗️ Architecture: CheckoutComponents (iOS 15+)

Notes

Events follow snake_case naming convention per documentation
Device information auto-filled by analytics service
Analytics gracefully handles nil container scenarios

github-actions · 2025-10-14T18:11:44Z

	Warnings
⚠️	> Pull Request size seems relatively large. If this Pull Request contains multiple changes, please split each into separate PR will helps faster, easier review.

Generated by 🚫 Danger Swift against dff6019

github-actions · 2025-10-14T18:27:02Z

Appetize link: https://appetize.io/app/qhkawl3zzxsmmzgz5dcktoxkdq

Enhanced all CheckoutComponents analytics events to include required and optional metadata fields according to the event definitions spec: - Add userLocale (Locale.current.identifier) to all analytics events - Extract paymentId and paymentMethod from PrimerError.paymentFailed for PAYMENT_FAILURE events - Include paymentMethod context in card form analytics events (PAYMENT_DETAILS_ENTERED, PAYMENT_SUBMITTED, PAYMENT_PROCESSING_STARTED) - Add paymentMethod to PAYMENT_THREEDS event from token data - Add userLocale to PAYMENT_REDIRECT_TO_THIRD_PARTY event Changed files: - DefaultCheckoutScope.swift: Enhanced state tracking with metadata extraction helper for failure cases - CheckoutSDKInitializer.swift: Added userLocale to SDK init events - DefaultCardFormScope.swift: Added metadata to card form events - DefaultPaymentMethodSelectionScope.swift: Added userLocale - HeadlessRepositoryImpl.swift: Enhanced 3DS and redirect event metadata Note: PAYMENT_REATTEMPTED event not implemented as retry feature does not exist yet.

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Data/Models/AnalyticsEventMetadata.swift

borisprimer · 2025-10-16T13:58:06Z

Sources/PrimerSDK/Classes/CheckoutComponents/Internal/Tokens/DesignTokensManager.swift

Not related to this task. Just a quick SwiftLint warning cleanup.

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Utils/DeviceInfoProvider.swift

NQuinn27 · 2025-10-16T14:29:46Z

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Utils/DeviceInfoProvider.swift

@@ -0,0 +1,326 @@
+//


We have a very similar file in the SDK UIDeviceExtension.swift. May be premature, but if we need both, this could be in a shared utils space

I know, I separated it intentionally because of future (let's hear from Henry) modularisation. But to add my 2 cents, the first thing that should be extracted to some kind of Util module is LogReporter, DeviceInfoProvider, and similar.

I think we should point any device info calls to the existing Device and Model objects and modularise that one when the time comes and avoid duplicating here.

Device info it's often, but not strictly the domain of analytics. Any analytics-specific properties can, in their domain, extend the current Device.swift or Model.swift

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Utils/UUIDGenerator.swift

…ore tests

.../PrimerSDK/Classes/CheckoutComponents/Internal/Presentation/Scope/DefaultCardFormScope.swift

Sources/PrimerSDK/Classes/CheckoutComponents/Internal/Services/CheckoutSDKInitializer.swift

henry-cooper-primer · 2025-10-16T16:43:48Z

...ces/PrimerSDK/Classes/CheckoutComponents/Analytics/Data/Services/AnalyticsEventService.swift

+
+/// Core analytics event service responsible for constructing and sending events.
+/// Thread-safe actor that maintains session state and handles HTTP communication.
+actor AnalyticsEventService: CheckoutComponentsAnalyticsServiceProtocol, LogReporter {


This object has a few too many responsibilities. You could certainly delegate the constructing of the payload, networking out of here and perhaps also the buffering

henry-cooper-primer · 2025-10-16T16:53:50Z

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Utils/DeviceInfoProvider.swift

@@ -0,0 +1,326 @@
+//


I think we should point any device info calls to the existing Device and Model objects and modularise that one when the time comes and avoid duplicating here.

Device info it's often, but not strictly the domain of analytics. Any analytics-specific properties can, in their domain, extend the current Device.swift or Model.swift

henry-cooper-primer · 2025-10-16T17:00:25Z

.../PrimerSDK/Classes/CheckoutComponents/Internal/Presentation/Scope/DefaultCheckoutScope.swift

+        switch state {
+        case .ready:
+            // Checkout flow is now interactive
+            await analyticsInteractor?.trackEvent(.checkoutFlowStarted, metadata: .general(GeneralEvent()))


Associated values can have default values, eg case general(GeneralEvent = GeneralEvent()) so you could just do metadata: .general()

henry-cooper-primer · 2025-10-16T17:11:51Z

...PrimerSDK/Classes/CheckoutComponents/Internal/Data/Repositories/HeadlessRepositoryImpl.swift

+
+        do {
+            guard let container = await DIContainer.current else {
+                // DI Container not available


There's a few superfluous comments here

henry-cooper-primer · 2025-10-16T17:13:45Z

...PrimerSDK/Classes/CheckoutComponents/Internal/Data/Repositories/HeadlessRepositoryImpl.swift

+    private func isLikelyURL(_ string: String) -> Bool {
+        guard !string.isEmpty else { return false }
+        let lowercased = string.lowercased()
+        return lowercased.hasPrefix("http://") || lowercased.hasPrefix("https://")


private func isLikelyURL(_ string: String) -> Bool { ["http://", "https://"].contains { string.lowercased().hasPrefix($0) } }

henry-cooper-primer · 2025-10-16T17:14:37Z

...PrimerSDK/Classes/CheckoutComponents/Internal/Data/Repositories/HeadlessRepositoryImpl.swift

+        }
+    }
+
+    private func resolveThreeDSProvider() -> String? {


probably more appropriate as a computed property

henry-cooper-primer · 2025-10-16T17:19:56Z

...PrimerSDK/Classes/CheckoutComponents/Internal/Data/Repositories/HeadlessRepositoryImpl.swift

    private var settingsService: Any?

+    /// Analytics interactor for tracking events (iOS 15.0+ only)
+    private var analyticsInteractor: Any?


Why doesn't this have a type?

Slip. Good catch.

gitguardian · 2025-10-17T15:24:34Z

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.

^{_{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}}

henry-cooper-primer · 2025-10-20T09:26:11Z

...SDK/Classes/CheckoutComponents/Analytics/Domain/Interactors/DefaultAnalyticsInteractor.swift

+    func trackEvent(_ eventType: AnalyticsEventType, metadata: AnalyticsEventMetadata?) async {
+        // Launch a child task to keep fire-and-forget behavior without leaving structured concurrency
+        // This prevents blocking the caller even if the service is busy
+        let eventMetadata = metadata


is this assignment necessary?

henry-cooper-primer · 2025-10-20T09:31:41Z

Sources/PrimerSDK/Classes/Extensions & Utilities/UIDeviceExtension.swift

+        } else if ["i386", "x86_64", "arm64"].contains(identifier) {
+            // Simulator - check what device it's simulating
+            if let simModelCode = ProcessInfo().environment["SIMULATOR_MODEL_IDENTIFIER"] {
+                if simModelCode.hasPrefix("iPhone") {


This identical-to-above logic could be extracted into a private helper

henry-cooper-primer · 2025-10-20T09:32:13Z

Tests/Primer/Analytics/AnalyticsEventBufferTests.swift

+    func testBuffer_AddsEventToBuffer() async {
+        // Given
+        let eventType = AnalyticsEventType.sdkInitStart
+        let metadata: AnalyticsEventMetadata = .general(GeneralEvent())


can be shortened to use the default value

henry-cooper-primer · 2025-10-20T09:34:37Z

Tests/Primer/Analytics/AnalyticsEventBufferTests.swift

A lot of the tests in this and the next files aren't asserting anything, they are just firing the events, is this deliberate?

These are intentional smoke tests for fire-and-forget patterns. This is deliberate but not ideal. Let me improve it...

henry-cooper-primer · 2025-10-20T09:36:56Z

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Utils/UUIDGenerator.swift

There is a static extension on string uuid that avoids having to create a new object which maybe worth a consideration here

- Remove unnecessary metadata variable assignment in DefaultAnalyticsInteractor - Simplify AnalyticsEventBufferTests to use default nil metadata value - Replace UUIDGenerator with existing String.uuid extension - Extract duplicate device type checking logic into private helper method in UIDeviceExtension - Add proper assertions to AnalyticsEventServiceTests"

sonarqubecloud · 2025-10-20T13:05:48Z

Quality Gate failed

Failed conditions
57.4% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

borisprimer self-assigned this Oct 14, 2025

borisprimer requested review from a team as code owners October 14, 2025 18:10

borisprimer added the do not review label Oct 14, 2025

borisprimer changed the base branch from master to bn/feature/checkout-components October 14, 2025 18:10

borisprimer marked this pull request as draft October 14, 2025 18:18

Implement analytics for checkout components

ea4d456

borisprimer force-pushed the bn/chore/ACC-5729-cc-analytics branch from 0372335 to ea4d456 Compare October 14, 2025 18:28

borisprimer removed the do not review label Oct 16, 2025

borisprimer marked this pull request as ready for review October 16, 2025 13:36

borisprimer requested review from aabdaab, dariusparteneprimer, henry-cooper-primer and marjaimate October 16, 2025 13:50

NQuinn27 reviewed Oct 16, 2025

View reviewed changes

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Data/Models/AnalyticsEventMetadata.swift Show resolved Hide resolved

borisprimer commented Oct 16, 2025

View reviewed changes

marjaimate reviewed Oct 16, 2025

View reviewed changes

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Utils/DeviceInfoProvider.swift Outdated Show resolved Hide resolved

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Utils/DeviceInfoProvider.swift Outdated Show resolved Hide resolved

marjaimate approved these changes Oct 16, 2025

View reviewed changes

NQuinn27 reviewed Oct 16, 2025

View reviewed changes

Sources/PrimerSDK/Classes/CheckoutComponents/Analytics/Utils/UUIDGenerator.swift Outdated Show resolved Hide resolved

Remove code duplication, improve DI pattern implementation, and add m…

d03400e

…ore tests

NQuinn27 reviewed Oct 16, 2025

View reviewed changes

.../PrimerSDK/Classes/CheckoutComponents/Internal/Presentation/Scope/DefaultCardFormScope.swift Outdated Show resolved Hide resolved

Discriminated union refactoring

3c13141

NQuinn27 reviewed Oct 16, 2025

View reviewed changes

Sources/PrimerSDK/Classes/CheckoutComponents/Internal/Services/CheckoutSDKInitializer.swift Outdated Show resolved Hide resolved

Remove obsolete code

4fe8339

borisprimer force-pushed the bn/chore/ACC-5729-cc-analytics branch from 1d83746 to 622c18b Compare October 16, 2025 16:18

Inject analytics config provider into checkout initializer

540eafd

borisprimer force-pushed the bn/chore/ACC-5729-cc-analytics branch from 622c18b to 540eafd Compare October 16, 2025 16:18

borisprimer requested a review from NQuinn27 October 16, 2025 16:19

primer-io deleted a comment from gitguardian bot Oct 16, 2025

henry-cooper-primer reviewed Oct 16, 2025

View reviewed changes

NQuinn27 approved these changes Oct 17, 2025

View reviewed changes

Use types

9a6a09e

Update as per Henry's comments

239376c

borisprimer requested review from NQuinn27 and henry-cooper-primer October 17, 2025 16:50

henry-cooper-primer reviewed Oct 20, 2025

View reviewed changes

NQuinn27 approved these changes Oct 20, 2025

View reviewed changes

henry-cooper-primer approved these changes Oct 20, 2025

View reviewed changes

Improve test coverage

dff6019

chore: Implement analytics for Checkout Components #1379

Are you sure you want to change the base?

chore: Implement analytics for Checkout Components #1379

Conversation

borisprimer commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

What Changed

Initial Implementation

Core Components

Data Models

Event Integration

Dependency Injection

Tests

Discriminated Union Refactoring (Based on Review Feedback)

Event Coverage

Implemented Events ✅

Not Implemented ⏸️

Technical Details

Architecture

Event Flow

Metadata Schema

Testing

References

Notes

Uh oh!

github-actions bot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 14, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gitguardian bot commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

️✅ There are no secrets present in this pull request anymore.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Oct 20, 2025

borisprimer commented Oct 14, 2025 •

edited

Loading

github-actions bot commented Oct 14, 2025 •

edited

Loading

gitguardian bot commented Oct 17, 2025 •

edited

Loading