Android SDK

The Android SDK is in Public Beta. It supports Android API 23 and later. Validate deferred installation through a Google Play test track before production use.

The open-source Kotlin-first SDK is published on Maven Central as li.biq:biqli-android.

Install

dependencies {
    implementation("li.biq:biqli-android:1.0.0")
}

The package transitively includes Google Play Install Referrer 2.2. It requests only android.permission.INTERNET; it does not request Advertising ID, location, contacts, or storage permissions.

Configure

Call Biqli.configure once before resolving attribution, normally from Application.onCreate or the first activity:

Biqli.configure(
    context = applicationContext,
    appId = "biq_mapp_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    publishableKey = "biqli_mobile_pk_your_public_mobile_key",
)

`BiqliConfiguration` property	Type	Default	Description
`appId`	`String`	Required	Public Mobile App ID beginning with `biq_mapp_`.
`publishableKey`	`String`	Required	Public app-scoped key beginning with `biqli_mobile_pk_`.
`apiBaseUrl`	`String`	`https://biq.li/api/v1`	HTTPS API base without credentials, query, or fragment.
`consentRequired`	`Boolean`	`false`	Prevent Install Referrer access and resolver requests until consent is supplied.
`diagnosticsEnabled`	`Boolean`	`false`	Enable bounded SDK diagnostic events.
`diagnosticListener`	`BiqliDiagnosticListener?`	`null`	Receives status enums without tokens, keys, URLs, or payloads.

The appId and mobile key must come from the same registered Mobile App. Never embed a biqli_... secret workspace API key.

Declare the App Link

Add an intent filter for every attached hostname to the activity that receives the link:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
        android:scheme="https"
        android:host="go.example.com"
        android:pathPrefix="/" />
</intent-filter>

The public assetlinks.json package and SHA-256 certificate must match the installed build. A local debug key and Google Play App Signing key are different certificates.

Resolve with coroutines

lifecycleScope.launch {
    try {
        val result = Biqli.resolveAttribution(intent)
        result.link?.route?.let(router::open)

        // Send a live receipt to your trusted backend before granting a reward.
        result.attributionReceipt?.let(backend::verifyReceipt)
    } catch (error: BiqliException) {
        // Keep startup non-blocking. Retry pending work on a later cold launch.
    }
}

Use a singleTop activity to forward a new verified link:

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    lifecycleScope.launch {
        Biqli.resolveAttribution(intent)
    }
}

Call resolution on each cold launch. Biqli.handleAppLink(intent) captures a verified HTTPS intent without resolving it. Biqli.attributionFlow(intent, consentGranted) emits the same single resolution through a Kotlin Flow.

Java callback API

Biqli.configure(
    getApplicationContext(),
    "biq_mapp_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "biqli_mobile_pk_your_public_mobile_key"
);

Biqli.resolveAttribution(getIntent(), true, new BiqliAttributionCallback() {
    @Override public void onSuccess(BiqliAttributionResult result) {
        // Read result.getOpen(), result.getLink(), and result.getAttribution().
    }

    @Override public void onError(BiqliException error) {
        // Retry transient pending work on a later launch.
    }
});

Callbacks run on the main thread.

Result model

BiqliAttributionResult contains:

Property	Type	Meaning
`open`	`Open`	Open ID, first-open flag, `MatchType`, and `Confidence`.
`click`	`Click?`	Matched click ID, or `null`.
`link`	`Link?`	Link ID, short URL, and in-app route, or `null`.
`attribution`	`Attribution?`	Referral code, safe metadata map, and allowed dynamic values, or `null`.
`attributionReceipt`	`String?`	Short-lived signed receipt returned only by a live matched resolution.
`requestId`	`String`	Request ID to use for tracing and support.

MatchType values are EXACT_APP_LINK, EXACT_INSTALL_REFERRER, EXACT_HANDOFF, PROBABILISTIC, and NONE. Android normally returns the first, second, or NONE.

Install Referrer lifecycle

During the pending first-open window, the SDK contacts Google Play once, extracts only a valid opaque biqli_token, and closes the connection. It never persists or transmits the complete referrer string. The extracted token, pending request, app-instance ID, and cached result use Android Keystore-backed encrypted preferences. An empty referrer, unsupported service, permission error, developer error, or missing Play Store becomes a terminal clean no-match. A service disconnect or timeout remains retryable during the 24-hour first-open window. Once first-open attribution reaches a terminal result, a cold launch without a new App Link returns the cached result without creating another resolver event. The cached result excludes attributionReceipt.

Retry and timeout behavior

Connection timeout: 5 seconds.
Read timeout: 5 seconds.
Immediate attempts: at most three.
Backoff between attempts: 400 ms, then 800 ms, plus 0–250 ms random jitter.
Immediate retries: transport errors, HTTP 429, and HTTP 5xx.
Later-launch recovery: the same pending event and idempotency key remain in encrypted storage.

The SDK does not run an autonomous background retry loop. Your app must call resolution again on a later cold launch. When consentRequired is true, call:

Biqli.resolveAttribution(intent, consentGranted = userHasConsented)

If consent is not granted, the SDK throws BiqliException.ConsentRequired before it reads Install Referrer or contacts Biqli.

Diagnostics

When enabled, diagnostics can report:

APP_LINK_CAPTURED
INSTALL_REFERRER_FOUND
INSTALL_REFERRER_EMPTY
INSTALL_REFERRER_UNAVAILABLE
INSTALL_REFERRER_RETRYABLE
RESOLVER_RETRY
RESOLVER_MATCHED
RESOLVER_NO_MATCH

These bounded enums intentionally omit raw URLs, referrers, handoff tokens, keys, and response payloads.

Errors

Exception	Meaning
`NotConfigured`	`Biqli.configure` has not completed.
`ConsentRequired`	This configuration requires consent.
`InvalidConfiguration`	App ID, mobile key, or API base is invalid.
`InvalidResponse`	The resolver response could not be decoded safely.
`Http(status, code)`	The server rejected a terminal HTTP request.
`Transport`	All immediate transport/server retry attempts failed.

Test the published dependency

Confirm Gradle resolves the Maven Central release rather than a local project substitution, then verify the built app and installed-app App Link. The deferred Install Referrer path is proven only by a Google Play installation. Follow Test and troubleshoot mobile links.

GETTING STARTED

SDKs

MOBILE ATTRIBUTION

BIQLI LINKS API

Install

Configure

Declare the App Link

Resolve with coroutines

Java callback API

Result model

Install Referrer lifecycle

Retry and timeout behavior

Diagnostics

Errors

Test the published dependency

​Install

​Configure

​Declare the App Link

​Resolve with coroutines

​Java callback API

​Result model

​Install Referrer lifecycle

​Retry and timeout behavior

​Consent

​Diagnostics

​Errors

​Test the published dependency

Install

Configure

Declare the App Link

Resolve with coroutines

Java callback API

Result model

Install Referrer lifecycle

Retry and timeout behavior

Consent

Diagnostics

Errors

Test the published dependency