Branch

Preserve GrowSurf referral attribution in Branch links for native mobile app referrals.

How It Works

If you use Branch, we recommend using a Branch 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 Branch link. Your app then passes the Branch deep link 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 Branch link that routes users to your app.

There's no configuration necessary in Branch, because Branch will automatically preserve grsf URL parameters in redirects.

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

iOS

import GrowSurfBranchAttribution

try await GrowSurfBranchAttribution.handle(branchParams, 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 a Branch link (and don't have your iOS app installed), the referral code only survives the install if Branch NativeLink is set up. iOS 14+ removed the device matching Branch previously used for deferred installs (and iOS 15 Private Relay masked the click IP), so on modern iOS the referral is carried by an encrypted clipboard token (NativeLink) instead. Without it, an iOS user who installs from a referral link opens the app with no referral data, and addReferredParticipant() finds no referrer.

To enable it:

• In the Branch dashboard: turn on NativeLink (Configuration → Enable NativeLink), and make sure your link is not web-only — the iOS redirect must be allowed to open/install the app (not $web_only / a forced web URL), so Branch can write its NativeLink token on the click.

• In your app: call checkPasteboardOnInstall() before initSession() so the SDK reads that token on first launch:

iOS

Branch.getInstance().checkPasteboardOnInstall() // must be called BEFORE initSession
Branch.getInstance().initSession(launchOptions: launchOptions) { params, _ in
    Task { try? await GrowSurfBranchAttribution.handle(params ?? [:], sdk: growsurf) }
}

On iOS 16+, a silent clipboard read still works but always surfaces Apple's one-time "Pasted from …" prompt on first launch. If you'd rather show an explicit, user-tappable paste button instead of reading silently, Branch offers BranchPasteControl (built on Apple's UIPasteControl) for iOS 16+ — which approach to use is a Branch SDK decision that depends on your Branch SDK version, so follow Branch's current iOS NativeLink documentation for the exact API.

NativeLink only carries the referral if grsf is present in the Branch link payload it restores. GrowSurf reads grsf out of whatever deep link Branch delivers, so deferred attribution survives a cold install only when NativeLink is enabled and the resolved Branch link still contains grsf. The installed-app flow (a Branch link that opens an app the user already has) does not need NativeLink.

---

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

• If the referral code is missing after app install, confirm that Branch deep link data contains grsf, ref, referredBy, or ~referring_link.

• iOS deferred (cold install) is best-effort. Even when NativeLink is set up correctly, a referral can be missing after a new iOS install if the user declined the iOS "Paste from …" prompt on first launch, copied something else before opening the app (overwriting the clipboard token), or tapped the link from an in-app / non-Safari browser. Provide a fallback such as manual referral-code entry, and don't assume the user always lands on a specific screen. (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.