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

# AppsFlyer

## How It Works

If you use AppsFlyer, we recommend using an AppsFlyer 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 AppsFlyer link. Your app then passes the AppsFlyer deep link or conversion 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 AppsFlyer OneLink URL that routes users to your app.

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

{% hint style="info" %}
For **new installs (deferred)** on iOS, the referral arrives through AppsFlyer Unified Deep Linking and `grsf` must ride in a `deep_link_value`/`deep_link_sub` field — see [iOS Deferred Deep Linking](#ios-deferred-deep-linking-new-installs) below.
{% endhint %}

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

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

```swift
import GrowSurfAppsFlyerAttribution

try await GrowSurfAppsFlyerAttribution.handle(appsFlyerParams, sdk: growsurf)
```

{% endtab %}

{% tab title="Android" %}

```kotlin
import com.growsurf.sdk.attribution.appsflyer.GrowSurfAppsFlyerAttribution

GrowSurfAppsFlyerAttribution.handle(appsFlyerConversionData, 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 an AppsFlyer OneLink (and don't have your iOS app installed), the referral code survives the install through AppsFlyer **Unified Deep Linking (UDL)**, which resolves the click server-side on first launch (typically within a \~15-minute click-to-install window). Unlike Branch, Adjust, and Singular, AppsFlyer does not read the clipboard for standard deferred attribution, so there is no "Pasted from …" prompt — but you must wire up its deep-link delegate, and the referral code must ride in a field UDL exposes to new installs.

* **In your app:** set `AppsFlyerLib.shared().deepLinkDelegate` and implement the UDL callback (`didResolveDeepLink(_:)`). When AppsFlyer resolves the deferred link on first launch, forward the resolved deep-link values (a dictionary) into the GrowSurf adapter, then call `addReferredParticipant()`:

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

```swift
import GrowSurfAppsFlyerAttribution

// Inside your AppsFlyer DeepLinkDelegate's didResolveDeepLink callback,
// once the resolved result status is "found":
try await GrowSurfAppsFlyerAttribution.handle(resolvedDeepLinkValues, sdk: growsurf)
```

{% endtab %}
{% endtabs %}

* **On your OneLink:** AppsFlyer UDL exposes only `deep_link_value` and `deep_link_sub1` through `deep_link_sub10` to a **new** install, so the GrowSurf referral code must ride in one of those fields — a query-string-only `grsf` is not guaranteed to survive a cold install. Map the GrowSurf code into `deep_link_value` or a `deep_link_sub` field in your OneLink template. (Confirm the exact delegate API against your installed AppsFlyer SDK version.)

GrowSurf reads `grsf` out of whatever deep link AppsFlyer delivers — so a deferred referral is recovered only when UDL is configured, delivers the deep link on first launch, and the link carries `grsf` in a UDL-exposed field. The installed-app flow (a OneLink that opens an app the user already has) does not need UDL wiring.

***

## 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 a new install on iOS, confirm your OneLink carries the GrowSurf code in `deep_link_value` or `deep_link_sub1`–`deep_link_sub10` and that UDL is wired up — see [iOS Deferred Deep Linking](#ios-deferred-deep-linking-new-installs).
* **iOS deferred (cold install) is best-effort.** AppsFlyer resolves deferred links server-side (no clipboard). A referral can be missing after a *new* iOS install if the install happened more than \~15 minutes after the click (outside the UDL window — use the `onConversionDataSuccess` / Extended DDL fallback for longer gaps), if `grsf` wasn't placed in `deep_link_value` or `deep_link_sub1`–`deep_link_sub10`, or if the UDL delegate (`didResolveDeepLink`) wasn't wired. Provide a fallback such as manual referral-code entry. (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/appsflyer.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.