Analytics

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, Aeropay, 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.

DeviceType is emitted during CheckoutDropIn(config:) initialisation. Most component, payment lifecycle, and Aeropay journey events require await create() and a mounted buildContent() view.

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

The following example wires analyticsEvent on CheckoutDropInConfig, then creates and mounts Drop-in so component and Aeropay flow analytics can fire:

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_GROUP_1", // Merchant group ID (ownerType is always "MerchantGroup")
    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)")
    }
)

let checkoutDropIn = try CheckoutDropIn(config: config)
await checkoutDropIn.create()
// In SwiftUI: checkoutDropIn.buildContent()

Component and Aeropay flow analytics fire after create() wires components and the Drop-in UI is mounted. DeviceType is the only event from config and CheckoutDropIn initialisation alone.

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)")
    }
}

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

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.

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)")
    }
}

Set dateEncodingStrategy = .iso8601 (or your platform's preferred strategy). The default JSONEncoder doesn't produce ISO 8601 strings for Date; without a strategy, dates encode as floating-point reference dates.

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

The following table lists events emitted when you construct Drop-in:

Most component interaction, lifecycle, payment method, and Aeropay journey events require await create() and a mounted buildContent() view.

The following table lists component lifecycle events:

The following table lists component interaction events:

The following table lists component error events:

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

Drop-in emits PreAuthorisation / PostAuthorisation for card, Apple Pay, and Aeropay when the component callbacks are wired. PayPal doesn't use these events.

Apple Pay emits several specific analytics events:

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

PayPal emits retry analytics events:

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

PayPal authorisation is tracked via PayPalRetryAttempt and ComponentError, not PreAuthorisation / PostAuthorisation.

Aeropay analytics are delivered through the same analyticsEvent handler on CheckoutDropInConfig as other Drop-in methods. There are no Drop-in-only Aeropay event names.

Aeropay uses these componentType values to identify parts of the flow: