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

# How Do I Track Referrals with the Flutter SDK (v4)?

> 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](https://docs.gameball.co/tutorials/experiences/more/branch-io-integration.md) or [Adjust](https://docs.gameball.co/tutorials/experiences/more/adjust-integration.md). 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.

***

## Setup

**1. Choose a Deep Link Provider**

Use **Branch** or **Adjust** to generate referral links and handle deep/deferred linking in your Flutter app.

**2. Install the Provider SDK**

Add the Branch or Adjust SDKs using their official packages via `pubspec.yaml` and follow their integration guides for Flutter.

**3. Configure Deep Linking**

Set up universal links or URL schemes depending on your chosen provider (see their docs for configuration steps).

**4. 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.

> [!NOTE]
>
> Gameball will automatically append a referral code to the generated referral links (e.g., `?referrerCode=SARAH123`).

***

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

***

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

> [!NOTE]
>
> Configure referral rewards and rules in your Gameball dashboard. Gameball automatically tracks referrer-referred relationships based on your configuration.

***

## Referral Flow Summary

**1. Referrer Gets a Link**

Customer retrieves their referral link from the app (via widget or API).

**2. Referrer Shares Link**

The link is shared via social apps, messages, or email.

**3. New User Opens Link**

The app is opened via the referral deep link (Branch or Adjust).

**4. App Captures Referrer Code**

The SDK extracts `referrerCode` from the deep link.

**5. New User Registers**

The app calls `registerPlayer` or `initializeCustomer`, passing the referral code.

**6. Rewards Are Granted**

Gameball applies your referral rules to reward both the referrer and the referred customer.

***

## Next Steps

* [Go-Live Checklist](https://docs.gameball.co/installation-guides/v4/flutter/go-live-checklist.md)
* [Migration Notes](https://docs.gameball.co/installation-guides/v4/flutter/migration-notes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.