Analytics

The SDK emits structured analytics events when important actions or states occur (lifecycle, interactions, tokenisation, 3DS, authorisation, errors, and more). You handle them in one place: CheckoutConfig.analyticsEvent.

Analytics help you:

• See the full journey from field interaction through tokenisation, 3DS (when enabled), and authorisation.
• Optimise conversion by correlating abandonment, validation-style signals, and errors with funnel steps.
• Feed data into your analytics or CRM tools (subject to privacy and consent).

Pass a closure when you build CheckoutConfig. The SDK calls it from checkout and component code (including submitAsync()). Keep the closure fast; move network I/O or heavy work to Task.detached or your own queue so you don't block the main thread.

import PXPCheckoutSDK

let checkoutConfig = CheckoutConfig(
    environment: .test,
    session: sessionData,
    transactionData: transactionData,
    merchantShopperId: "shopper-id",
    ownerType: "MerchantGroup",
    ownerId: "your-owner-id",
    analyticsEvent: { event in
        switch event {
        case let e as ComponentErrorAnalyticsEvent:
            print(e.errorCode ?? "", e.errorMessage)
        case let e as ComponentInteractionAnalyticsEvent:
            print(e.componentType, e.interactionType)
        case let e as PaymentLifecycleAnalyticsEvent:
            print(e.eventName, e.transactionId)
        case let e as RetryablePaymentLifecycleAnalyticsEvent:
            print(e.eventName, e.isRetry)
        default:
            print(event.eventName)
        }

        Task.detached(priority: .utility) {
            await forwardToYourPipeline(event)
        }
    }
)

let pxpCheckout = try PxpCheckout.initialize(config: checkoutConfig)

Use switch / as? on concrete subclasses so you can read typed properties. Tokenisation milestones (PreTokenizationAnalyticsEvent, PostTokenizationAnalyticsEvent) extend PaymentLifecycleAnalyticsEvent (componentType, transactionId). 3DS and authorisation milestones extend RetryablePaymentLifecycleAnalyticsEvent (componentType, transactionId, isRetry). Those two bases are sibling subclasses of BaseAnalyticsEvent, not parent and child.

Apple Pay and PayPal define additional event types in PXPCheckoutSDK; the table focuses on card-related names.

Each row is the string in event.eventName. Every event also includes eventName, sessionId, and timestamp from BaseAnalyticsEvent.

Property names match the Swift types (for example TokenListFillCVVTimerAnalyticsEvent uses startTimeStamp / endTimeStamp).

BaseAnalyticsEvent subclasses conform to Encodable. Use JSONEncoder with dateEncodingStrategy = .iso8601 and encode the runtime subclass if you need full payloads for an API.

func encodeEvent(_ event: BaseAnalyticsEvent) -> Data? {
    let encoder = JSONEncoder()
    encoder.dateEncodingStrategy = .iso8601
    // Cast to each concrete type you persist — encoding as BaseAnalyticsEvent
    // does not include subclass-specific keys.
    switch event {
    case let e as ComponentErrorAnalyticsEvent: return try? encoder.encode(e)
    case let e as PaymentLifecycleAnalyticsEvent: return try? encoder.encode(e)
    case let e as RetryablePaymentLifecycleAnalyticsEvent: return try? encoder.encode(e)
    default: return nil
    }
}

For Firebase Analytics, names and parameter lengths are limited — see Firebase event limits. Truncate errorMessage / messageContent (for example to 100 characters) and normalise eventName to allowed characters before Analytics.logEvent.

• Filter noisy events in production if you only care about errors and payment milestones.
• Never let a logging failure break checkout — wrap third-party SDK calls and swallow or degrade gracefully.
• Obtain consent where required; avoid exporting data that could identify users when combined with other sources.
• Don't log PAN/CVC; review messageContent and errorMessage before they leave the device.