> ## 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 React Native 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 React Native app.
  </Step>

  <Step title="Install the Provider SDK">
    Install Branch or Adjust using their official React Native packages:

    ```bash theme={null}
    # Example for Branch
    npm install react-native-branch

    # Example for Adjust
    npm install @adjust/react-native-adjust
    ```

    Follow their official documentation for linking and permissions.
  </Step>

  <Step title="Configure Deep Linking">
    Set up universal links or custom URL schemes depending on your chosen provider.\
    Refer to Branch or Adjust setup guides for iOS and Android.
  </Step>

  <Step title="Connect Provider in Gameball Dashboard">
    Go to your Gameball dashboard:
    Settings → Admin Settings → Integration → Mobile Configuration → Dynamic Link Provider

    Select and configure Branch or Adjust.
  </Step>
</Steps>

<Info>
  Gameball appends a referral code (e.g., `?referrerCode=SARAH123`) to each referral link automatically.
</Info>

***

## Handle Deep Links

After the app is opened via a referral link, your deep linking provider’s SDK will pass the parameters.

You need to:

1. Extract the referrerCode
2. Store it (e.g., AsyncStorage)
3. Pass it when calling initializeCustomer

### Example with Branch

```tsx theme={null}
import branch from 'react-native-branch';
import AsyncStorage from '@react-native-async-storage/async-storage';

useEffect(() => {
  const unsubscribe = branch.subscribe(({ params }) => {
    if (params?.referrerCode) {
      AsyncStorage.setItem('referrerCode', params.referrerCode);
      console.log('Stored referrer code:', params.referrerCode);
    }
  });

  return () => unsubscribe();
}, []);
```

### Example with Adjust

```tsx theme={null}
import { Adjust, AdjustConfig } from '@adjust/react-native-adjust';
import { Linking } from 'react-native';

useEffect(() => {
  const config = new AdjustConfig('YOUR_APP_TOKEN', AdjustConfig.ENVIRONMENT_SANDBOX);
  Adjust.create(config);

  Linking.addEventListener('url', (event) => {
    const url = new URL(event.url);
    const referrerCode = url.searchParams.get('referrerCode');
    if (referrerCode) {
      AsyncStorage.setItem('referrerCode', referrerCode);
      console.log('Stored referrer code:', referrerCode);
    }
  });

  return () => Linking.removeAllListeners('url');
}, []);
```

***

## Register Customer with Referral

When registering a new customer, include the stored referral code if it exists:

```tsx theme={null}
import AsyncStorage from '@react-native-async-storage/async-storage';
import { GameballApp, InitializeCustomerRequest } from 'gameball-react-native';

async function registerCustomer() {
  const referrerCode = await AsyncStorage.getItem('referrerCode');

  const request: InitializeCustomerRequest = {
    customerId: 'new-customer-456',
    email: 'newuser@example.com',
    mobile: '+1234567890',
    referralCode: referrerCode ?? undefined,
    customerAttributes: {
      displayName: 'Jane Smith',
    },
  };

  try {
    const response = await GameballApp.getInstance().initializeCustomer(request);
    console.log('Customer registered with referral');
    await AsyncStorage.removeItem('referrerCode');
  } catch (error) {
    console.error('Registration error:', error);
  }
}
```

<Tip>
  Clear the stored referral code after successful registration to avoid applying it again unintentionally.
</Tip>

***

## Display Referral Link (via Widget)

Customers can view and share their referral link using the built-in Gameball widget. This includes both the code and sharable link.

If you’re using a custom UI, contact Gameball support to retrieve referral details via API.

<Info>
  Set up your referral rewards and eligibility criteria inside the Gameball dashboard.
</Info>

***

## Referral Flow Summary

<Steps>
  <Step title="Referrer Gets a Link">
    The existing customer retrieves their referral link via the widget or API.
  </Step>

  <Step title="Referrer Shares Link">
    They share the link through messages, social platforms, or email.
  </Step>

  <Step title="New User Opens Link">
    The deep link provider opens the app and passes the referral parameters.
  </Step>

  <Step title="App Captures Referrer Code">
    Your app extracts and stores the `referrerCode` from the link.
  </Step>

  <Step title="New User Registers">
    The registration request includes the stored referral code.
  </Step>

  <Step title="Rewards Are Granted">
    Gameball evaluates your referral conditions and rewards the referrer and the referred user.
  </Step>
</Steps>

***

## Next Steps

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