> 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/branch.md).

# Branch

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

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

{% hint style="info" %}
There's no configuration necessary in Branch, because Branch will automatically preserve `grsf` URL parameters in redirects.
{% endhint %}

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

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

```swift
import GrowSurfBranchAttribution

try await GrowSurfBranchAttribution.handle(branchParams, sdk: growsurf)
```

{% endtab %}

{% tab title="Android" %}

```kotlin
import com.growsurf.sdk.attribution.branch.GrowSurfBranchAttribution

GrowSurfBranchAttribution.handle(branchParams, growsurf)
```

{% endtab %}
{% endtabs %}

**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:

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

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

{% endtab %}
{% endtabs %}

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](/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/branch.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.