# Track paywall events

> Paywall views, closes, cancels and taps from RevenueCat, Superwall, Adapty or your own paywall, as goals next to the revenue they lead to.

Source: https://metricraven.com/docs/paywall-events  
Markdown: https://metricraven.com/docs/paywall-events.md  
Section: Revenue

See how many people saw a paywall, closed it, cancelled the payment sheet or picked a plan, and how many of them paid. Paywall events are goals, so they work in funnels, journeys and every report filter.

> **Warning:** Send paywall events one way: from the app with the SDK, or from your backend. Not both. MetricRaven doesn't deduplicate goal events, so every paywall event sent both ways is counted twice.

## Choose how to send them

| Route | Paywall tools | Events |
| --- | --- | --- |
| From the app (SDK) | RevenueCat, Superwall, Adapty, or your own paywall | All five; exit offers only where the paywall SDK reports them (RevenueCat on iOS UIKit) |
| From your backend | RevenueCat only: its webhook can include paywall events. Superwall and Adapty webhooks don't. | All five |

Purchases, renewals and refunds keep coming from the [RevenueCat](https://metricraven.com/docs/revenuecat), [Superwall](https://metricraven.com/docs/superwall) or [Adapty](https://metricraven.com/docs/adapty) webhook connected to MetricRaven. Paywall events come from one of the routes below.

## Events and properties

| Event | When |
| --- | --- |
| paywall_impression | The paywall was shown. |
| paywall_close | The paywall was closed. |
| paywall_cancel | The payment sheet was dismissed without buying. |
| paywall_exit_offer | An exit offer was shown. |
| paywall_component_interacted | A plan, tab or button on the paywall was used (RevenueCat), or a product was picked. |

Every event carries `provider` (`revenuecat`, `superwall` or `adapty`) and, when known, `paywall_id`, `paywall_name`, `offering_id` and `placement`. Interactions add `component_type`, `component_name`, `component_value`, `origin_product_id` and `destination_product_id`. An event holds at most 10 properties; extra properties you pass fill the remaining space.

## From the app

The [iOS](https://metricraven.com/docs/ios-sdk), [Android](https://metricraven.com/docs/android-sdk), [React Native](https://metricraven.com/docs/react-native) and [Flutter](https://metricraven.com/docs/flutter#paywalls) SDKs have a paywall helper with no dependency on any paywall SDK: call it from the paywall SDK's callbacks. Identify the signed-in user with the same ID as your paywall tool, so paywall events and purchases belong to the same person. It needs `@metricraven/react-native` 0.5.0, the iOS package 0.3.0, the Android library 0.2.0 or later, or any version of the Flutter package.

### RevenueCat

RevenueCat has no callback for a paywall being shown, so call `impression()` when you show it. Pass the offering: RevenueCat's close and cancel callbacks don't say which paywall it was.

```swift title="iOS (SwiftUI)"
import MetricRaven
import RevenueCatUI

let paywall = MetricRavenPaywall(provider: "revenuecat", offeringId: offering.identifier)

PaywallView(offering: offering)
    .onAppear { paywall.impression() }
    .onPurchaseCancelled { paywall.cancel() }
    .onPaywallInteraction { event in paywall.interaction(event.rawProperties) }
// presentPaywall: call paywall.close() in its onDismiss.
// UIKit (PaywallViewControllerDelegate):
//   WasDismissed → close()
//   DidCancelPurchase → cancel()
//   willPresentExitOfferController → exitOffer()
//   didTrackInteraction → interaction(event.rawProperties)
```

```kotlin title="Android"
val paywall = MetricRaven.paywall(provider = "revenuecat", offeringId = offering.identifier)
paywall.impression()

val listener = object : PaywallListener {
    override fun onPurchaseCancelled() = paywall.cancel()
    override fun onInteraction(event: PaywallInteractionEvent) = paywall.interaction(event.rawProperties)
}
// Closing: call paywall.close() in PaywallOptions' dismissRequest
// or in the PaywallActivityLauncher result.
```

```javascript title="React Native"
import { paywallEvents } from "@metricraven/react-native";
import RevenueCatUI from "react-native-purchases-ui";

const paywall = paywallEvents(metricRaven, { provider: "revenuecat", offeringId: offering.identifier });
useEffect(() => paywall.impression(), []);

<RevenueCatUI.Paywall
  options={{ offering }}
  onDismiss={paywall.close}
  onPurchaseCancelled={paywall.cancel}
  onInteraction={paywall.interaction}
/>
```

### Superwall

Forward Superwall's analytics events. `paywall_open`, `paywall_close` and `transaction_abandon` become `paywall_impression`, `paywall_close` and `paywall_cancel`, with the paywall's identifier, name and placement (and the abandoned product on a cancel); other Superwall events are ignored.

```swift title="iOS"
final class SuperwallService: SuperwallDelegate {
  let paywall = MetricRavenPaywall(provider: "superwall")

  func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
    paywall.superwall(eventInfo.event.description, params: eventInfo.params)
  }
}
```

```kotlin title="Android"
class SuperwallService : SuperwallDelegate {
    private val paywall = MetricRaven.paywall(provider = "superwall")

    override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
        paywall.superwall(eventInfo.event.rawName, eventInfo.params)
    }
}
```

```javascript title="React Native"
import { useSuperwallEvents } from "expo-superwall";

const paywall = paywallEvents(metricRaven, { provider: "superwall" });

useSuperwallEvents({
  onSuperwallEvent: (eventInfo) => paywall.superwall(eventInfo.event.event, eventInfo.params),
});
// expo-superwall/compat: paywall.superwall(eventInfo.event.type, eventInfo.params) in handleSuperwallEvent.
```

### Adapty or your own paywall

Create the helper with `provider: "adapty"` (or none for your own paywall) and the placement, then call it from Adapty's paywall view events:

| iOS | Call |
| --- | --- |
| didAppear | impression() |
| didDisappear | close() |
| didSelectProduct | productSelected(id) |
| didFinishPurchase, cancelled | cancel() |

| Android | Call |
| --- | --- |
| Showing the paywall view | impression() |
| onActionPerformed, action Close | close() |
| onProductSelected | productSelected(id) |
| onPurchaseFinished, result UserCanceled | cancel() |

| React Native | Call |
| --- | --- |
| onAppeared (v3: onPaywallShown) | impression() |
| onCloseButtonPress, or onDisappeared for a modal (v3: onPaywallClosed) | close() |
| onProductSelected | productSelected(id) |
| onPurchaseCompleted, type user_cancelled | cancel() |

## From your backend (RevenueCat)

1. **Include paywall events in your own webhook**

   In RevenueCat, open **Integrations → Webhooks**, edit the webhook that points to **your** server, and turn on **Send paywall events to Webhooks**. Keep the default event names.

2. **Forward them as server events**

   For each paywall event, send a [server event](https://metricraven.com/docs/server-events) with the same names and properties as the SDK, and RevenueCat's app user ID as `user_id`:

   ```javascript
   const NAMES = {
     PAYWALL_IMPRESSION: "paywall_impression",
     PAYWALL_CLOSE: "paywall_close",
     PAYWALL_CANCEL: "paywall_cancel",
     PAYWALL_EXIT_OFFER: "paywall_exit_offer",
     PAYWALL_COMPONENT_INTERACTED: "paywall_component_interacted",
   };
   const KEYS = ["paywall_id", "paywall_name", "offering_id", "component_type", "component_name",
     "component_value", "origin_product_id", "destination_product_id"];

   // In your RevenueCat webhook handler, after checking the Authorization header:
   const event = body.event;
   const name = NAMES[event.type];
   if (name && event.app_user_id && !event.app_user_id.startsWith("$RCAnonymousID:")) {
     const props = { provider: "revenuecat" };
     for (const key of KEYS) if (event[key] != null) props[key] = event[key];
     await fetch("https://metricraven.com/api/v1/events", {
       method: "POST",
       headers: {
         Authorization: `Bearer ${process.env.METRICRAVEN_SECRET_KEY}`,
         "Content-Type": "application/json",
       },
       body: JSON.stringify({
         name,
         user_id: event.app_user_id,
         timestamp: new Date(event.event_timestamp_ms).toISOString(),
         props,
       }),
     });
   }
   ```

   RevenueCat retries deliveries that fail. Skip an `event.id` you already forwarded so a retry isn't counted again.

> **Verify it works**
>
> The events appear in the **Goal** tab of the **Conversions** card on Traffic. A funnel such as `event:paywall_impression → event:paywall_component_interacted → payment` shows how many who saw the paywall went on to pay.

## Details

- Paywall events are linked to people through Identify: anonymous RevenueCat IDs (`$RCAnonymousID:…`) can't be matched to a visitor.
- RevenueCat's EXPERIMENT_ENROLLMENT webhook event isn't recorded.
- Paywall events count toward your monthly events like any other goal.
