API Reference

DetourService

High-level orchestration layer for routing-safe integration. Extends ChangeNotifier so it can be used with Flutter's ListenableBuilder or provider-based state management.

Constructor

DetourService({
  Duration duplicateSuppressionWindow = const Duration(seconds: 2),
})

Parameter	Type	Default	Description
duplicateSuppressionWindow	Duration	Duration(seconds: 2)	Time window used to suppress duplicate emissions for the same link (matched by type|url). Prevents double-navigation when the OS delivers the same link to both the initial and runtime paths

Properties

Property	Type	Description
isStarted	bool	true after start() has been called. Subsequent start() calls are no-ops
isInitialLinkProcessed	bool	true once the initial link resolve flow has completed, regardless of whether a link was found. Use this to conditionally show a splash screen
pendingIntent	DetourIntent?	Last navigation intent waiting to be consumed. Set when a link is resolved; cleared by consumePendingIntent(). Notifies listeners on change

Methods

start

Future<void> start(DetourConfig config)

Starts the Detour flow: configures the native SDK, subscribes to the runtime link stream, and resolves the initial link. Safe to call multiple times — only the first call starts the service.

processLink

Future<DetourResult> processLink(String url, {bool emitIntent = true})

Processes an arbitrary URL through the native SDK. When emitIntent is true (default) and the result contains a link, a new DetourIntent with source manual is emitted and pendingIntent is updated.

logEvent

Future<void> logEvent(DetourEventName eventName, {Map<String, dynamic>? data})

Records a user action using a predefined DetourEventName. The optional data parameter accepts a map of arbitrary metadata.

logRetention

Future<void> logRetention(String eventName)

Records a retention/lifecycle event with a free-form event name string.

consumePendingIntent

void consumePendingIntent()

Marks the current pendingIntent as consumed by setting it to null and notifying listeners. Call this after your navigation layer has handled the intent to prevent repeated navigation.

stop

Future<void> stop()

Stops the runtime link stream subscription. The service can be restarted by calling start() again.

DetourFlutterPlugin

Low-level method/event-channel bridge to native SDKs. Use this directly only when you need fine-grained control over the link lifecycle; prefer DetourService for most integrations.

Methods

configure

Future<void> configure(DetourConfig config)

Configures the native SDK with credentials and behavioral settings. Must be called before other methods.

resolveInitialLink

Future<DetourResult> resolveInitialLink()

Resolves the link that launched the app (cold start). Session-guarded on the native side — repeated calls return an empty result.

processLink

Future<DetourResult> processLink(String url)

Processes a single URL through the native SDK and returns the result.

linkStream

Stream<DetourResult> get linkStream

Stream of link results from runtime events (Universal Links / App Links received while the app is running).

logEvent

Future<void> logEvent(DetourEventName eventName, {Map<String, dynamic>? data})

Forwards an analytics event to the native SDK.

logRetention

Future<void> logRetention(String eventName)

Forwards a retention event to the native SDK.

Types

DetourConfig

class DetourConfig {
  final String apiKey;
  final String appID;
  final bool shouldUseClipboard;
  final LinkProcessingMode linkProcessingMode;
}

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
shouldUseClipboard	bool	No	true	iOS only. When true, the SDK reads the device clipboard as part of probabilistic fingerprinting for deferred link matching. May trigger the iOS system paste permission prompt
linkProcessingMode	LinkProcessingMode	No	LinkProcessingMode.all	Controls which link sources the SDK processes. See LinkProcessingMode for details

DetourResult

class DetourResult {
  final bool processed;
  final DetourLink? link;
}

Result returned by link processing methods.

Field	Type	Description
processed	bool	true when the native SDK has finished processing (regardless of whether a link was found)
link	DetourLink?	Parsed link data, or null if no link was matched

DetourLink

class DetourLink {
  final String url;
  final String route;
  final String pathname;
  final Map<String, String> params;
  final LinkType type;
}

Parsed link data returned inside a DetourResult.

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)
params	Map<String, String>	Parsed query parameters as key-value pairs
type	LinkType	How the link arrived in the app

DetourIntent

class DetourIntent {
  final DetourLink link;
  final DetourIntentSource source;
  final DateTime receivedAt;
}

A single navigation intent produced by DetourService. Represents a resolved link that is ready to be consumed by the app's navigation layer.

Field	Type	Description
link	DetourLink	The resolved link data
source	DetourIntentSource	Origin of the link — how it was resolved
receivedAt	DateTime	Timestamp when the intent was created

DetourIntentSource

enum DetourIntentSource {
  initial,
  runtime,
  manual,
}

Origin of a resolved Detour link emitted by DetourService:

Value	Meaning
initial	Link resolved from cold-start flow via resolveInitialLink()
runtime	Link received while the app is running via the native link stream
manual	Link resolved from an explicit processLink(url) call

LinkType

enum 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 a Universal Link (iOS) or App Link (Android) — an HTTP/HTTPS URL that the OS verified belongs to your app and delivered directly to it
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 scheme

LinkProcessingMode

enum LinkProcessingMode {
  all,
  webOnly,
  deferredOnly,
}

Controls which link sources the native SDK processes:

Value	Behavior
all (default)	Processes all link sources: deferred links from the Detour API, Universal Links (iOS) / App Links (Android), and custom scheme deep links
webOnly	Same as all but filters out custom scheme links. Only deferred links and HTTP/HTTPS links are processed
deferredOnly	Only processes deferred links from the Detour API. Skips runtime link listener and initial URL check. Recommended when your navigation framework already handles runtime deep links

DetourEventName

Standard event names for use with logEvent().

Enum value	String value
General
DetourEventName.login	login
DetourEventName.search	search
DetourEventName.share	share
DetourEventName.signUp	sign_up
DetourEventName.tutorialBegin	tutorial_begin
DetourEventName.tutorialComplete	tutorial_complete
DetourEventName.reEngage	re_engage
DetourEventName.invite	invite
DetourEventName.openedFromPushNotification	opened_from_push_notification
Sales
DetourEventName.addPaymentInfo	add_payment_info
DetourEventName.addShippingInfo	add_shipping_info
DetourEventName.addToCart	add_to_cart
DetourEventName.removeFromCart	remove_from_cart
DetourEventName.refund	refund
DetourEventName.viewItem	view_item
DetourEventName.beginCheckout	begin_checkout
DetourEventName.purchase	purchase
DetourEventName.adImpression	ad_impression

Notes

• logEvent accepts only predefined DetourEventName enum values.
• The Flutter bridge does not expose mountAnalytics, unmountAnalytics, or resetSession — analytics are managed automatically by the native SDKs.

Related pages

• Plugin Usage
• Examples
• Testing & Troubleshooting