# Analytics

Track Aeropay interactions, bank linking, errors, and transaction lifecycle events.

## Overview

The Android SDK emits structured analytics events throughout the Aeropay flow. Use these events to measure conversion, identify drop-off points, and connect client activity with your monitoring and analytics systems.

Aeropay analytics can help you:

* Measure progression from the payment button to transaction submission.
* Track Aerosync bank-linking attempts and outcomes.
* Monitor consumer data, OTP, bank selection, and transaction errors.
* Correlate client activity with sessions and merchant transactions.
* Find points where shoppers abandon or repeatedly retry the flow.


## Consume analytics events

Set `analyticsEvent` when building `PxpSdkConfig`:

```kotlin
val sdkConfig = PxpSdkConfig(
    environment = Environment.TEST,
    session = sessionResult.session,
    transactionData = transactionData,
    clientId = "your-client-id",
    ownerType = "MerchantGroup",
    ownerId = "MERCHANT_GROUP_1",
    onGetShopper = { getCurrentShopper() },
    analyticsEvent = { event ->
        sendAnalyticsEvent(
            eventName = event.eventName,
            timestamp = event.timestamp,
            payload = event,
        )
    },
)
```

The SDK calls this handler when an event is created. Keep the handler non-blocking and catch errors in your analytics client so tracking doesn't interrupt checkout.

Don't use analytics events to confirm payments or payouts. Verify the transaction on your backend using the authoritative PXP transaction result.

## Supported events

Aeropay emits payment-method-specific events and shared component events.

All events include `eventName`, `sessionId`, and `timestamp` (milliseconds since epoch). Authorisation events also expose `isRetry` (defaults to `false`).

### Aeropay-specific events

The following events describe the embedded Aerosync bank-linking flow:

| Event name | Trigger | Fields returned  |
|  --- | --- | --- |
| `AerosyncLaunched` | The Aerosync bank-linking widget opens. | - `eventName`
- `sessionId`
- `componentId`

 |
| `AerosyncCompleted` | Aerosync bank linking completes successfully. | - `eventName`
- `sessionId`
- `componentId`

 |
| `AerosyncFailed` | Aerosync bank linking fails. | - `eventName`
- `sessionId`
- `componentId`

 |


Widget-level Aerosync failures emit `AerosyncFailed` and `onError` with `SDK1304`. They don't always emit `ComponentError`. Listen for `AerosyncFailed` or `onError` in addition to `ComponentError` for complete Aeropay error coverage.

### Authorisation events

`PreAuthorisation` and `PostAuthorisation` describe the transaction gate and successful submission:

| Event name | Trigger | Fields returned  |
|  --- | --- | --- |
| `PreAuthorisation` | `onPreAuthorisation` is configured on the Aeropay component. The event fires at the start of payment submission, before the callback result is evaluated. It's emitted even when the callback returns `false`. | - `eventName`
- `sessionId`
- `componentType` (`aeropay`)
- `transactionId`

 |
| `PostAuthorisation` | `onPostAuthorisation` is configured and invoked after successful submission. | - `eventName`
- `sessionId`
- `componentType` (`aeropay`)
- `transactionId`

 |


The `transactionId` is the `merchantTransactionId` supplied during SDK initialisation. `PreAuthorisation` is emitted only when `onPreAuthorisation` is configured (including when the callback later returns `false`). `PostAuthorisation` is emitted only when `onPostAuthorisation` is configured and submission succeeds with a `MerchantSubmitResult`.

### Component interaction

`ComponentInteraction` records shopper activity such as button taps and popup close actions:

| Field | Description |
|  --- | --- |
| `eventName` | Always `ComponentInteraction`. |
| `sessionId` | The current checkout session identifier. |
| `componentType` | The Aeropay area that produced the interaction. |
| `interactionType` | The interaction, such as `Click`, `Close`, `Submit`, or on data-entry screens `Focus`, `Blur`, and `Change`. |
| `componentId` | The component identifier for the active control or screen. |


Aeropay uses these component types to identify parts of the flow:

| Component type | Area |
|  --- | --- |
| `aeropay-button` | Main Aeropay payment button. |
| `aeropayDataCollection` | Consumer data collection screen. |
| `aeropayOtpVerification` | OTP verification screen. |
| `aeropayAerosync` | Bank selection and Aerosync screen. |


### Component lifecycle

`ComponentLifecycleEvent` records popup screen mount and unmount activity:

| Field | Description |
|  --- | --- |
| `eventName` | Always `ComponentLifecycleEvent`. |
| `sessionId` | Current checkout session identifier. |
| `eventType` | `Mount` or `Unmount`. |
| `componentId` | Identifier for the mounted control or screen element. |


### Component errors

`ComponentError` records SDK and provider failures:

| Field | Description |
|  --- | --- |
| `eventName` | Always `ComponentError`. |
| `sessionId` | The current checkout session identifier. |
| `componentId` | Component identifier for the failing control or screen. Always present; may be an empty string in edge cases. |
| `errorCode` | SDK error code string. Always present; may be empty when no code is mapped. |
| `errorMessage` | A description of the error. |


Use `errorCode`, `sessionId`, and `componentId` when investigating errors. Don't display `errorMessage` directly to shoppers without mapping it to an approved user-facing message.

Mapped failed Unity transaction responses call `onSubmitError` and also emit `ComponentError` with `SDK1326`. Network or transport failures still call `onSubmitError`, but can emit a different `ComponentError` code. Widget-level Aerosync failures that emit `AerosyncFailed` and `SDK1304` on `onError` don't always emit `ComponentError`.

### Error messages shown

`ErrorMessageShown` records messages rendered inside the Aeropay flow. The event can represent field validation, user creation, OTP, bank account, account-linking, or transaction feedback shown in the popup. It isn't emitted merely because an error occurred.

The SDK emits `MessageShownAnalyticsEvent` with these fields:

| Field | Description |
|  --- | --- |
| `eventName` | Always `ErrorMessageShown`. |
| `sessionId` | Current checkout session identifier. |
| `componentType` | Aeropay screen area (e.g., `aeropayDataCollection`, `aeropayOtpVerification`, `aeropayAerosync`). |
| `componentId` | Identifier for the control that displayed the message. |
| `messageContent` | User-visible message text (treat as potentially sensitive). |


## Track a conversion funnel

Use `eventName`, `componentType`, and `interactionType` to derive a basic Aeropay funnel:

```kotlin
analyticsEvent = { event ->
    when (event.eventName) {
        "ComponentInteraction" -> {
            val interaction = event as ComponentInteractionAnalyticsEvent
            if (
                interaction.componentType == "aeropay-button" &&
                interaction.interactionType == "Click"
            ) {
                // Track aeropay_button_clicked
            }
        }
        "AerosyncLaunched" -> {
            // Track aeropay_bank_linking_started
        }
        "AerosyncCompleted" -> {
            // Track aeropay_bank_linking_completed
        }
        "PostAuthorisation" -> {
            // Track aeropay_transaction_submitted using transactionId
        }
    }
}
```

Filter the Aeropay button click carefully. Popup screens also emit `ComponentInteraction` events with the screen `componentType` values in the component-type table (e.g., `aeropayDataCollection`, `aeropayOtpVerification`, `aeropayAerosync`) and interaction types such as `Focus`, `Blur`, `Change`, `Submit`, and `Close`.

`PostAuthorisation` is emitted only when `onPostAuthorisation` is set on `AeropayButtonComponentConfig` and submission succeeds with a `MerchantSubmitResult`. Configure that callback if you rely on this funnel stage.

Analytics events don't include a dedicated user-verification-success event. If you need that funnel stage, record a custom event from `onUserVerificationSuccess`.

## Privacy guidance

When forwarding Aeropay analytics:

* Prefer `sessionId`, `merchantTransactionId`, `eventName`, `componentType`, and `errorCode`.
* Don't forward OTPs, full shopper records, bank account numbers, or provider payloads.
* Treat `errorMessage` and `messageContent` as potentially sensitive.
* Keep analytics out of the payment-confirmation path.