> For the complete documentation index, see [llms.txt](https://docs.growsurf.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.growsurf.com/integrations/singular.md).

# Singular

## 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.

<figure><img src="/files/76iLLxsusTpH1PsOJvml" alt=""><figcaption></figcaption></figure>

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

{% hint style="info" %}
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`
  {% endhint %}

<figure><img src="/files/3YxE2aiKrXCht9rcSmRB" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
There's no configuration necessary in Singular, as the `_forward_params=2` will automatically preserve the `grsf` URL parameters in redirects.
{% endhint %}

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

{% tabs %}
{% tab title="iOS" %}

```swift
import GrowSurfSingularAttribution

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

{% endtab %}

{% tab title="Android" %}

```kotlin
import com.growsurf.sdk.attribution.singular.GrowSurfSingularAttribution

GrowSurfSingularAttribution.handle(singularParams, growsurf)
```

{% endtab %}
{% endtabs %}

**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](#ios-deferred-deep-linking-new-installs) 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](/developer-tools/ios-sdk/attribution-providers.md), [Android SDK Attribution Providers](/developer-tools/android-sdk/attribution-providers.md), and [Getting Started for Native Mobile](/getting-started-for-native-mobile.md) for more details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.growsurf.com/integrations/singular.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.