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

# Referral Tracking in Your Android App

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

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

***

## Setup Requirements

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

  <Step title="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.+'
    ```
  </Step>

  <Step title="Configure Deep Linking">
    Set up deep linking using your provider’s documentation.\
    Ensure your app handles link routing and parameters correctly.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  Gameball automatically appends a referral identifier (e.g. `?referrerCode=SARAH123`) to the referral links generated by your provider.
</Info>

***

## Handling Referral Deep Links

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

<CodeGroup>
  ```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;
          });
      }
  }
  ```
</CodeGroup>

<Tip>
  Store the referral code locally (e.g., SharedPreferences) and include it during customer registration.
</Tip>

***

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

<Steps>
  <Step title="Customer A Retrieves Their Referral Link">
    The existing customer accesses their unique referral link (via widget or API).
  </Step>

  <Step title="Customer A Shares Referral Link">
    They share it via messaging apps, social media, etc.
  </Step>

  <Step title="Customer B Opens the Link">
    The app opens from a Branch/Adjust link with referral parameters.
  </Step>

  <Step title="App Captures Referral Code">
    The code is extracted and stored locally.
  </Step>

  <Step title="Customer B Registers">
    The referral code is included in the registration payload.
  </Step>

  <Step title="Gameball Rewards Both Users">
    Based on your program rules configured in the Gameball dashboard.
  </Step>
</Steps>

<Info>
  You can configure your referral rewards, eligibility, and behavior inside the Gameball dashboard.
</Info>