Attribution Providers

Configure direct deep links and attribution adapters for the GrowSurf iOS SDK.

On iOS, GrowSurf relies on your app or attribution provider to return the referral payload after install. Pass that payload into the SDK before calling addReferredParticipant().

Unlike Android (which reads the Play Install Referrer for native deferred attribution via handleDeferredDeepLink()), iOS has no native deferred deep link equivalent, so deferred attribution is delegated to your attribution provider (e.g., Branch, AppsFlyer).

Why iOS deferred is provider-specific

For a referral program, the deferred / cold-install path is the primary one — a referral targets people who don't yet have your app. When a friend taps a referral link, installs your app, then opens it for the first time (a deferred / cold install), iOS has no reliable native way to carry the referral across the install. iOS 14 (App Tracking Transparency removed the IDFA) and iOS 15 (Private Relay masks the Safari IP) broke the probabilistic device matching attribution providers previously relied on. Each provider now solves this differently, so deferred setup is not interchangeable between providers — follow the integration guide for yours.

Provider	iOS deferred mechanism	On by default?	What you must turn on
Branch	NativeLink (encrypted clipboard token)	Yes, once NativeLink is enabled	Branch dashboard Enable NativeLink + a non-web-only link; call checkPasteboardOnInstall() before initSession() (iOS 16+: consider BranchPasteControl).
Adjust	LinkMe (clipboard token)	No (optional)	ADJConfig.enableLinkMe() (v5) / setLinkMeEnabled(true) (v4) + link tag adj_linkme=1 or linkme=1; otherwise deferred is server-side/probabilistic.
Singular	Clipboard-Based DDL (clipboard token)	No (optional, enterprise)	SingularConfig.clipboardAttribution = true + Singular WebSDK on the landing page (ask your Singular CSM to enable); otherwise server-side/probabilistic.
AppsFlyer	Server-side Unified Deep Linking (no clipboard)	Yes	Implement the deepLinkDelegate / didResolveDeepLink(_:) callback; new installs receive deep_link_value + deep_link_sub1–deep_link_sub10 within a ~15-min click-to-install window.

In every case the GrowSurf SDK simply reads grsf out of whatever deep link your provider hands back. So GrowSurf deferred attribution survives a cold install only when (1) your provider's deferred path is enabled (above) and (2) the link your participants share carries grsf. The integration guides cover keeping grsf on the link; this table covers turning on the provider's deferred path.

Any clipboard-based path (Branch NativeLink, Adjust LinkMe, Singular Clipboard-Based DDL) triggers Apple's one-time "Pasted from …" prompt on first launch on iOS 16+. AppsFlyer's server-side UDL does not use the clipboard and shows no prompt. Provider SDK APIs are version-specific — confirm exact method names against your installed provider SDK.

iOS deferred is best-effort even when configured — the user can decline the paste prompt, overwrite the clipboard before first launch, or tap from an in-app/non-Safari browser (AppsFlyer also has a ~15-minute click-to-install window) — so always pair it with a fallback such as manual referral-code entry. Android's Play Install Referrer is deterministic and not subject to these.

---

Direct deep links

Use handleDeepLink(_:) when the installed app opens from a link that already contains grsf, which contains the referral code.

if let url {
    let attribution = try await growsurf.handleDeepLink(url)
}

Example accepted links:

• your-app://open?grsf=referrer_id

• https://example.com/app?grsf=referrer_id

Already support deep links? If you use an attribution provider (Branch, AppsFlyer, Adjust, Singular) or otherwise open your app from links, this is already set up — just forward the opened URL to handleDeepLink(url).

Starting from scratch? Register a custom URL scheme (CFBundleURLSchemes in Info.plist) — the quickest path, no domain needed — and/or configure Universal Links (Associated Domains entitlement) for nicer https links, which require a domain you control. Then call handleDeepLink(url) from your app's URL-open handler (SwiftUI .onOpenURL or application(_:open:options:)).

---

Adapters

GrowSurf provides adapters for popular attribution providers. Choose your provider below, or use Other to pass a dictionary of attribution values from any other provider.

Adjust

Adjust adapter

Add the Adjust adapter:

CocoaPods

pod 'GrowSurfSDK/AdjustAttribution',
    :podspec => 'https://raw.githubusercontent.com/growsurf/growsurf-ios-sdk-distribution/v0.3.0/GrowSurfSDK.podspec'

Swift Package Manager

Manual

Then pass the Adjust deferred deep link into GrowSurf:

import GrowSurfAdjustAttribution

try await GrowSurfAdjustAttribution.handle(adjustDeferredDeepLinkURL, sdk: growsurf)

The adapter accepts URL and String deep link values.

For deferred (no-app-installed) referrals on iOS, Adjust's clipboard path (LinkMe) is optional and off by default — enable it with ADJConfig.enableLinkMe() (v5) / setLinkMeEnabled(true) (v4) and tag your link adj_linkme=1/linkme=1; without it, deferred falls back to Adjust's server-side matching. See Adjust - iOS Deferred Deep Linking for detailed instructions.

AppsFlyer

Branch

Singular

Other

---

Accepted attribution keys

Key	Description
grsf	Preferred GrowSurf referrer ID.
ref	Alternate referrer ID.
referredBy	Alternate referrer ID.
provider	Attribution provider name. Ignored when the SDK method receives an explicit provider argument.
clickId	Provider click ID metadata.
click_id	Provider click ID metadata.
unique	Optional boolean string: true or false.

The SDK also parses values nested inside URL-like payload fields. For example, a provider value of https://example.com/?grsf=referrer_id&click_id=click_123 can still produce GrowSurf attribution. If a provider returns a GrowSurf-hosted share URL such as https://grow.surf/share/:campaignId/:referrerId, the SDK uses the participant value from the path.