AppsFlyer

Preserve GrowSurf referral attribution in AppsFlyer OneLink campaigns for native mobile app referrals.

How It Works

If you use AppsFlyer, we recommend using an AppsFlyer link as your GrowSurf campaign Share URL.

This is the URL that referred friends land on when they open up a referral link. Depending on the device they open the link on (web, iOS, or Android), they will either land on a webpage or your App Store / Google Play listing on mobile.

When a participant shares their referral link, the GrowSurf referral code must stay attached to the AppsFlyer link. Your app then passes the AppsFlyer deep link or conversion payload into the GrowSurf mobile SDK before calling addReferredParticipant().

---

How to Set Up

Step 1: In GrowSurf, open Campaign Editor > 5. Installation and set your Share URL to the AppsFlyer OneLink URL that routes users to your app.

For new installs (deferred) on iOS, the referral arrives through AppsFlyer Unified Deep Linking and grsf must ride in a deep_link_value/deep_link_sub field — see iOS Deferred Deep Linking below.

Step 2: Pass the AppsFlyer callback payload into the GrowSurf attribution adapter before calling addReferredParticipant().

iOS

import GrowSurfAppsFlyerAttribution

try await GrowSurfAppsFlyerAttribution.handle(appsFlyerParams, sdk: growsurf)

Android

Step 3: Call addReferredParticipant() after the GrowSurf SDK has handled attribution. This method will validate pending attribution and creates a new referred participant record only when there is a valid referrer.

---

iOS Deferred Deep Linking (New Installs)

This is the primary path for an app referral program — a referral targets people who don't have your app yet, so most referred installs are cold installs. On iOS it's best-effort even when configured (see the troubleshooting tips below), so pair it with a fallback such as manual referral-code entry.

For users who tap an AppsFlyer OneLink (and don't have your iOS app installed), the referral code survives the install through AppsFlyer Unified Deep Linking (UDL), which resolves the click server-side on first launch (typically within a ~15-minute click-to-install window). Unlike Branch, Adjust, and Singular, AppsFlyer does not read the clipboard for standard deferred attribution, so there is no "Pasted from …" prompt — but you must wire up its deep-link delegate, and the referral code must ride in a field UDL exposes to new installs.

• In your app: set AppsFlyerLib.shared().deepLinkDelegate and implement the UDL callback (didResolveDeepLink(_:)). When AppsFlyer resolves the deferred link on first launch, forward the resolved deep-link values (a dictionary) into the GrowSurf adapter, then call addReferredParticipant():

iOS

import GrowSurfAppsFlyerAttribution

// Inside your AppsFlyer DeepLinkDelegate's didResolveDeepLink callback,
// once the resolved result status is "found":
try await GrowSurfAppsFlyerAttribution.handle(resolvedDeepLinkValues, sdk: growsurf)

• On your OneLink: AppsFlyer UDL exposes only deep_link_value and deep_link_sub1 through deep_link_sub10 to a new install, so the GrowSurf referral code must ride in one of those fields — a query-string-only grsf is not guaranteed to survive a cold install. Map the GrowSurf code into deep_link_value or a deep_link_sub field in your OneLink template. (Confirm the exact delegate API against your installed AppsFlyer SDK version.)

GrowSurf reads grsf out of whatever deep link AppsFlyer delivers — so a deferred referral is recovered only when UDL is configured, delivers the deep link on first launch, and the link carries grsf in a UDL-exposed field. The installed-app flow (a OneLink that opens an app the user already has) does not need UDL wiring.

---

Additional Tips

• Test both flows before launching:

  • Installed app flow: Users who already have your app installed

  • New install flow: Users who don't have your app installed — on iOS this requires the iOS Deferred Deep Linking setup above

• If the referral code is missing after a new install on iOS, confirm your OneLink carries the GrowSurf code in deep_link_value or deep_link_sub1–deep_link_sub10 and that UDL is wired up — see iOS Deferred Deep Linking.

• iOS deferred (cold install) is best-effort. AppsFlyer resolves deferred links server-side (no clipboard). A referral can be missing after a new iOS install if the install happened more than ~15 minutes after the click (outside the UDL window — use the onConversionDataSuccess / Extended DDL fallback for longer gaps), if grsf wasn't placed in deep_link_value or deep_link_sub1–deep_link_sub10, or if the UDL delegate (didResolveDeepLink) wasn't wired. Provide a fallback such as manual referral-code entry. (Android's Play Install Referrer is deterministic and isn't affected by these.)

• See iOS SDK Attribution Providers, Android SDK Attribution Providers, and Getting Started for Native Mobile for more details.