API Reference

WarpLink

The main entry point. Singleton object.

object WarpLink

Properties

Property	Type	Description
SDK_VERSION	String	The current SDK version ("1.1.0").
isConfigured	Boolean	Whether configure() has been called. Thread-safe.

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 API Keys > SDK key. 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().

When options.onLink is set, configure() auto-registers ActivityLifecycleCallbacks for cold-start handling and auto-fires the deferred deep link check. 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.

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, 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 fingerprint 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 Reinstall Persistence.

Errors: NotConfigured, NetworkError, ServerError, InvalidApiKey, DecodingError

---

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>	Custom parameters on the link.
isDeferred	Boolean	Whether resolved via deferred attribution.
matchType	MatchType?	DETERMINISTIC or PROBABILISTIC.
matchConfidence	Double?	Confidence score (0.0–1.0). Useful for reporting, not for a trust decision.
matchGuaranteed	Boolean	True only for a deterministic match. Gate anything sensitive (auto sign-in, showing personal data) on this rather than on a confidence threshold.

---

MatchType

enum class MatchType {
    DETERMINISTIC,
    PROBABILISTIC
}

Value	Description
DETERMINISTIC	Matched via Play Install Referrer. Confidence is always 1.0.
PROBABILISTIC	Matched via enriched fingerprint. 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.
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