Android API Reference

WarpLink

The main entry point. Singleton object.

object WarpLink

Properties

Property	Type	Description
SDK_VERSION	String	The current SDK version ("1.1.1").
isConfigured	Boolean	Whether configure() has been called. Thread-safe.
attributionResult	WarpLinkDeepLink?	The cached result of the last deferred deep link check, or null if none.

configure(context, apiKey, options)

fun configure(
    context: Context,
    apiKey: String,
    options: WarpLinkOptions = WarpLinkOptions()
)

Initialize the SDK. Must be called before any other SDK methods.

Parameter	Type	Description
context	Context	Android context (typically Application). Retains applicationContext.
apiKey	String	Your WarpLink SDK key (wl_live_ + 32 alphanumeric chars). Create it in the dashboard under Keys > SDK keys. An API key is rejected by install attribution.
options	WarpLinkOptions	Configuration overrides, including the onLink callback and opt-out flags.

Does not throw. A malformed key is not thrown: configure() logs a warning, dispatches WarpLinkError.InvalidApiKeyFormat to options.onLink (if set), and leaves the SDK unconfigured. This makes it safe to call from Application.onCreate().

The deferred deep link check fires on first launch whenever automaticDeferredDeepLinks is true (the default), with or without onLink set: the SDK still calls the attribution API and records the install. options.onLink only gates delivery of the result and cold-start handling. When options.onLink is set, configure() also auto-registers ActivityLifecycleCallbacks for cold-start handling, and the deferred check's result is dispatched to it. The single callback receives every resolved link (a tap or a deferred install match). Set automaticDeepLinks or automaticDeferredDeepLinks to false to disable either piece.

onNewIntent(intent)

fun onNewIntent(intent: Intent)

Forward a warm-start intent to the SDK from your Activity's onNewIntent. The SDK resolves the link and dispatches to onLink. Required because Android delivers warm-start links through onNewIntent. Set android:launchMode="singleTask" on the Activity. A no-op when automaticDeepLinks is false.

isWarpLinkUri(uri)

fun isWarpLinkUri(uri: Uri): Boolean

Check whether a URI is a WarpLink link, without resolving it. Useful when a host has its own router and needs to decide whether to hand a URI to WarpLink at all, since handleDeepLink resolves it as a side effect (claiming the tap, deduping, calling the API).

Parameter	Type	Description
uri	Uri	The URI to check.

Before configure(), the known domain set is aplnk.to alone. A link on a custom domain reads as false until it is declared via linkDomains, the app.warplink.DOMAINS manifest meta-data, or /sdk/validate has returned it.

handleDeepLink(uri, callback)

fun handleDeepLink(
    uri: Uri,
    callback: (Result<WarpLinkDeepLink>) -> Unit
)

Resolve an incoming App Link URI to a deep link.

Parameter	Type	Description
uri	Uri	The App Link URI from intent?.data.
callback	(Result<WarpLinkDeepLink>) -> Unit	Called on the main thread.

Errors: NotConfigured, InvalidUrl, LinkNotFound, PasswordRequired, NetworkError, ServerError, InvalidApiKey, DecodingError

checkDeferredDeepLink(callback)

fun checkDeferredDeepLink(
    callback: (Result<WarpLinkDeepLink?>) -> Unit
)

Check for a deferred deep link on first launch. Returns null if no match found. Called automatically by configure() unless automaticDeferredDeepLinks is false.

Parameter	Type	Description
callback	(Result<WarpLinkDeepLink?>) -> Unit	Called on the main thread.

On first launch, reads Play Install Referrer then falls back to probabilistic matching (device language + timezone offset, with the IP derived server-side). Subsequent launches return cached result.

"First launch" means the first launch of the current install. A reinstall is a new install and runs the check again, with is_reinstall set on the request. See App Reinstall.

Errors: NotConfigured, NetworkError, ServerError, InvalidApiKey, DecodingError

isAttributionComplete()

fun isAttributionComplete(): Boolean

Whether the deferred attribution check has definitively completed for this install. Returns false before configure() runs or before the check completes. The React Native bridge reads this so a deferred match reaches onLink at most once across launches, matching the native auto-dispatch guard.

---

WarpLinkOptions

data class WarpLinkOptions(
    val apiEndpoint: String = "https://api.warplink.app/v1",
    val debugLogging: Boolean = false,
    val automaticDeepLinks: Boolean = true,
    val automaticDeferredDeepLinks: Boolean = true,
    val linkDomains: List<String> = emptyList(),
    val onLink: ((Result<WarpLinkDeepLink>) -> Unit)? = null
)

Property	Type	Default	Description
apiEndpoint	String	"https://api.warplink.app/v1"	API endpoint URL.
debugLogging	Boolean	false	Enable WarpLink Logcat tag logging.
automaticDeepLinks	Boolean	true	Auto-register cold-start handling and resolve forwarded intents.
automaticDeferredDeepLinks	Boolean	true	Auto-run the deferred deep link check on first launch.
linkDomains	List<String>	emptyList()	Extra hosts the SDK should treat as yours, for links served from a custom domain.
onLink	((Result<WarpLinkDeepLink>) -> Unit)?	null	Single callback for cold start, warm start, and deferred results. Disambiguate with isDeferred.

The match window is server-side (set per link in the dashboard), so there is no matchWindowHours option.

linkDomains and the manifest meta-data

linkDomains is additive, never a replacement. The SDK recognizes the union of aplnk.to, linkDomains, the comma separated app.warplink.DOMAINS meta-data in AndroidManifest.xml, and the domains returned by /sdk/validate. The first three are known synchronously at configure(), so a launch intent on a custom domain is claimed on the first launch instead of waiting for the server.

<meta-data
    android:name="app.warplink.DOMAINS"
    android:value="links.yourapp.com,go.yourapp.com" />

Entries are normalized: trimmed, lowercased, and reduced to a host if a full URL is given. A port is dropped, because Uri.getHost() never carries one. Empty entries are dropped. A www. prefix is preserved, since it is a different host.

---

WarpLinkDeepLink

data class WarpLinkDeepLink(
    val linkId: String,
    val destination: String,
    val deepLinkUrl: String? = null,
    val customParams: Map<String, Any> = emptyMap(),
    val isDeferred: Boolean = false,
    val matchType: MatchType? = null,
    val matchConfidence: Double? = null,
    val matchGuaranteed: Boolean = false
)

Property	Type	Description
linkId	String	Unique link identifier.
destination	String	Resolved destination URL.
deepLinkUrl	String?	Android-specific deep link URL (e.g., myapp://path).
customParams	Map<String, Any>	The query parameters of the link's destination URL on a direct open, empty on a deferred match.
isDeferred	Boolean	Whether resolved via deferred attribution.
matchType	MatchType?	DETERMINISTIC or PROBABILISTIC.
matchConfidence	Double?	Confidence score (0.0–1.0).
matchGuaranteed	Boolean	True only for a deterministic match. Use it to pick a destination, and keep sign-in on your own authentication.

---

MatchType

enum class MatchType {
    DETERMINISTIC,
    PROBABILISTIC
}

Value	Description
DETERMINISTIC	Matched via Play Install Referrer. Confidence is always 1.0.
PROBABILISTIC	Matched via enriched match key. Confidence varies.

---

WarpLinkError

sealed class WarpLinkError(
    message: String,
    cause: Throwable? = null
) : Exception(message, cause)

Subclass	Description
NotConfigured	SDK used before configure().
InvalidApiKeyFormat	Key format invalid. Reported to onLink by configure().
InvalidApiKey	Key rejected by server.
NetworkError(cause)	Network request failed.
ServerError(statusCode, message)	API error response.
InvalidUrl	Not a recognized WarpLink domain.
LinkNotFound	Link not found or inactive.
PasswordRequired	Link is password protected, so it resolves to no destination and no platform URLs.
DecodingError(cause)	Response parsing failed.

Thread Safety

• isConfigured is thread-safe (protected by synchronized)
• All callbacks are dispatched to the main thread
• configure() can be called from any thread but should be called once during initialization