# 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 components. These allow you to monitor every aspect of the payment journey.

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 `PxpCheckout.initialize` function.

For example:

```typescript
const pxpCheckoutSdk = PxpCheckout.initialize({
  environment: "test",
  session: sessionData,
  ownerId: "UnityGroup",
  ownerType: "MerchantGroup",
  transactionData: {
    currency: 'USD' as CurrencyType,
    amount: payAmount,
    entryType: "Ecom",
    intent: {
      card: "Authorisation"
    },
    merchantTransactionId: "9af8af33-59d5-432d-bd35-96124930ec9f",
    merchantTransactionDate: () => new Date().toISOString(),
  },
  kountDisabled: false,
  onGetShopper: () => {
    return Promise.resolve({
      id: '123',
      email: 'customer@example.com'
    });
  },
  analyticsEvent: (analyticsEvent: AnalyticsEvent.BaseAnalyticsEvent) => {
    if (analyticsEvent instanceof PazeButtonClickAnalyticsEvent) {
      console.log('Paze button clicked', {
        componentId: analyticsEvent.componentId,
        merchantTransactionId: analyticsEvent.merchantTransactionId,
        sessionId: analyticsEvent.sessionId
      });
    }

    if (analyticsEvent instanceof PazeCheckoutCompletedAnalyticsEvent) {
      console.log('Paze checkout completed', {
        merchantTransactionId: analyticsEvent.merchantTransactionId,
        sessionId: analyticsEvent.sessionId
      });
    }

    if (analyticsEvent instanceof PazeAuthorisationFailedAnalyticsEvent) {
      console.error('Paze authorisation failed', {
        merchantTransactionId: analyticsEvent.merchantTransactionId,
        additionalData: analyticsEvent.additionalData
      });
    }
  }
});
```

Wallet availability isn't emitted as an analytics event. Track it with the `onPresentmentResolved` callback on the Paze button component instead:

```typescript
const pazeButton = pxpSdk.create('paze-button', {
  buttonRenderMode: 'static',
  emailAddress: customerEmail,
  onPresentmentResolved: (isVisible) => {
    trackMetric('paze_wallet_available', { isVisible });
  }
});
```

## Supported events

The following tables list events you can receive during a Paze payment. Paze-specific events extend `PazeAnalyticsEvent`. Shared lifecycle events use different structures — check `eventName` and `componentType` when filtering.

### Paze-specific events

| Event name | Structure |
|  --- | --- |
| `PazeButtonRendered` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType` |
| `PazeButtonClicked` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType` |
| `PazePopupLaunched` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType` |
| `PazeCheckoutCompleted` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType` |
| `PazeCheckoutAbandoned` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType``additionalData` |
| `PazeDecryptionInitiated` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType` |
| `PazeDecryptionCompleted` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType` |
| `PazeDecryptionFailed` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType``additionalData` |
| `PazeAuthorisationFailed` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType``additionalData` |
| `PazeSdkInitialisationFailed` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType``additionalData` |
| `PazeCheckoutFailed` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType``additionalData` |
| `PazeCompleteFailed` | `eventName``timestamp``sessionId``componentId``merchantTransactionId``pageUrl``deviceType``operatingSystem``browserType``browserVersion``walletType``additionalData` |


### Shared lifecycle events during Paze payments

These events are also emitted during the Paze flow. They do not extend `PazeAnalyticsEvent`.

| Event name | Structure |
|  --- | --- |
| `PreAuthorisation` | `eventName``timestamp``sessionId``componentType``transactionId``isRetry` |
| `PostAuthorisation` | `eventName``timestamp``sessionId``componentType``transactionId``isRetry` |
| `PazeTransactionInitiated` | `eventName``timestamp``sessionId``componentType``transactionId` |
| `PazeAuthorisationCancelled` | `eventName``timestamp``sessionId``componentType``transactionId` |
| `PazeTokenDecryptionCancelled` | `eventName``timestamp``sessionId``componentType``transactionId` |
| `ComponentError` | `eventName``timestamp``errorCode``errorMessage``sessionId``componentId` |


`PreAuthorisation` is emitted only when you configure `onPreAuthorisation`. `PostAuthorisation` is emitted only when you configure `onPostAuthorisation` and the transaction submission succeeds. Paze does not emit 3DS or tokenisation events such as `PreAuthentication` or `PreTokenization`.

### Event data

All Paze analytics events extend `PazeAnalyticsEvent` and include the following common fields:

| Name | Description |
|  --- | --- |
| `eventName` | The name of the event (for example, `PazeButtonClicked`). |
| `timestamp` | The date and time when the event occurred. |
| `sessionId` | The session's unique identifier. |
| `componentId` | The Paze button component's unique identifier. |
| `merchantTransactionId` | The merchant transaction identifier from SDK initialisation. |
| `pageUrl` | The URL of the page where the event occurred. |
| `deviceType` | The device type (for example, `mobile` or `desktop`). |
| `operatingSystem` | The operating system. |
| `browserType` | The browser type (for example, `Chrome`). |
| `browserVersion` | The browser version. |
| `walletType` | Always `Paze` for Paze-specific events. |
| `componentType` | `Paze` for `PreAuthorisation` and `PostAuthorisation`; `PazeButton` for `PazeTransactionInitiated` and cancellation events. |
| `transactionId` | The merchant transaction identifier on shared lifecycle events. |
| `additionalData` | Optional context on failure and abandonment events (for example, error details or checkout `reason`). |


## Paze-specific events

The following table describes when each event fires.

| Event name | Trigger |
|  --- | --- |
| `PazeButtonRendered` | The Paze button became visible. |
| `PazeButtonClicked` | The shopper clicked the native Paze button. |
| `PazePopupLaunched` | The Paze checkout popup window opened. |
| `PazeCheckoutCompleted` | The Paze provider returned `COMPLETE`. |
| `PazeCheckoutAbandoned` | Checkout returned `INCOMPLETE`, the shopper closed the popup, or merchant validation rejected checkout. |
| `PazeDecryptionInitiated` | The SDK began decrypting the secured payload. |
| `PazeDecryptionCompleted` | Decryption succeeded. |
| `PazeDecryptionFailed` | Decryption failed. |
| `PazeCompleteFailed` | The `complete()` call failed. |
| `PazeCheckoutFailed` | The `checkout()` call failed. |
| `PazeAuthorisationFailed` | Transaction submission failed. |
| `PazeSdkInitialisationFailed` | SDK initialisation failed (load or initialise). |
| `PreAuthorisation` | Emitted when `onPreAuthorisation` is configured and the flow proceeds. `componentType` is `Paze`. |
| `PostAuthorisation` | Emitted when `onPostAuthorisation` is configured and transaction submission succeeds. `componentType` is `Paze`. |
| `PazeTransactionInitiated` | Transaction submission to PXP started. `componentType` is `PazeButton`. |
| `PazeAuthorisationCancelled` | `onPreAuthorisation` returned `false`. |
| `PazeTokenDecryptionCancelled` | `onPreDecryption` returned `false`. |


Use `merchantTransactionId` to correlate analytics events with server-side logs and PXP reports.

## Integration examples

### Google Analytics 4

```typescript
const pxpCheckoutSdk = PxpCheckout.initialize({
  // ... other config
  analyticsEvent: (event) => {
    if (event instanceof PazeButtonClickAnalyticsEvent) {
      gtag('event', 'paze_button_click', {
        component_id: event.componentId,
        merchant_transaction_id: event.merchantTransactionId,
        session_id: event.sessionId
      });
    }

    if (event instanceof PazeCheckoutCompletedAnalyticsEvent) {
      gtag('event', 'paze_checkout_complete', {
        merchant_transaction_id: event.merchantTransactionId,
        session_id: event.sessionId
      });
    }

    if (event instanceof PazeAuthorisationFailedAnalyticsEvent) {
      gtag('event', 'paze_authorisation_failed', {
        merchant_transaction_id: event.merchantTransactionId,
        session_id: event.sessionId
      });
    }
  }
});
```

### Segment

```typescript
const pxpCheckoutSdk = PxpCheckout.initialize({
  // ... other config
  analyticsEvent: (event) => {
    if (event instanceof PazeButtonClickAnalyticsEvent) {
      analytics.track('Paze button clicked', {
        componentId: event.componentId,
        merchantTransactionId: event.merchantTransactionId,
        sessionId: event.sessionId
      });
    }

    if (event instanceof PazeCheckoutCompletedAnalyticsEvent) {
      analytics.track('Paze checkout completed', {
        merchantTransactionId: event.merchantTransactionId,
        sessionId: event.sessionId
      });
    }

    if (event instanceof PazeDecryptionFailedAnalyticsEvent) {
      analytics.track('Paze decryption failed', {
        merchantTransactionId: event.merchantTransactionId,
        additionalData: event.additionalData
      });
    }
  }
});
```

## Best practices

### Conversion funnel tracking

Build a complete picture of your Paze conversion funnel by combining SDK analytics events with the `onPresentmentResolved` callback:

```typescript
const funnelStages = {
  walletAvailable: 0,
  buttonRendered: 0,
  buttonClicked: 0,
  checkoutCompleted: 0,
  decryptionCompleted: 0,
  paymentAuthorised: 0
};

const pazeButton = pxpSdk.create('paze-button', {
  buttonRenderMode: 'static',
  emailAddress: customerEmail,
  onPresentmentResolved: (isVisible) => {
    if (isVisible) {
      funnelStages.walletAvailable++;
    }
  }
});

const pxpCheckoutSdk = PxpCheckout.initialize({
  // ... other config
  analyticsEvent: (event) => {
    if (event instanceof PazeButtonRenderedAnalyticsEvent) {
      funnelStages.buttonRendered++;
    }

    if (event instanceof PazeButtonClickAnalyticsEvent) {
      funnelStages.buttonClicked++;
    }

    if (event instanceof PazeCheckoutCompletedAnalyticsEvent) {
      funnelStages.checkoutCompleted++;
    }

    if (event instanceof PazeDecryptionCompletedAnalyticsEvent) {
      funnelStages.decryptionCompleted++;
    }

    if (event instanceof PostAuthorisationAnalyticsEvent &&
        event.componentType === 'Paze') {
      funnelStages.paymentAuthorised++;
      console.log('Paze conversion funnel:', funnelStages);
    }
  }
});
```

### Error tracking and alerting

Track operational failures using Paze failure events and shared component errors:

```typescript
analyticsEvent: (event) => {
  if (event instanceof ComponentErrorAnalyticsEvent &&
      event.componentId.includes('paze')) {
    trackError('paze_component_error', {
      errorCode: event.errorCode,
      errorMessage: event.errorMessage,
      sessionId: event.sessionId
    });
  }

  if (event instanceof PazeDecryptionFailedAnalyticsEvent ||
      event instanceof PazeAuthorisationFailedAnalyticsEvent ||
      event instanceof PazeSdkInitialisationFailedAnalyticsEvent ||
      event instanceof PazeCheckoutFailedAnalyticsEvent ||
      event instanceof PazeCompleteFailedAnalyticsEvent) {
    trackError('paze_flow_error', {
      eventName: event.eventName,
      merchantTransactionId: event.merchantTransactionId,
      additionalData: event.additionalData
    });
  }
}
```