Skip to main content

​
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

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:
// 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 ProviderSelect and connect Branch or Adjust.
Gameball automatically appends a referral identifier (e.g. ?referrerCode=SARAH123) to the referral links generated by your provider.
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()
    }
}
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
        }
    }
)
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

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.
You can configure your referral rewards, eligibility, and behavior inside the Gameball dashboard.