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

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

# Referral Tracking in Your Android App

Gameball referrals for Android 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.

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

***

## Setup Requirements

**1. Choose a Deep Link Provider**

Use **Branch** or **Adjust** to generate referral links and manage deep/deferred linking.

**2. Install SDK**

Follow the official installation steps of your provider:

```groovy theme={null}
// Branch (in build.gradle)
implementation 'io.branch.sdk.android:library:5.+'

// Adjust
implementation 'com.adjust.sdk:adjust-android:4.+'
```

**3. Configure Deep Linking**

Set up deep linking using your provider’s documentation.\
Ensure your app handles link routing and parameters correctly.

**4. Connect Provider in Gameball Dashboard**

Go to your Gameball dashboard:

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

Select and connect Branch or Adjust.

> [!NOTE]
>
> Gameball automatically appends a referral identifier (e.g. `?referrerCode=SARAH123`) to the referral links generated by your provider.

***

## Handling Referral Deep Links

When a user opens the app via a referral link, extract the referral code and store it for registration.

```kotlin Kotlin (Branch Example) theme={null}
class MainActivity : AppCompatActivity() {

    override fun onStart() {
        super.onStart()

        Branch.sessionBuilder(this).withCallback { referringParams, error ->
            if (error == null) {
                val referralCode = referringParams?.getString("referrerCode")
                if (!referralCode.isNullOrEmpty()) {
                    saveReferralCode(referralCode)
                }
            }
        }.withData(this.intent?.data).init()
    }
}
```

```java Java (Adjust Example) theme={null}
public class MainApplication extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        AdjustConfig config = new AdjustConfig(this, "YOUR_APP_TOKEN", AdjustConfig.ENVIRONMENT_SANDBOX);
        Adjust.onCreate(config);

        Adjust.setOnDeeplinkResponseListener(deepLink -> {
            Uri uri = Uri.parse(deepLink.toString());
            String referralCode = uri.getQueryParameter("referrerCode");
            if (referralCode != null) {
                saveReferralCode(referralCode);
            }
            return true;
        });
    }
}
```

> [!TIP]
>
> Store the referral code locally (e.g., SharedPreferences) and include it during customer registration.

***

## Registering a Customer with a Referral Code

Pass the stored referral code when registering the new customer:

```kotlin theme={null}
val savedReferralCode = getStoredReferralCode()  // from SharedPreferences

val customerRequest = InitializeCustomerRequest.builder()
    .customerId("customer-123")
    .email("customer@example.com")
    .referralCode(savedReferralCode)
    .build()

GameballApp.getInstance(context).initializeCustomer(
    customerRequest,
    object : Callback<InitializeCustomerResponse> {
        override fun onSuccess(response: InitializeCustomerResponse) {
            // Referral code successfully used
            clearStoredReferralCode()
        }

        override fun onError(error: Throwable) {
            // Handle error
        }
    }
)
```

***

## Fetching the Customer’s Referral Link

Use this to retrieve and display the referral link the customer can share:

```kotlin theme={null}
GameballApp.getInstance(context).getCustomerReferralInfo(
    "customer-123",
    object : Callback<ReferralInfo> {
        override fun onSuccess(referralInfo: ReferralInfo) {
            val referralLink = referralInfo.referralLink
            showShareDialog(referralLink)
        }

        override fun onError(error: Throwable) {
            // Handle error
        }
    }
)
```

***

## Sharing the Referral Link

Trigger Android’s native share dialog:

```kotlin theme={null}
fun shareReferralLink(referralLink: String) {
    val shareIntent = Intent(Intent.ACTION_SEND).apply {
        putExtra(Intent.EXTRA_TEXT, "Join me on our app! Use my referral link: $referralLink")
        type = "text/plain"
    }

    startActivity(Intent.createChooser(shareIntent, "Share referral link"))
}
```

***

## Full Referral Flow

**1. Customer A Retrieves Their Referral Link**

The existing customer accesses their unique referral link (via widget or API).

**2. Customer A Shares Referral Link**

They share it via messaging apps, social media, etc.

**3. Customer B Opens the Link**

The app opens from a Branch/Adjust link with referral parameters.

**4. App Captures Referral Code**

The code is extracted and stored locally.

**5. Customer B Registers**

The referral code is included in the registration payload.

**6. Gameball Rewards Both Users**

Based on your program rules configured in the Gameball dashboard.

> [!NOTE]
>
> You can configure your referral rewards, eligibility, and behavior inside the Gameball dashboard.


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