Android Install Attribution

On Android, the SDK connects an install back to the link that drove it in one of two ways: a deterministic signal from the Google Play Store itself, or a probabilistic match key computed from device signals. The first tier that produces an answer wins; the second only runs when the first has nothing to offer.

Match Cascade

The SDK tries each method below in order and stops at the first one that succeeds.

Tier	Method	Signal	Confidence
1	Play Install Referrer	utm_source=warplink&utm_content={link_id}	1.0
2	Enriched probabilistic match	IP (server-derived) + normalized language + timezone	Up to 0.85

Deterministic Matching (Play Install Referrer)

Used for first-install attribution via the Google Play Store. In this tier the Play Store itself carries the link ID through to the install.

When a user clicks a WarpLink URL and is redirected to the Play Store, the referrer URL includes utm_source=warplink&utm_content={link_id}. At first launch, the SDK opens a connection to InstallReferrerClient, decodes the referrer string, and checks that utm_source reads warplink and that utm_content is a well-formed UUID before treating it as a match. A referrer that is present but belongs to another attribution system, or carries no WarpLink markers at all, is read as an ordinary organic install rather than as a failure.

• Confidence: always 1.0
• Requires Google Play Services
• No user permission needed
• Two-second timeout: the SDK never blocks the app's first launch, and moves straight to probabilistic matching if the Play Store has not answered

Devices without a Play Store (Huawei AppGallery devices, some Amazon Fire tablets), installs by adb install or direct APK, and Play Store disconnects move to the probabilistic tier below automatically. None of them throw an error the host app has to catch.

Probabilistic Matching (Enriched Match Key)

Used when the Play Install Referrer is unavailable (sideloaded apps, non-Google-Play devices).

The SDK collects the device's preferred language and timezone and sends them to the attribution API. The server derives the request's IP address, computes the match key from all three signals, and checks for a match.

Match Key Variants

Variant	Timezone component	Sent by
enriched_tz	IANA zone name, for example America/Toronto	SDKs that collect a zone name
enriched	Minute offset	Older SDKs, and devices that cannot resolve a zone
basic	None	Fallback when neither matches

An IANA zone name like America/Toronto narrows a device to one of roughly 340 possibilities. ZoneId.systemDefault().id on Android resolves the zone name directly, so most current-SDK installs send enriched_tz rather than the offset fallback.

Confidence by Elapsed Time

Time Since Click	enriched_tz	enriched	basic
< 1 hour	0.85	0.80	0.70
< 3 hours	0.65	0.60	0.50
< 6 hours	0.50	0.45	0.35
< 24 hours	0.30	0.25	0.20

The 24 hour row applies to links whose match window is raised above the 6 hour default in the dashboard.

Two further checks adjust the score for click and IP context:

• Bucket ambiguity. More than one claimable click shared the match key: x0.6
• IP sharing. Carrier-grade NAT or a private address: x0.6. A household IPv4 address: x0.9. IPv6: x1.0

Reinstalls

A reinstall counts as an install. If the user deletes and reinstalls your app, the SDK runs the full attribution flow again and records a new install, not a resumed one, so the match, if any, is counted in your install numbers exactly like a first-time install.

Android tracks this with two markers that live in different places on purpose. The completion gate, which decides whether a deferred check has already run for this install, lives in noBackupFilesDir, a directory Auto Backup never touches, so a genuine uninstall and reinstall always looks like a fresh first launch and always re-runs the check. A separate "has this device been seen before" marker lives in ordinary SharedPreferences, which Auto Backup does restore, and its only job is to set is_reinstall: true on the attribution request so the dashboard can tell a reinstall apart from a first install without affecting whether the request happens at all. If a host disables Auto Backup (android:allowBackup="false"), that second marker never restores either, and every reinstall on that device attributes as if it were brand new; this is a debug-log line, not a warning, because attribution itself is unaffected. See App Reinstall.

Interpreting Results

WarpLink.checkDeferredDeepLink { result ->
    result.onSuccess { deepLink ->
        if (deepLink != null) {
            println("Link ID: ${deepLink.linkId}")
            println("Match type: ${deepLink.matchType}")
            println("Confidence: ${deepLink.matchConfidence}")
            println("Guaranteed: ${deepLink.matchGuaranteed}")
            println("Is deferred: ${deepLink.isDeferred}")
        }
    }
}

Recommended Thresholds

WarpLink.checkDeferredDeepLink { result ->
    result.onSuccess { deepLink ->
        if (deepLink == null) {
            showOnboarding() // Organic install
            return@onSuccess
        }

        val confidence = deepLink.matchConfidence ?: 0.0

        when {
            confidence >= 0.5 -> navigateTo(deepLink.destination)
            confidence >= 0.3 -> showSuggestion(deepLink.destination)
            else -> showOnboarding()
        }
    }
}

Confidence	Recommended Action
1.0 (deterministic)	Route directly to content
> 0.5 (probabilistic)	Route to content: high confidence
0.3–0.5	Show content with confirmation
< 0.3	Show generic onboarding

These bands are a default. Pick tighter or looser cutoffs to fit your app.

Using matchGuaranteed

On Android, matchGuaranteed reads true for exactly one thing: a Play Install Referrer match. Every probabilistic-tier result, however high its confidence score, leaves it false. Use the flag, like a confidence cutoff, to decide which destination to route to. A probabilistic match is a score built from signal type and time elapsed since the click. A Play referrer match is different: it is Google's own record of which link the user tapped before installing. Keep sign-in on your own authentication.

if (deepLink.matchGuaranteed) {
    navigateToSignIn(deepLink)
} else {
    navigateTo(deepLink.destination) // public content only
}

Privacy

Signals Collected

Signal	Purpose	Source
Preferred language	Match key (server normalizes to the primary subtag)	Locale.getDefault().toLanguageTag()
Timezone name	Match key, sent as timezone by SDKs that collect a zone name	ZoneId.systemDefault().id
Timezone offset	Match key, the fallback for older SDKs	TimeZone.getDefault().getOffset(...) (DST-aware)
Play Install Referrer	Deterministic match	Google Play InstallReferrerClient

The IP address is the third match key component and is derived server-side from the request. The SDK does not collect a User-Agent or screen dimensions.

Not Collected

• GAID (Google Advertising ID)
• Android ID
• Location data
• Contacts or personal data
• Cross-app identifiers

All signals are sent over HTTPS and used solely for attribution matching. Play Install Referrer data is read once at first launch and not stored beyond the attribution result.

The probabilistic match restores the link a user tapped on the first open after install, for your own app's deferred deep links and install attribution. It does not track users across other companies' apps or websites, and it uses no advertising ID. The server keys the pending deep link by a hashed match key (HMAC-SHA256 of the IP address, primary language, and time zone). Each tap can be matched only within the app's match window, and pending entries expire automatically. A matched install keeps the hashed key for your plan's data retention period. The raw IP address is not stored. The time zone is used by the enriched variant only; the basic variant uses the IP address and primary language.

Troubleshooting Android-Specific Attribution

Play Install Referrer never fires, even on a Play Store install. Confirm com.android.installreferrer:installreferrer:2.2 is actually on the classpath; it ships as a transitive dependency of the WarpLink SDK, but an aggressive dependency-exclusion rule elsewhere in the build can strip it. Emulators without a Google Play system image never have the service to connect to, so testing this tier requires a Play-enabled emulator image or a physical device.

Every install lands in the probabilistic tier, never the deterministic one. Huawei devices running HMS, Amazon Fire tablets, and builds installed by adb install use the probabilistic tier. An absent referrer service and a referrer service that returned nothing both move to probabilistic matching identically.

Confidence scores look lower than expected on corporate or campus Wi-Fi. Carrier-grade NAT and shared IPv4 ranges apply the 0.6x IP-sharing adjustment described above, because many devices share an address.

FAQ

Does Play Install Referrer attribution require the user to grant any permission? No. Reading the install referrer needs no runtime permission and no user-facing prompt; it is a background Google Play Services call the SDK makes at first launch.

What if my app is distributed outside the Play Store entirely (APK download, enterprise MDM)? Attribution still works through the probabilistic tier. The Play Install Referrer tier simply never has a signal to read, so every install falls through to enriched or basic probabilistic matching automatically.

How do I read the match quality of an install? The matchType on the resolved WarpLinkDeepLink distinguishes deterministic from probabilistic, and matchConfidence reflects the final computed score.

Does a factory reset count as a reinstall? Yes, from the SDK's point of view. A factory reset clears noBackupFilesDir, so the completion gate is gone and the next launch runs a fresh attribution check, the same as a manual uninstall and reinstall.

Why does the SDK use SharedPreferences for one marker and noBackupFilesDir for another instead of one consistent store? They need opposite backup behavior. The device-seen marker has to survive a backup restore so a reinstall can be labeled correctly; the completion gate has to not survive one, or a restored backup would make a genuine reinstall skip attribution entirely and report as an organic install.

Related

• Getting more installs matched