Analytics

Get actionable, trackable data instantly to drive better decisions and performance.

Overview

Analytics events are structured data objects that are automatically triggered when significant actions or states occur within the drop-in. These allow you to monitor every aspect of the payment journey across cards, PayPal, Apple Pay, Paze, and other enabled payment methods.

Analytics events allow you to:

Gain transparency with native transaction tracking in PXP reports.
Optimise conversion rates and reduce drop-offs, thanks to actionable insights.
Feed real-time data into your analytics and CRM systems.

Consume an event

Analytics events should be consumed in the analyticsEvent callback when initialising Drop-in.

Basic example

The following example wires analyticsEvent on CheckoutDropInConfig:

import PXPCheckoutSDK

let config = CheckoutDropInConfig(
    environment: .test,
    session: sessionData,
    transactionData: DropInTransactionData(
        amount: Decimal(string: "99.99") ?? 0,
        currency: "USD",
        entryType: .ecom,
        intent: DropInTransactionIntentData(
            card: .authorisation,
            paypal: .authorisation
        ),
        merchantTransactionId: UUID().uuidString,
        merchantTransactionDate: { Date() }
    ),
    merchantShopperId: "shopper-001",
    ownerId: "MERCHANT-1",
    onGetShopper: { async in
        TransactionShopper(id: "shopper-001")
    },
    analyticsEvent: { event in
        print("Analytics event: \(event.eventName)")
        
        // Send to your analytics platform
        sendToAnalyticsPlatform(event)
    },
    onSuccess: { result in
        verifyPaymentOnBackend(result)
    },
    onError: { paymentMethod, error in
        print("Payment failed: \(error.errorMessage)")
    }
)

Typed event handling

Since event-specific fields live on subclasses, cast to the concrete type for typed access:

analyticsEvent: { event in
    switch event {
    case let componentEvent as ComponentInteractionAnalyticsEvent:
        print("Component interaction:")
        print("- Type: \(componentEvent.componentType)")
        print("- Interaction: \(componentEvent.interactionType.rawValue)")
        print("- ID: \(componentEvent.componentId)")
        
    case let errorEvent as ComponentErrorAnalyticsEvent:
        print("Component error:")
        print("- Code: \(errorEvent.errorCode ?? "unknown")")
        print("- Message: \(errorEvent.errorMessage)")
        print("- Component ID: \(errorEvent.componentId)")
        
    case let lifecycleEvent as ComponentLifecycleAnalyticsEvent:
        print("Component lifecycle:")
        print("- Event: \(lifecycleEvent.eventType.rawValue)")
        print("- Component ID: \(lifecycleEvent.componentId)")
        
    default:
        print("Analytics event: \(event.eventName)")
    }
    
    // Encode and send to analytics platform
    do {
        let encoder = JSONEncoder()
        encoder.dateEncodingStrategy = .iso8601
        let data = try encoder.encode(event)
        sendToAnalyticsPlatform(data)
    } catch {
        print("Failed to encode analytics event: \(error)")
    }
}

Event structure

All analytics events inherit from BaseAnalyticsEvent and contain the following base properties:

Property	Description
`eventName` String	The name of the analytics event (e.g., `"ComponentInteraction"`, `"ApplePaySheetOpened"`).
`sessionId` String	The session ID for the current checkout session.
`timestamp` Date	When the event occurred (Swift `Date` type).

Event-specific fields are encoded as top-level properties on each subclass, not under a nested properties object. For example, ComponentInteractionAnalyticsEvent adds componentType, interactionType, and componentId as top-level fields.

Serialising events

When sending events to external analytics platforms, you'll typically need to encode them to JSON:

analyticsEvent: { event in
    do {
        let encoder = JSONEncoder()
        encoder.dateEncodingStrategy = .iso8601
        let data = try encoder.encode(event)
        
        // Send encoded data to analytics platform
        sendToAnalyticsPlatform(data)
    } catch {
        print("Failed to encode analytics event: \(error)")
    }
}

iOS SDK analytics events

The iOS SDK emits structured analytics events through several event classes. Each event inherits from BaseAnalyticsEvent and adds event-specific fields.

Component lifecycle events

The following table lists component lifecycle events:

Event name	Swift class	Description
`ComponentLifecycleEvent`	`ComponentLifecycleAnalyticsEvent`	Fired when a component mounts or unmounts. Includes `eventType` and `componentId`. Most drop-in components use `.mount` / `.unmount` (JSON: `"Mount"`, `"Unmount"`). The SDK also defines `Loaded`, `Unloaded`, `Callback`, and `onMounted` for other components.

Component interaction events

The following table lists component interaction events:

Event name	Swift class	Description
`ComponentInteraction`	`ComponentInteractionAnalyticsEvent`	Fired when a user interacts with a component. Includes `componentType`, `interactionType`, and `componentId`. Swift cases are `.focus`, `.blur`, `.change`, `.submit`, `.paste`, `.click`, and `.close`; JSON encodes PascalCase raw values (`"Focus"`, `"Blur"`, `"Change"`, `"Submit"`, `"Paste"`, `"Click"`, `"Close"`).

Component error events

The following table lists component error events:

Event name	Swift class	Description
`ComponentError`	`ComponentErrorAnalyticsEvent`	Fired when a component error occurs. Includes `errorCode`, `errorMessage`, and `componentId`.
`ErrorMessageShown`	`MessageShownAnalyticsEvent`	Fired when an error or validation message is displayed to the user. Includes `componentType`, `messageContent`, and `elementId`.

Payment lifecycle events

The following table lists shared payment lifecycle events. Each row shows the eventName string and its Swift class:

Event name	Swift class	Description
`ComponentAbandonment`	`ComponentAbandonmentAnalyticsEvent`	Fired when a payment component is abandoned. Includes `componentType`.
`PaymentAbandonment`	`PaymentAbandonmentAnalyticsEvent`	Fired when a payment flow is abandoned. Includes `componentType`.
`PreTokenization`	`PreTokenizationAnalyticsEvent`	Fired before card tokenisation begins. Includes `componentType` and `transactionId`.
`PostTokenization`	`PostTokenizationAnalyticsEvent`	Fired after card tokenisation completes. Includes `componentType` and `transactionId`.
`PreInitiateAuthentication`	`PreInitiateAuthenticationAnalyticsEvent`	Fired before 3D Secure authentication is initiated. Includes `componentType` and `transactionId`.
`PostInitiateAuthentication`	`PostInitiateAuthenticationAnalyticsEvent`	Fired after 3D Secure authentication is initiated. Includes `componentType` and `transactionId`.
`PreAuthentication`	`PreAuthenticationAnalyticsEvent`	Fired before 3D Secure authentication begins. Includes `componentType` and `transactionId`.
`PostAuthentication`	`PostAuthenticationAnalyticsEvent`	Fired after 3D Secure authentication completes. Includes `componentType` and `transactionId`.
`PreAuthorisation`	`PreAuthorisationAnalyticsEvent`	Fired before payment authorisation begins when the component's `onPreAuthorisation` callback is set. Includes `componentType` and `transactionId`. Drop-in wires this for card, PayPal, and Apple Pay.
`PostAuthorisation`	`PostAuthorisationAnalyticsEvent`	Fired after the authorisation HTTP response is processed when the component's `onPostAuthorisation` callback is set. Includes `componentType` and `transactionId`. Drop-in wires this for card, PayPal, and Apple Pay.

Apple Pay events

Apple Pay emits several specific analytics events:

Event name	Description
`ApplePayButtonClick`	Fired when the customer taps the Apple Pay button.
`ApplePaySheetOpened`	Fired when the Apple Pay payment sheet opens.
`ApplePaySheetCompleted`	Fired when the customer completes the Apple Pay payment sheet.
`ApplePayFlowCancelled`	Fired when the customer cancels the Apple Pay flow.
`ApplePayRetryAttempt`	Fired when a retry is attempted after an Apple Pay failure.
`ApplePayBlobDecryptionFailed`	Fired when Apple Pay payment data decryption fails.
`ApplePayPaymentRequestCreationFailed`	Fired when Apple Pay payment request creation fails.

Apple Pay events extend ApplePayAnalyticsEvent and include walletType (always "ApplePay"), componentId, merchantTransactionId, optional customerID, and optional additionalData.

PayPal events

PayPal emits retry analytics events:

Event name	Description
`PayPalRetryAttempt`	Fired when a retry is attempted after a PayPal failure. Includes `componentId`, `merchantTransactionId`, optional `customerID`, and retry count in `additionalData`.

PayPal validation failures and errors are emitted through ComponentErrorAnalyticsEvent with PayPal-specific error codes and messages.