> ## 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 React Native SDK (v4)?

> 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](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 React Native app.

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

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

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

> [!NOTE]
>
> Gameball appends a referral code (e.g., `?referrerCode=SARAH123`) to each referral link automatically.

***

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

***

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

> [!NOTE]
>
> Set up your referral rewards and eligibility criteria inside the Gameball dashboard.

***

## Referral Flow Summary

**1. Referrer Gets a Link**

The existing customer retrieves their referral link via the widget or API.

**2. Referrer Shares Link**

They share the link through messages, social platforms, or email.

**3. New User Opens Link**

The deep link provider opens the app and passes the referral parameters.

**4. App Captures Referrer Code**

Your app extracts and stores the `referrerCode` from the link.

**5. New User Registers**

The registration request includes the stored referral code.

**6. Rewards Are Granted**

Gameball evaluates your referral conditions and rewards the referrer and the referred user.

***

## Next Steps

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


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