API Reference

Detour

Main SDK singleton. All methods are @JvmStatic for Java interoperability.

Methods

initialize

Detour.initialize(context: Context, config: DetourConfig): Unit

Initializes the SDK. Must be called once before any other SDK method — typically in Application.onCreate() or at the start of your launcher Activity. Sets up the internal API client, fingerprint collector, install referrer helper, and analytics subsystem. Throws if apiKey or appId are blank.

processLink

suspend fun Detour.processLink(intent: Intent): LinkResult

Main entry point for link processing. Automatically detects the link source from the given Intent and returns the appropriate result. Checks in priority order:

1. App Links — HTTP/HTTPS URLs from verified domains (returns LinkType.VERIFIED)
2. Scheme links — custom scheme deep links, if linkProcessingMode is ALL (returns LinkType.SCHEME)
3. Deferred links — queries the Detour API on first launch (returns LinkType.DEFERRED)

If a web URL has a single path segment (short link), the SDK resolves it to the full destination URL before returning.

getDeferredLink

suspend fun Detour.getDeferredLink(): LinkResult

Resolves deferred links only, ignoring App Links and scheme links. Useful when you handle other link types separately. Returns LinkResult.NotFirstLaunch on subsequent calls within the same session — deferred matching runs only once per app install.

resolveShortLink

suspend fun Detour.resolveShortLink(url: String): ShortLinkResponse?

Resolves a Detour short link URL to its full destination. Returns null if resolution fails or the URL is not a valid short link.

DetourDelegate

Lifecycle-aware helper that wraps Detour.processLink() for Activity / Fragment integrations. Manages coroutine scope internally and delivers results via callback.

Constructor

DetourDelegate(
    lifecycleOwner: LifecycleOwner,
    config: DetourConfig,
    onLinkResult: (LinkResult) -> Unit,
)

Parameter	Type	Description
lifecycleOwner	LifecycleOwner	The Activity, AppCompatActivity, or Fragment that owns this delegate
config	DetourConfig	SDK configuration. Also used to call Detour.initialize() if not already initialized
onLinkResult	(LinkResult) -> Unit	Callback invoked with the link processing result

Methods

onCreate

fun onCreate(intent: Intent): Unit

Call from Activity.onCreate(). Processes the launching intent for App Links, scheme links, and deferred links.

onNewIntent

fun onNewIntent(intent: Intent): Unit

Call from Activity.onNewIntent(). Processes links received while the app is already running.

DetourConfig

SDK configuration object. Accepts required credentials and optional behavioral settings.

Data class

data class DetourConfig(
    val apiKey: String,
    val appId: String,
    val linkProcessingMode: LinkProcessingMode = LinkProcessingMode.ALL,
    val storage: DetourStorage? = null,
)

Field	Type	Required	Default	Description
apiKey	String	Yes	—	Publishable API key from the Detour dashboard. Used as a Bearer token for all API calls (deferred link matching, short-link resolution, analytics)
appId	String	Yes	—	Unique app identifier from the Detour dashboard. Used to route API requests to the correct app
linkProcessingMode	LinkProcessingMode	No	ALL	Controls which link sources the SDK processes. See LinkProcessingMode for details on each value
storage	DetourStorage	No	SharedPreferences	Custom storage adapter for SDK persistence. The SDK stores a first-entrance flag (for deferred link matching) and a device ID (for analytics). Defaults to SharedPreferences-based storage

Java builder

For Java callers, a builder pattern is available:

DetourConfig.Builder(apiKey: String, appId: String)
    .linkProcessingMode(LinkProcessingMode)
    .storage(DetourStorage)
    .build()

LinkResult

Sealed class returned by processLink() and getDeferredLink(). Pattern-match on the subtype to handle each outcome.

sealed class LinkResult {
    data class Success(
        val url: String,
        val route: String,
        val pathname: String,
        val type: LinkType,
        val params: Map<String, String>,
    ) : LinkResult()

    data object NotFirstLaunch : LinkResult()
    data object NoLink : LinkResult()
    data class Error(val exception: Exception) : LinkResult()
}

Subtypes

Subtype	Description
Success	A link was successfully resolved. Contains the parsed link data — see fields below
NotFirstLaunch	No deferred link available because this is not the first app launch. Only returned by the deferred link flow
NoLink	Normal app launch without any deep link
Error	An error occurred during link processing. The exception field contains the cause

Success fields

Field	Type	Description
url	String	Full URL that was matched or opened
route	String	In-app route for navigation — path with query string, first path segment (app hash) stripped (e.g. /promo/123?utm=1)
pathname	String	Route path without query string (e.g. /promo/123)
type	LinkType	How the link arrived — DEFERRED, VERIFIED, or SCHEME
params	Map<String, String>	Parsed query parameters as key-value pairs

LinkProcessingMode

enum class LinkProcessingMode {
    ALL,
    WEB_ONLY,
    DEFERRED_ONLY,
}

Controls which link sources Detour.processLink() handles:

Value	Behavior
ALL (default)	Processes all link sources: deferred links from the Detour API, App Links (verified HTTP/HTTPS URLs), and custom scheme deep links
WEB_ONLY	Same as ALL but filters out custom scheme links. Only deferred links and App Links (HTTP/HTTPS) are processed
DEFERRED_ONLY	Only processes deferred links from the Detour API. Skips App Link and scheme link detection. Recommended when your navigation framework already handles runtime deep links

LinkType

enum class LinkType {
    DEFERRED,
    VERIFIED,
    SCHEME,
}

Describes how the link arrived in the app:

Value	Meaning
DEFERRED	The link was obtained from the Detour deferred-link API. This happens when a user who doesn't have the app installed clicks a Detour link, installs the app, and opens it — the SDK retrieves the original link from the backend on first launch
VERIFIED	The link arrived as an Android App Link — an HTTP/HTTPS URL from a verified domain that the OS delivered directly to your app
SCHEME	The link arrived via a custom URL scheme (e.g. myapp://path). These are non-HTTP URLs that the OS routes to your app based on the registered intent filter

ShortLinkResponse

data class ShortLinkResponse(
    val link: String,
    val route: String?,
    val parameters: String?,
)

Returned by Detour.resolveShortLink().

Field	Type	Description
link	String	The full destination URL after short-link resolution
route	String?	Extracted in-app route, or null if not available
parameters	String?	Raw query parameter string, or null if none

DetourStorage

interface DetourStorage {
    suspend fun getItem(key: String): String?
    suspend fun setItem(key: String, value: String)
    suspend fun removeItem(key: String) { }
}

Interface for custom storage adapters. The SDK persists a first-entrance flag (used for deferred link matching — only triggers on first app install) and a stable device ID (used for analytics). All methods are suspending functions.

By default, the SDK uses a SharedPreferences-based implementation. Provide a custom adapter if you need encrypted storage, DataStore, or another persistence layer. See Custom Storage for examples.

DetourAnalytics

Analytics module initialized by Detour.initialize(). All calls are fire-and-forget — they run on a background dispatcher and never propagate exceptions. Both methods are @JvmStatic for Java interoperability.

Methods

logEvent

DetourAnalytics.logEvent(eventName: DetourEventNames, data: Any? = null): Unit

Records a user action or custom event and sends it to the Detour backend. Pass one of the predefined DetourEventNames values. The optional data parameter accepts any Gson-serializable object (maps, primitives, data classes, etc.).

logRetention

DetourAnalytics.logRetention(eventName: String): Unit

Records a retention/lifecycle event for user engagement tracking with a free-form event name string.

DetourEventNames

Category	Event Name	String Value
General	Login	login
	Search	search
	Share	share
	SignUp	sign_up
	TutorialBegin	tutorial_begin
	TutorialComplete	tutorial_complete
	ReEngage	re_engage
	Invite	invite
	OpenedFromPushNotification	opened_from_push_notification
Sales	AddPaymentInfo	add_payment_info
	AddShippingInfo	add_shipping_info
	AddToCart	add_to_cart
	RemoveFromCart	remove_from_cart
	Refund	refund
	ViewItem	view_item
	BeginCheckout	begin_checkout
	Purchase	purchase
	AdImpression	ad_impression

Related pages

• SDK Usage
• Custom Storage
• Testing & Troubleshooting