Referral Tracking in Your Android App

Gameball referrals for Android apps rely on deep links generated by a provider such as Branch or Adjust. 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

Choose a Deep Link Provider

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

Install SDK

Follow the official installation steps of your provider:

// Branch (in build.gradle)
implementation 'io.branch.sdk.android:library:5.+'

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

Configure Deep Linking

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

Connect Provider in Gameball Dashboard

Go to your Gameball dashboard:Settings → Admin Settings → Integration → Mobile Configuration → Dynamic Link ProviderSelect and connect Branch or Adjust.

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.

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()
    }
}

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;
        });
    }
}

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:

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:

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

Trigger Android’s native share dialog:

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

Customer A Retrieves Their Referral Link

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

Customer A Shares Referral Link

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

Customer B Opens the Link

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

App Captures Referral Code

The code is extracted and stored locally.

Customer B Registers

The referral code is included in the registration payload.

Gameball Rewards Both Users

Based on your program rules configured in the Gameball dashboard.

You can configure your referral rewards, eligibility, and behavior inside the Gameball dashboard.

Overview

Web & POS Integration

Mobile Integration

How Do I Track Referrals with the Android SDK (v3)?

Referral Tracking in Your Android App

Setup Requirements

Handling Referral Deep Links

Registering a Customer with a Referral Code

Fetching the Customer’s Referral Link

Full Referral Flow

​Referral Tracking in Your Android App

​Setup Requirements

​Handling Referral Deep Links

​Registering a Customer with a Referral Code

​Fetching the Customer’s Referral Link

​Sharing the Referral Link

​Full Referral Flow

Referral Tracking in Your Android App

Setup Requirements

Handling Referral Deep Links

Registering a Customer with a Referral Code

Fetching the Customer’s Referral Link

Sharing the Referral Link

Full Referral Flow