API Reference

WarpLink

The main entry point. Exported from @warplink/react-native.

import { WarpLink } from '@warplink/react-native';

configure(options)

configure(options: WarpLinkConfig): Promise<void>

Initialize the SDK. The key format is validated synchronously; the returned promise resolves after native configuration completes, including the automatic cold-start and deferred deep link dispatch.

Parameter	Type	Description
options	WarpLinkConfig	Configuration with your SDK key, the onLink callback, and optional settings.

When onLink is set, configure() wires getInitialDeepLink (cold start), onDeepLink (warm start), and checkDeferredDeepLink (deferred) into that single callback. Disambiguate the deferred case with isDeferred. Set automaticDeepLinks or automaticDeferredDeepLinks to false to disable either piece.

Does not throw. A malformed SDK key is reported through your onLink callback as an { error } event with code E_INVALID_API_KEY_FORMAT, and always logs a warning. The SDK stays unconfigured. iOS and Android behave the same way.

handleDeepLink(url)

handleDeepLink(url: string): Promise<WarpLinkDeepLink | null>

Resolve a deep link URL to its link data.

Errors: E_NOT_CONFIGURED, E_INVALID_URL, E_LINK_NOT_FOUND, E_NETWORK_ERROR, E_SERVER_ERROR, E_INVALID_API_KEY, E_DECODING_ERROR

checkDeferredDeepLink()

checkDeferredDeepLink(): Promise<WarpLinkDeepLink | null>

Check for a deferred deep link on first launch. Returns null if no match found. On subsequent launches, returns the 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: E_NOT_CONFIGURED, E_NETWORK_ERROR, E_SERVER_ERROR, E_INVALID_API_KEY, E_DECODING_ERROR

getAttributionResult()

getAttributionResult(): Promise<AttributionResult | null>

Get install attribution data. Returns null if no attribution match found.

isConfigured()

isConfigured(): Promise<boolean>

Check whether the SDK has been configured.

onDeepLink(listener)

onDeepLink(listener: DeepLinkListener): () => void

Register a listener for warm-start deep link events. Returns an unsubscribe function.

getInitialDeepLink()

getInitialDeepLink(): Promise<WarpLinkDeepLink | null>

Get the deep link that launched the app (cold start). Returns null if not launched via a link.

---

Types

WarpLinkConfig

interface WarpLinkConfig {
  apiKey: string;
  apiEndpoint?: string;                  // Default: "https://api.warplink.app/v1"
  debugLogging?: boolean;                // Default: false
  onLink?: (event: { deepLink?: WarpLinkDeepLink; error?: WarpLinkError }) => void; // Cold/warm/deferred, or an error
  automaticDeepLinks?: boolean;          // Default: true
  automaticDeferredDeepLinks?: boolean;  // Default: true
  linkDomains?: string[];                // Default: [] (custom domains you serve links from)
}

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

linkDomains

Hosts the SDK should treat as yours, in addition to aplnk.to. configure() forwards the list to the native SDKs, which own the domain set and the normalization (trimmed, lowercased, a full URL reduced to its host). Declaring a custom domain here is what lets a link on it resolve on the first launch, before the SDK has reached the server. The same domains can be declared natively instead: see iOS and Android.

WarpLinkDeepLink

interface WarpLinkDeepLink {
  linkId: string;
  destination: string;
  deepLinkUrl: string | null;
  customParams: Record<string, unknown>;
  isDeferred: boolean;
  matchType: 'deterministic' | 'probabilistic' | null;
  matchConfidence: number | null;
  matchGuaranteed: boolean;
}

AttributionResult

interface AttributionResult {
  linkId: string;
  matchType: 'deterministic' | 'probabilistic';
  matchConfidence: number;
  matchGuaranteed: boolean;
  isDeferred: boolean;
}

DeepLinkEvent

Discriminated union: exactly one of deepLink or error is present.

type DeepLinkEvent =
  | { deepLink: WarpLinkDeepLink; error?: undefined }
  | { deepLink?: undefined; error: WarpLinkError };

DeepLinkListener

type DeepLinkListener = (event: DeepLinkEvent) => void;

---

Error Types

WarpLinkError

class WarpLinkError extends Error {
  readonly code: ErrorCode;
  constructor(code: ErrorCode, message: string);
}

ErrorCodes

const ErrorCodes = {
  E_NOT_CONFIGURED: 'E_NOT_CONFIGURED',
  E_INVALID_API_KEY_FORMAT: 'E_INVALID_API_KEY_FORMAT',
  E_INVALID_API_KEY: 'E_INVALID_API_KEY',
  E_NETWORK_ERROR: 'E_NETWORK_ERROR',
  E_SERVER_ERROR: 'E_SERVER_ERROR',
  E_INVALID_URL: 'E_INVALID_URL',
  E_LINK_NOT_FOUND: 'E_LINK_NOT_FOUND',
  E_DECODING_ERROR: 'E_DECODING_ERROR',
} as const;

Code	Description
E_NOT_CONFIGURED	SDK not initialized.
E_INVALID_API_KEY_FORMAT	Key format invalid.
E_INVALID_API_KEY	Key rejected by server.
E_NETWORK_ERROR	Network unreachable or timeout.
E_SERVER_ERROR	Server returned 5xx.
E_INVALID_URL	Not a recognized WarpLink domain.
E_LINK_NOT_FOUND	Link not found or inactive.
E_DECODING_ERROR	Malformed server response.