Singular

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

How It Works

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

Step 2: Staying within the same GrowSurf screen as the prior step, add ?_forward_params=2 to the Share URL.

Here is an example so you can see what changes:

• Before: https://rides.sng.link/Dw5zn/k6kj

• After: https://rides.sng.link/Dw5zn/k6kj?_forward_params=2

There's no configuration necessary in Singular, as the _forward_params=2 will automatically preserve the grsf URL parameters in redirects.

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

iOS

import GrowSurfSingularAttribution

try await GrowSurfSingularAttribution.handle(singularParams, sdk: growsurf)

Android

Step 4: 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 Singular link (and don't have your iOS app installed), the referral code survives the install reliably only when Singular Clipboard-Based DDL is set up. iOS 14+ removed the IDFA/device matching and iOS 15 Private Relay masks the click IP, so Singular's default server-side probabilistic matching is unreliable on modern iOS. Clipboard-Based DDL (the equivalent of Branch's NativeLink) instead writes a token to the iOS clipboard at click time and reads it on first launch.

To enable it:

• In your app: opt into the clipboard path before initializing the Singular SDK — set SingularConfig.clipboardAttribution = true.

• On your landing page / Singular plan: Clipboard-Based DDL also requires the Singular WebSDK on the click/landing page so the token is written at click time, and it is an enterprise feature your Singular Customer Success Manager (CSM) must enable. Confirm both are in place before relying on cold-install attribution. (Confirm the exact SingularConfig API against your installed Singular SDK version.)

On iOS 16+, the user sees a one-time "Pasted from …" prompt on first launch when Singular reads the clipboard token. Without Clipboard-Based DDL, Singular falls back to server-side probabilistic matching, and the grsf referral may not reach a fresh install. The installed-app flow (a Singular link that opens an app the user already has) does not need Clipboard-Based DDL.

Note that _forward_params=2 only keeps grsf attached to the link; on iOS, the clipboard path above is what carries that grsf value into a fresh install. Both are required for cold-install attribution.

---

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 app install, confirm that Singular returns _dl, _ddl, _p, or urlParameters with the GrowSurf referral code.

• iOS deferred (cold install) is best-effort. Even when Clipboard-Based DDL is set up, 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.