Superwall - DATALYR Documentation

DATALYR integrates with Superwall in two ways: receiving webhook events for subscription analytics and revenue attribution, and pushing attribution data from your mobile app into Superwall via the SDK.

What Gets Tracked

Webhook Events (Superwall to DATALYR)

When a subscription event occurs in Superwall, DATALYR receives the webhook and maps it to a standardized event.

Superwall Event	DATALYR Event	Has Revenue	Notes
`initial_purchase`	`subscription_started`	Yes	Direct paid subscription (no trial)
`initial_purchase`	`trial_started`	No	Free trial begun (`periodType=TRIAL`, $0 value)
`renewal`	`subscription_renewed`	Yes	Recurring payment
`renewal`	`trial_converted`	Yes	First charge after trial ends (`isTrialConversion=true`)
`non_renewing_purchase`	`purchase`	Yes	One-time purchase
`cancellation`	`subscription_cancelled`	No
`expiration`	`subscription_expired`	No
`billing_issue`	`billing_failed`	No
`uncancellation`	`subscription_reactivated`	No
`product_change`	`subscription_changed`	No
`subscription_paused`	`subscription_paused`	No

Attribution Data (DATALYR to Superwall)

The DATALYR mobile SDK provides a getSuperwallAttributes() method that returns attribution data formatted for Superwall’s setUserAttributes() API. This pushes your marketing attribution into Superwall so you can segment users by acquisition source. Attribute keys returned by getSuperwallAttributes():

Key	Description
`datalyr_id`	DATALYR visitor ID
`media_source`	Acquisition source (maps from `utm_source`)
`campaign`	Campaign name (maps from `utm_campaign`)
`adgroup`	Ad group or adset identifier
`ad`	Ad identifier
`keyword`	Search keyword
`network`	Ad network name
`utm_source`	UTM source parameter
`utm_medium`	UTM medium parameter
`utm_campaign`	UTM campaign parameter
`utm_term`	UTM term parameter
`utm_content`	UTM content parameter
`lyr`	DATALYR tracking link ID
`fbclid`	Meta click ID
`gclid`	Google click ID
`ttclid`	TikTok click ID
`idfa`	iOS Identifier for Advertisers
`gaid`	Google Advertising ID (Android)
`att_status`	App Tracking Transparency status (iOS)

Only non-empty values are included. The method returns a flat Record<string, string> dictionary.

Setup

1. Connect Superwall in DATALYR

Go to Settings -> Integrations in DATALYR
Click “Connect” next to Superwall
Enter your Superwall Project ID
Copy the generated webhook URL

2. Configure Webhook in Superwall

Go to your Superwall Dashboard -> Settings -> Integrations -> Webhooks
Add a new webhook endpoint
Paste the DATALYR webhook URL
Select all subscription events
Save the endpoint
Click Copy Secret on the webhook endpoint to copy the signing secret (whsec_...)
Go back to DATALYR Settings -> Integrations -> Superwall and paste the signing secret

3. Push Attribution to Superwall (Mobile SDK)

After initializing the DATALYR mobile SDK, call getSuperwallAttributes() and pass the result to Superwall’s setUserAttributes(). React Native:

import { Datalyr } from '@datalyr/react-native';
import Superwall from '@superwall/react-native-superwall';

// After DATALYR SDK is initialized and user has been identified
const attrs = Datalyr.getSuperwallAttributes();
Superwall.setUserAttributes(attrs);

iOS Swift:

import DatalyrSDK
import SuperwallKit

// After DATALYR SDK is initialized and user has been identified
let attrs = DatalyrSDK.shared.getSuperwallAttributes()
Superwall.shared.setUserAttributes(attrs)

Call getSuperwallAttributes() after the DATALYR SDK has finished initialization and attribution data is available. If you call it before the SDK resolves attribution, the returned dictionary may be empty.

How Attribution Works

DATALYR uses multi-tier identity resolution to attribute Superwall subscription events to marketing sources.

Attribution Flow

Step 1: User Clicks Ad

User clicks a Meta ad
DATALYR web SDK captures: fbclid, utm_source=facebook, utm_medium=cpc
Stores in visitor profile

Step 2: User Installs App

User installs your app from the App Store
DATALYR mobile SDK initializes
Attribution data captured via web-to-app matching

Step 3: Push Attribution to Superwall

Your app calls:
const attrs = Datalyr.getSuperwallAttributes();
Superwall.setUserAttributes(attrs);

This passes datalyr_id (visitor ID) and attribution data to Superwall

Step 4: User Identifies

User signs up or logs in with email: user@example.com

Your app calls:
Datalyr.identify('user_456', { email: 'user@example.com' });

DATALYR links the mobile visitor to the original web visitor

Step 5: User Subscribes via Superwall

User purchases subscription through Superwall paywall
Superwall sends webhook to DATALYR
Webhook includes userAttributes with datalyr_id and email

Step 6: DATALYR Resolves Attribution

DATALYR receives the webhook
Looks up visitor by datalyr_id from userAttributes (fastest, most accurate)
Falls back to email lookup if datalyr_id not found
Finds match with fbclid from Step 1
Links subscription_started event to the Meta ad click

Step 7: Conversion Postback

DATALYR sends conversion to Meta via CAPI
Includes: fbclid, event_name=Purchase, value=$9.99
Meta attributes the conversion to the original ad

Identity Resolution Order

DATALYR resolves identity in this order for each Superwall webhook:

Visitor ID lookup — Checks userAttributes.datalyr_id (set automatically by getSuperwallAttributes()). This is the most accurate method because it directly matches the DATALYR visitor.
Email lookup — Searches userAttributes.email or userAttributes.$email against identified visitors
User ID lookup — Uses originalAppUserId (skips Superwall anonymous IDs that start with $SuperwallAlias:)

If none resolve, the event is still ingested but without marketing attribution.

Requirements for Attribution

The user must have been tracked by the DATALYR web or mobile SDK before the subscription event
For best results, call getSuperwallAttributes() and pass the result to Superwall.setUserAttributes() — this ensures the datalyr_id is available for direct visitor matching
Alternatively, the user must have been identified with an email that matches the email in Superwall’s userAttributes
The subscription event must be within the attribution window (default 30 days)

For the highest attribution accuracy, always call getSuperwallAttributes() after the DATALYR SDK is initialized and pass the result to Superwall. This sets the datalyr_id which enables direct visitor matching without relying on email.

Conversion Postbacks

When a Superwall subscription event matches a conversion rule, DATALYR sends the conversion to the relevant ad platform server-side.

How Postbacks Work

Superwall sends a webhook (e.g., initial_purchase)
DATALYR maps it to the appropriate event (subscription_started, trial_started, trial_converted, or subscription_renewed)
DATALYR resolves the user’s attribution (fbclid, gclid, ttclid)
If a conversion rule matches the event, DATALYR sends a postback:
- Meta: Conversions API (CAPI) with fbclid, fbp, fbc
- Google: Google Ads Conversion API with gclid
- TikTok: TikTok Events API with ttclid

Supported Platforms

Platform	Click ID	API
Meta (Facebook/Instagram)	`fbclid`	Conversions API (CAPI)
Google Ads	`gclid`	Google Ads API
TikTok Ads	`ttclid`	TikTok Events API

Setting Up Postbacks

Go to Settings -> Connections in DATALYR
Connect your ad platform (Meta, Google, or TikTok)
Create conversion rules for the events you want to track:
- trial_started → Meta StartTrial / TikTok StartTrial (optimizes for trial signups)
- trial_converted → Meta Purchase / TikTok CompletePayment (optimizes for trial-to-paid)
- subscription_started → Meta Subscribe / TikTok Subscribe (direct paid subscriptions)
- subscription_renewed → Meta Purchase / TikTok CompletePayment (recurring revenue)

See Conversion Rules for detailed configuration.

Revenue Tracking

Gross Revenue

DATALYR captures the price field from the Superwall webhook payload. Superwall converts all prices to USD. Revenue events: subscription_started, trial_converted, subscription_renewed, purchase. Note that trial_started is excluded from revenue since trials have $0 value.

Net Revenue

DATALYR calculates net revenue using Superwall’s proceeds field when available: If Superwall provides proceeds:

net_revenue = proceeds

Superwall’s proceeds field is already net of taxes and platform commission. If Superwall does not provide proceeds:

net_revenue = price * (1 - tax_percentage) * (1 - commission_percentage)

Commission Rates

Superwall may provide commissionPercentage directly in the webhook payload. If not provided, DATALYR uses:

Program	Commission Rate
Apple Small Business Program	15%
Standard	30%

Trials

DATALYR splits trial and paid subscription events automatically:

trial_started — Fires when a user begins a free trial (periodType=TRIAL). Value is $0.
trial_converted — Fires when a trial user is charged for the first time (isTrialConversion=true). Value is the subscription price.
subscription_started — Fires only for direct paid subscriptions (no trial period).

This allows you to set up separate conversion rules — for example, send StartTrial to Meta for trial_started and Purchase for trial_converted.

Store Platforms

DATALYR maps Superwall store identifiers to platform types:

Store	Platform
`APP_STORE`	ios
`MAC_APP_STORE`	macos
`PLAY_STORE`	android
`AMAZON`	android
`STRIPE`	web
`PADDLE`	web
`RC_BILLING`	web

Event Data

Each processed event includes enriched metadata:

subscription_id — Original transaction ID
product_id — Superwall product identifier
platform — Store name (APP_STORE, PLAY_STORE, etc.)
platform_type — Normalized platform (ios, android, web)
app_id — Bundle ID
period_type — Subscription period (NORMAL, TRIAL, etc.)
gross_revenue — Full price in USD
net_revenue — After commission and tax
commission_rate — Applied commission percentage
tax_percentage — Applied tax percentage
is_trial_conversion — Whether this converted from a trial
is_family_share — Whether this is a family share subscription

Data Privacy

Customer Data in Postbacks

When DATALYR sends conversion postbacks to ad platforms, customer data is hashed before transmission:

Email addresses are hashed with SHA-256 before sending to Meta, Google, or TikTok
No plaintext personally identifiable information (PII) is sent to ad platforms
All postbacks comply with GDPR hashing requirements

Data Retention

Subscription events are retained indefinitely for revenue reporting
Attribution data is retained for the duration of your DATALYR plan
Webhook deduplication keys expire after seven days

Opted-Out Users

If a user has opted out of tracking (via your app’s consent flow or ATT denial on iOS), DATALYR respects the opt-out:

Events are still ingested for revenue reporting
No postbacks are sent to ad platforms for opted-out users
Attribution data is not linked to ad platform identifiers

Refunds

Superwall signals refunds with negative price values on any event type. DATALYR automatically tracks these as negative revenue, which subtracts from your gross and net revenue totals. No additional configuration is needed.

Sandbox Events

DATALYR automatically filters out sandbox/test events (environment: "SANDBOX"). Only production events are processed and counted toward your metrics.

Webhook Signature Verification

DATALYR verifies webhook signatures using Svix (Superwall’s webhook delivery provider). When you provide the whsec_... signing secret during setup, every incoming webhook is verified for authenticity and replay protection. Webhooks older than 5 minutes are rejected.

Deduplication

DATALYR deduplicates Superwall webhook events using the unique event ID provided by Superwall (data.id). If Superwall retries a webhook, DATALYR detects the duplicate and skips processing. Deduplication keys expire after seven days.

Troubleshooting

Webhook Events Not Appearing

Check the following:

The webhook URL in Superwall matches the URL generated in DATALYR Settings -> Integrations
Your Superwall Project ID is correct in DATALYR
All subscription event types are selected in the Superwall webhook configuration
The webhook is active (not paused) in Superwall

Verify in DATALYR:

Go to Event Stream in the DATALYR dashboard
Filter by source: superwall
Check if events appear after a test purchase

Events Not Attributed

Check the following:

You are calling getSuperwallAttributes() and passing the result to Superwall.setUserAttributes() — this sets the datalyr_id for direct visitor matching
If not using getSuperwallAttributes(), the user’s email must be set in Superwall’s userAttributes (either email or $email)
The same email was used when calling identify() in the DATALYR SDK
The user was tracked by DATALYR before the subscription event
The attribution window has not expired (default 30 days)

Recommended fix: Pass DATALYR attributes to Superwall after SDK initialization:

// After DATALYR SDK is initialized
const attrs = Datalyr.getSuperwallAttributes();
Superwall.setUserAttributes(attrs);

// Also identify in DATALYR and set email in Superwall
Datalyr.identify(user.id, { email: user.email });
Superwall.setUserAttributes({ email: user.email });

Postbacks Not Sending

Check the following:

A conversion rule exists that matches the DATALYR event name (e.g., trial_started, trial_converted, subscription_started)
The ad platform is connected in Settings -> Connections
The user has a valid click ID (fbclid, gclid, or ttclid) from their original ad click

See Postback Debugging for detailed troubleshooting.

Revenue Showing Incorrect Values

Common causes:

Commission rate mismatch: Verify your Apple Small Business Program enrollment matches the commission rate DATALYR applies
Tax not accounted for: DATALYR deducts tax from net revenue. Check the tax_percentage field on the event
Currency conversion: Superwall converts to USD. If your prices are in other currencies, the USD value depends on Superwall’s conversion rate

SDK Attributes Not Populating

Check the following:

The DATALYR mobile SDK is initialized before calling getSuperwallAttributes()
Attribution data has been resolved (the user visited your site or app via a tracked link)
You are passing the result to Superwall.setUserAttributes() correctly

Debug: Log the attributes to verify:

const attrs = Datalyr.getSuperwallAttributes();
console.log('Superwall attributes:', attrs);
// Should contain keys like datalyr_id, utm_source, etc.

Next Steps

Conversion Rules

Configure how events are sent to ad platforms

Mobile SDK

Install the DATALYR mobile SDK

Meta Ads

Send conversions to Meta via CAPI

Customer Journeys

View user journeys from ad click to subscription

Introduction

Getting Started

Installation

Container & Tag Management

Understanding Your Data

Integrations

Features

Account & Billing

SDKs & Developer Tools

Troubleshooting

​What Gets Tracked

​Webhook Events (Superwall to DATALYR)

​Attribution Data (DATALYR to Superwall)

​Setup

​1. Connect Superwall in DATALYR

​2. Configure Webhook in Superwall

​3. Push Attribution to Superwall (Mobile SDK)

​How Attribution Works

​Attribution Flow

​Identity Resolution Order

​Requirements for Attribution

​Conversion Postbacks

​How Postbacks Work

​Supported Platforms

​Setting Up Postbacks

​Revenue Tracking

​Gross Revenue

​Net Revenue

​Commission Rates

​Trials

​Store Platforms

​Event Data

​Data Privacy

​Customer Data in Postbacks

​Data Retention

​Opted-Out Users

​Refunds

​Sandbox Events

​Webhook Signature Verification

​Deduplication

​Troubleshooting

​Webhook Events Not Appearing

​Events Not Attributed

​Postbacks Not Sending

​Revenue Showing Incorrect Values

​SDK Attributes Not Populating

​Next Steps

Conversion Rules

Mobile SDK

Meta Ads

Customer Journeys

What Gets Tracked

Webhook Events (Superwall to DATALYR)

Attribution Data (DATALYR to Superwall)

Setup

1. Connect Superwall in DATALYR

2. Configure Webhook in Superwall

3. Push Attribution to Superwall (Mobile SDK)

How Attribution Works

Attribution Flow

Identity Resolution Order

Requirements for Attribution

Conversion Postbacks

How Postbacks Work

Supported Platforms

Setting Up Postbacks

Revenue Tracking

Gross Revenue

Net Revenue

Commission Rates

Trials

Store Platforms

Event Data

Data Privacy

Customer Data in Postbacks

Data Retention

Opted-Out Users

Refunds

Sandbox Events

Webhook Signature Verification

Deduplication

Troubleshooting

Webhook Events Not Appearing

Events Not Attributed

Postbacks Not Sending

Revenue Showing Incorrect Values

SDK Attributes Not Populating

Next Steps