Android

Get your test keys

In the dashboard, go to Developers → API keys and copy your test publishable key (pk_test_…). You will also use your test secret key (sk_test_…) in step 6 to simulate the referred user from your terminal:

export INVITEBASE_SECRET_KEY=sk_test_...

Create a campaign

In Campaigns → New campaign, pick the Paid subscription template — it validates a referral when the referred user starts a paid subscription within 14 days, gated on a subscription_started event with plan: paid. Copy the campaign ID (for example 7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15).

Add the dependency

dependencies {
    implementation("com.invitebase:sdk:1.0.0")
}

The SDK is published to Maven Central. Supported Android versions, the Groovy form, and versioning details are in Android setup.

Configure and identify

Call configure once in your Application class. The SDK starts an anonymous session immediately — install, first open, and attribution all bind to the anonymous ID, and identify merges that history onto your user after signup.

import com.invitebase.sdk.Invitebase

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Invitebase.configure(this, publishableKey = "pk_test_...")
    }
}

After signup or login:

Invitebase.identify(InvitebaseUser(id = "usr_123", email = "sam@example.com"))

Get a referral link

val link = Invitebase.getReferralLink(campaignId = "7e1f8a3b-4c26-49d0-b591-0d8e2f6a3c15")

// link.url  → https://mycompany.refr.link/a1b2c3
// link.code → a1b2c3

Put link.url behind your "Invite a friend" button and hand it to the system share sheet:

val send = Intent(Intent.ACTION_SEND).apply {
    type = "text/plain"
    putExtra(Intent.EXTRA_TEXT, link.url)
}
startActivity(Intent.createChooser(send, null))

How the friend's install is attributed

When a friend without the app taps the link, the refr.link redirect sends them to the Play Store with the referral code in the referrer= parameter. The Play Install Referrer API passes it through the install deterministically, and the SDK recovers it automatically on first launch — no prompt, no clipboard, nothing to configure.

For friends who already have the app installed, Android App Links open it directly with the code in the launch URL. Pass it through:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent.data?.let { Invitebase.handleInbound(it) }
}

App Links need a one-time assetlinks.json association for your refr.link subdomain — Invitebase serves the file; you register your package name and signing-key fingerprint. See deep-link attribution; you can finish this quickstart without it.

Simulate the referred signup and qualifying event

Play the friend from your terminal. First the signup, carrying the referral code for attribution, then the qualifying event:

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "signup",
    "referred_user_id": "usr_friend_1",
    "referral_code": "a1b2c3"
  }'

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "subscription_started",
    "referred_user_id": "usr_friend_1",
    "properties": { "plan": "paid" }
  }'

You can fire the same events from Developers → Event simulator instead. In the real app, the referred user's device sends the qualifying event with one call:

Invitebase.track("subscription_started", mapOf("plan" to "paid"))

Watch it validate

Open the dashboard Overview: both events land in the live feed, and the referral moves signed_up → in_progress → validated under your campaign. To react in-app the moment it happens, collect the SDK's Flow:

lifecycleScope.launch {
    Invitebase.referralStateUpdates.collect { change ->
        // 5f8e2a1d-… → VALIDATED
    }
}