> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Track Referrals

> Implement referral tracking using mobile deep linking providers (Branch or Adjust)

# Implement Mobile Referrals

Gameball referrals for Flutter apps rely on **deep links** generated by a provider such as [Branch](/tutorials/experiences/more/branch-io-integration) or [Adjust](/tutorials/experiences/more/adjust-integration). These links help identify the referring customer when a new user installs and opens the app.

<Warning>
  Firebase Dynamic Links are no longer supported.\
  Use **Branch** or **Adjust** instead.
</Warning>

***

## Setup

<Steps>
  <Step title="Choose a Deep Link Provider">
    Use **Branch** or **Adjust** to generate referral links and handle deep/deferred linking in your Flutter app.
  </Step>

  <Step title="Install the Provider SDK">
    Add the Branch or Adjust SDKs using their official packages via `pubspec.yaml` and follow their integration guides for Flutter.
  </Step>

  <Step title="Configure Deep Linking">
    Set up universal links or URL schemes depending on your chosen provider (see their docs for configuration steps).
  </Step>

  <Step title="Connect Provider in Gameball Dashboard">
    In the Gameball dashboard, go to:

    **Settings → Admin Settings → Integration → Mobile Configuration → Dynamic Link Provider**

    Connect your Branch or Adjust setup.
  </Step>
</Steps>

<Info>
  Gameball will automatically append a referral code to the generated referral links (e.g., `?referrerCode=SARAH123`).
</Info>

***

## Handle Referral Links

Once a user installs and opens the app through a referral link, your deep linking provider (Branch/Adjust) will pass the link parameters.

You need to:

1. Extract the `referrerCode`
2. Store it temporarily (e.g., in `SharedPreferences`)
3. Include it when calling `registerPlayer` or `initializeCustomer`

### Example with Branch

```dart theme={null}
// Pseudo-code example (refer to Branch docs for actual implementation)

BranchSdk.initSession().listen((data) {
  final referrerCode = data['referrerCode'];
  if (referrerCode != null) {
    // Save code to use during registration
    saveReferralCode(referrerCode);
  }
});
```

### Example with Adjust

```dart theme={null}
// Refer to Adjust Flutter SDK for deep link handling
Adjust.onDeeplinkResponseReceived = (String? deepLink) {
  if (deepLink != null) {
    final uri = Uri.parse(deepLink);
    final referrerCode = uri.queryParameters['referrerCode'];
    if (referrerCode != null) {
      saveReferralCode(referrerCode);
    }
  }
};
```

***

## Register Customer with Referral

Pass the stored referral code (if any) to Gameball when registering a new customer:

```dart theme={null}
import 'package:gameball_sdk/gameball_sdk.dart';

final attributes = CustomerAttributesBuilder()
    .displayName("Jane Smith")
    .email("newuser@example.com")
    .mobile("+1234567890")
    .build();

final request = InitializeCustomerRequestBuilder()
    .customerId("new-customer-456")
    .customerAttributes(attributes)
    .referralCode(savedReferralCode) // Include captured referral code
    .build();

final gameballApp = GameballApp.getInstance();
gameballApp.initializeCustomer(request, (response, error) {
  if (error == null) {
    print("Customer registered with referral");
    clearReferralCode(); // Clear stored code after success
  } else {
    print("Error: $error");
  }
});
```

<Tip>
  Clear the stored referral code after registration to avoid unintended reuse.
</Tip>

***

## Display Referral Link (via Widget)

Customers can view and share their referral link through the Gameball widget embedded in your app.

If you’re using a custom UI instead of the widget, contact Gameball support for referral link retrieval options.

<Info>
  Configure referral rewards and rules in your Gameball dashboard. Gameball automatically tracks referrer-referred relationships based on your configuration.
</Info>

***

## Referral Flow Summary

<Steps>
  <Step title="Referrer Gets a Link">
    Customer retrieves their referral link from the app (via widget or API).
  </Step>

  <Step title="Referrer Shares Link">
    The link is shared via social apps, messages, or email.
  </Step>

  <Step title="New User Opens Link">
    The app is opened via the referral deep link (Branch or Adjust).
  </Step>

  <Step title="App Captures Referrer Code">
    The SDK extracts `referrerCode` from the deep link.
  </Step>

  <Step title="New User Registers">
    The app calls `registerPlayer` or `initializeCustomer`, passing the referral code.
  </Step>

  <Step title="Rewards Are Granted">
    Gameball applies your referral rules to reward both the referrer and the referred customer.
  </Step>
</Steps>

***

## Next Steps

* [Go-Live Checklist](/installation-guides/v3/flutter/go-live-checklist)
* [Migration Notes](/installation-guides/v3/flutter/migration-notes)