How to Connect Superwall Paywall Events to Airbridge

Sync device and user IDs, prevent duplicate SDK tracking, and configure a webhook to connect paywall events to Airbridge, with subscription event mappings.

Airbridge4 min read
How to Connect Superwall Paywall Events to Airbridge

Key Takeaway

  • Connect Superwall to Airbridge by retrieving the Airbridge Device ID with fetchDeviceUUID and passing it via setIntegrationAttributes, matching user IDs, and adding your Airbridge Subdomain and Token to a Superwall webhook.
  • Configure the Airbridge SDK not to collect any events that Superwall sends to Airbridge to avoid counting events twice.
  • Superwall events map directly to Airbridge events, such as initial_purchase mapping to airbridge.subscribe and airbridge.startTrial.

You have paid campaigns running, a Superwall paywall converting users in your app, and subscription revenue coming in. Connecting Superwall and Airbridge cleanly comes down to syncing identifiers in your app code, turning off duplicate SDK tracking, and wiring up the webhook credentials.

Sync Device and User IDs First

Before you touch the webhook settings in either dashboard, your app needs to pass shared identifiers between both SDKs.

First, pass the Airbridge Device ID to Superwall before setting up the integration. Passing this ID allows Airbridge to match incoming Superwall events to the exact device. In your codebase, retrieve the Airbridge Device ID from the Airbridge SDK by calling fetchDeviceUUID. Once that value is returned, pass it to Superwall by calling setIntegrationAttributes.

Next, set the exact same user ID in both the Airbridge SDK and the Superwall SDK prior to configuring the integration. Matching user IDs allow Airbridge to tie Superwall events back to the right user. Set the user ID in the Airbridge SDK by calling Airbridge.setUserID, and set the same identifier in the Superwall SDK by calling setUserAttributes. When Superwall sends event payloads to Airbridge, this user ID is passed inside the externalUserID field.

When you are writing the initialization and login logic in your app, check the execution order carefully. Once they create an account or log in, setting the same user ID in both SDKs enables Airbridge to match Superwall events to the correct user.

Stop Duplicate Event Tracking

When a user starts a trial or completes a purchase on your paywall, your in-app code might still have default SDK event calls firing alongside the webhook.

To avoid counting events twice, configure the Airbridge SDK not to collect the events that Superwall sends to Airbridge. Audit your codebase for places where your app manually logs trial starts, initial purchases, renewals, or cancellations directly through the Airbridge SDK. If you select those events in your Superwall webhook configuration, remove or disable the corresponding in-app Airbridge SDK event calls before shipping the update.

Set Up the Superwall Webhook

Once your SDKs are passing matching identifiers and duplicate in-app event calls are turned off, you can connect the two platforms across both dashboards. You need to copy credentials from Airbridge and paste them into Superwall's webhook configuration.

  1. In Airbridge, navigate to Integrations > Third-party Integration and select Superwall to access your integration credentials.
  2. Copy the Airbridge Subdomain and Airbridge Token from Airbridge to use in the Superwall dashboard.
  3. Open the Superwall dashboard, go to Integrations, and click Create Webhook.
  4. Paste the Airbridge Subdomain and Airbridge Token copied from your Airbridge dashboard into their corresponding fields in the Superwall webhook setup.
  5. Under Events to Listen For, select the specific events you want to send to Airbridge.
  6. Click Create Webhook to finish the integration.

When choosing which events to forward in step five, align that selection with the events you disabled in the Airbridge SDK. If you only want Superwall to send initial purchases and renewals, select only those under Events to Listen For so you are not sending unexpected event types into your reports.

How Superwall Events Map to Airbridge

Superwall events map to specific Airbridge events in your integration.

When Event Action is selected as the GroupBy in Airbridge, initial_purchase shows initial_purchase as the GroupBy value, renewal shows renewal, and cancellation shows cancellation. For instance, both an initial purchase and a renewal can map to airbridge.subscribe, while the GroupBy value separates initial_purchase from renewal. For the seven lifecycle events starting from uncancellation down to non_renewing_purchase, the GroupBy value when grouped by Event Action displays as -. These seven events arrive as custom events, which require the Growth Plan.

Superwall EventAirbridge EventGroupBy Value (Event Action)
initial_purchaseairbridge.subscribe, airbridge.startTrialinitial_purchase
renewalairbridge.subscriberenewal
cancellationairbridge.unsubscribecancellation
uncancellationuncancellation-
expirationexpiration-
billing_issuebilling_issue-
product_changeproduct_change-
subscription_extendedsubscription_extended-
subscription_pausedsubscription_paused-
non_renewing_purchasenon_renewing_purchase-

FAQS

FAQ

How does Superwall pass the user ID in event payloads to Airbridge?

The user ID you configure in Superwall via setUserAttributes is sent to Airbridge as the externalUserID field within the event data. Setting the identical user ID in the Airbridge SDK via Airbridge.setUserID allows Airbridge to match those incoming events to the right user.

How can I tell an initial purchase apart from a renewal in Airbridge reports?

Both initial_purchase and renewal from Superwall map to the airbridge.subscribe event in Airbridge. When you select Event Action as your GroupBy in Airbridge, initial purchases show initial_purchase as the GroupBy value and renewals show renewal.

Does Superwall count toward the Core Plan's third-party integration limit?

Yes. Superwall is a third-party integration, and the Airbridge Core Plan includes up to 2 third-party integrations, so Superwall uses one of them.