Events Reference

Track user actions and forward them to ad networks for conversion optimization.

Verified website payments#

Payment backends can use POST /api/v1/apps/{appId}/web-events with a private organization API key carrying apps:write. Enable this separately with PATCH /api/v1/apps/{appId} and {"webEvents":{"enabled":true}}; it is disabled by default.

Send eventId, arClickId, anonymous deviceId, original timestampMs, eventType (purchase, renewal or refund), revenue in major units, ISO currency, clean HTTPS sourceUrl, and optional emailSha256. A renewal references its initial purchase eventId through originalTransactionId; a refund references the payment it reverses and carries negative revenue. Refunds are bounded cumulatively to that payment.

This production-only endpoint requires a verified Meta, Google, TikTok or OpenAI click belonging to the same app and a web_funnel link whose destination origin matches sourceUrl. Only initial purchases reach acquisition conversion APIs. Renewals and refunds update revenue reporting without creating installs or new acquisition conversions. Organic traffic is not supported by this endpoint.

Production receipts are not test events

The sender must verify canonical live facts and applicable consent before submitting. Payment receipts require settled payments; do not send sandbox, synthetic, zero-value or unpaid payment receipts. Confirmed trial and account funnel signals use the separate rules below. A 202 response confirms durable acceptance, not an attributed conversion. Retry the identical event ID and payload; never replay historical purchases automatically. Missing parent receipts return 409 with original_transaction_unavailable and can retry; a conflicting payload is terminal.

Website funnel signals#

The same web-events endpoint accepts sign_up (no money), checkout_started (selected price and currency), and start_trial (the monthly plan price as predicted value and currency). Send start_trial only after a real card-required trial is confirmed by the payment backend. These signals require consent and the same eligible click and source origin as payments, use stable event IDs, and contribute zero reporting revenue. start_trial forwards as Meta StartTrial and OpenAI trial_started; a later funded conversion must send a separate purchase receipt.

Web-funnel redirects preserve supported offer=trial or offer=control query parameters and include the tracking link ID as ar_link_id. A consumer may use them for experiment assignment while keeping its own admission limits.

Event Types#

AppRefer processes two types of events:

Type	Source	Use Case
SDK events	trackEvent() in your app code	Custom actions: sign_up, tutorial_complete, level_complete, etc.
RevenueCat webhook events	RevenueCat server-to-server	All purchase and subscription lifecycle events (no app code needed)

SDK Event Tracking#

Flutter - Track Event

// Standard event
await AppReferSDK.trackEvent('sign_up');

// Event with revenue
await AppReferSDK.trackEvent('purchase', params: {
  'revenue': '9.99',
  'currency': 'USD',
});

// Custom event
await AppReferSDK.trackEvent('tutorial_complete');

Standard Event Names#

Event Name	Description
install	Automatically tracked on first SDK configure()
sign_up	User creates an account
start_trial	User starts a free trial
subscribe	User subscribes to a plan
purchase	User makes a purchase
add_to_cart	User adds item to cart
initiate_checkout	User begins checkout flow
search	User performs a search
view_content	User views a product or content page
tutorial_complete	User completes onboarding tutorial
level_complete	User completes a game level

Custom Events

Any string name is supported as an event name and is recorded for analytics. Only standard names (or names you map in Settings → Event mapping) are sent to ad networks; other custom events stay in AppRefer.

Revenue Events#

Include revenue and currency parameters to report revenue to ad networks. Revenue can be a number or a decimal string (e.g., "9.99"). Currency should be a 3-letter ISO 4217 code (e.g., "USD"); non-USD amounts are converted to USD. Amounts that can't be converted, are negative, or exceed $2,000 are kept on the event but not counted or forwarded.

Ad Network Event Mapping#

AppRefer Event	Meta CAPI	Google Ads	TikTok
install	Lead	(gclid required)	Lead
purchase	Purchase	purchase	Purchase
sign_up	CompleteRegistration	sign_up	CompleteRegistration
start_trial	StartTrial	start_trial	StartTrial
qualified_trial	StartTrial	qualified_trial	StartTrial
subscribe	Subscribe	subscribe	Subscribe
add_to_cart	AddToCart	add_to_cart	AddToCart
view_content	ViewContent	view_content	ViewContent

Event Deduplication#

Each forwarded event includes a unique identifier per network to prevent duplicate conversions. Deduplication is handled automatically — no additional configuration needed.

Advanced Matching#

Call setAdvancedMatching() after user login to enrich forwarded events with hashed PII. This improves ad network match rates by 20-30%.

Flutter - Advanced Matching

AppReferSDK.setAdvancedMatching(
  email: 'user@example.com',
  phone: '+14155551234',
);

All PII is SHA256-hashed on the device before being sent to the server. See the Privacy page for details on data handling.