iOS API Reference

WarpLink

The main entry point. All methods are static.

public final class WarpLink

Properties

Property	Type	Description
sdkVersion	String	The current SDK version ("1.1.1").
isConfigured	Bool	Whether configure() has been called. Thread-safe.
isApiKeyValid	Bool?	The server's key validation verdict: true, false (rejected or revoked), or nil if not yet determined.
attributionResult	WarpLinkDeepLink?	The cached result of the last deferred deep link check.
isAttributionComplete	Bool	Whether the deferred attribution check has finished for this install.

configure(apiKey:options:)

public static func configure(
    apiKey: String,
    options: WarpLinkOptions? = nil
)

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

Parameter	Type	Description
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?	Optional configuration overrides, including the onLink callback and opt-out flags.

Validates the key format locally, then performs async server-side validation via /sdk/validate. The validation result is cached for 24 hours.

When options.onLink is set, configure() also wires up cold start, warm start, and the deferred deep link check. The single callback receives every resolved link (a tap or a deferred install match). Set autoDeepLinkHandling or autoDeferredCheck to false to disable either piece and drive it with the manual methods below.

continue(_:) and open(_:)

@discardableResult
public static func `continue`(_ userActivity: NSUserActivity) -> Bool

@discardableResult
public static func open(_ url: URL) -> Bool

Forward an incoming Universal Link to the SDK from your scene or app delegate. The SDK resolves it and dispatches to onLink. Use these when you keep your own delegate instead of the drop-in WarpLinkSceneDelegate / WarpLinkAppDelegate. continue(_:) extracts webpageURL and forwards it to open(_:).

Both return true if the URL was a WarpLink link the SDK will handle: a WarpLink domain and a path of exactly one segment, which is what a slug always is. A custom domain counts as a WarpLink domain once you declare it in linkDomains or WarpLinkDomains. They return false (and do nothing) when configure() has not run, when autoDeepLinkHandling is disabled, when the URL is not on a WarpLink domain, or when the path is not a single segment. By default your app is associated with every path on the domain, so pass every URL here and route the ones that return false with your own router.

isWarpLinkURL(_:)

public static func isWarpLinkURL(_ url: URL) -> Bool

Check whether a URL is a WarpLink link, without resolving it. Useful when a host has its own router and needs to decide whether to hand a URL to WarpLink at all, since open(_:) and continue(_:) resolve as a side effect (claiming the tap, deduping, calling the API). Uses the same WarpLink domain and single-path-segment rule as open(_:)/continue(_:).

Parameter	Type	Description
url	URL	The URL to check.

handleDeepLink(_:completion:)

public static func handleDeepLink(
    _ url: URL,
    completion: @escaping (Result<WarpLinkDeepLink, WarpLinkError>) -> Void
)

Resolve an incoming Universal Link URL to a deep link.

Parameter	Type	Description
url	URL	The Universal Link URL received by the app.
completion	(Result<WarpLinkDeepLink, WarpLinkError>) -> Void	Called on the main thread.

Errors: .notConfigured, .invalidURL, .linkNotFound, .passwordRequired, .networkError, .serverError, .invalidApiKey, .decodingError

checkDeferredDeepLink(completion:)

public static func checkDeferredDeepLink(
    completion: @escaping (Result<WarpLinkDeepLink?, WarpLinkError>) -> Void
)

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

Parameter	Type	Description
completion	(Result<WarpLinkDeepLink?, WarpLinkError>) -> Void	Called on the main thread.

On first launch, collects device signals (preferred language, timezone offset, IDFV) and sends them to the attribution API. The server derives the IP and computes the match key. 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: .notConfigured, .networkError, .serverError, .invalidApiKey, .decodingError

---

WarpLinkOptions

public struct WarpLinkOptions: Sendable

Property	Type	Default	Description
apiEndpoint	String	"https://api.warplink.app/v1"	API endpoint URL.
debugLogging	Bool	false	Enable [WarpLink] console logging.
autoDeepLinkHandling	Bool	true	Automatically resolve forwarded Universal Links and dispatch to onLink.
autoDeferredCheck	Bool	true	Automatically run the deferred deep link check on first launch.
linkDomains	[String]	[]	Extra hosts the SDK should treat as yours, for links served from a custom domain.
onLink	((Result<WarpLinkDeepLink?, WarpLinkError>) -> Void)?	nil	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 WarpLinkDomains plist key

linkDomains is additive, never a replacement. The SDK recognizes the union of aplnk.to, linkDomains, the WarpLinkDomains string array in Info.plist, and the domains returned by /sdk/validate. The first three are known synchronously at configure(), so open(_:) claims a custom-domain link on the first launch instead of waiting for the server.

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

WarpLinkDomains is an array of strings. A single comma separated string is accepted too, because that is the row type Xcode's plist editor creates by default.

---

WarpLinkDeepLink

public struct WarpLinkDeepLink

Property	Type	Description
linkId	String	Unique link identifier.
destination	String	Resolved destination URL.
deepLinkUrl	String?	iOS-specific deep link URL (e.g., myapp://path).
customParams	[String: JSONValue]	The query parameters of the link's destination URL on a direct open, empty on a deferred match. Read values with the typed accessors (.stringValue, .intValue, .doubleValue, .boolValue).
isDeferred	Bool	Whether resolved via deferred attribution.
matchType	MatchType?	.deterministic or .probabilistic.
matchConfidence	Double?	Confidence score (0.0–1.0). Use it for reporting.
matchGuaranteed	Bool	True only for a deterministic match. Use it to pick a destination, and keep sign-in on your own authentication.

Access custom params with the typed accessors:

if let productId = deepLink.customParams["product_id"]?.stringValue {
    showProduct(id: productId)
}

---

JSONValue

public enum JSONValue: Codable, Sendable, Equatable

The value type of customParams, which the API returns as a JSON object. Read a value with its typed accessor rather than switching on the enum cases directly.

Accessor	Type	Description
stringValue	String?	The value if it is a JSON string.
intValue	Int?	The value if it is a JSON number representable as an Int.
doubleValue	Double?	The value if it is a JSON number.
boolValue	Bool?	The value if it is a JSON boolean.
arrayValue	[JSONValue]?	The value if it is a JSON array.
objectValue	[String: JSONValue]?	The value if it is a JSON object.
foundationValue	Any	The value lowered to a Foundation/JSON object graph (String/Int/Double/Bool/[String: Any]/[Any]/NSNull).

---

MatchType

public enum MatchType: String, Codable, Sendable

Case	Description
.deterministic	Resolved straight from a tapped link, or matched by the Play Install Referrer on Android. Confidence is always 1.0. A deferred install on iOS is never deterministic.
.probabilistic	Matched via enriched match key.

---

WarpLinkError

public enum WarpLinkError: Error, LocalizedError

Case	Description
.notConfigured	SDK used before configure().
.invalidApiKeyFormat	Key format invalid (wl_live_ + 32 chars).
.invalidApiKey	Key rejected by server.
.networkError(Error)	Network request failed.
.serverError(statusCode: Int, message: String)	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(Error)	Response parsing failed.

---

WarpLinkAppDelegate

open class WarpLinkAppDelegate: UIResponder, UIApplicationDelegate

Drop-in UIApplicationDelegate that forwards Universal Links to WarpLink. Use it directly, or subclass it and copy the two forwarding calls into your own delegate. No method swizzling is performed.

Member	Description
application(_:continue:restorationHandler:)	Forwards the incoming NSUserActivity to WarpLink.continue(_:).
application(_:open:options:)	Forwards the incoming URL to WarpLink.open(_:).

WarpLinkSceneDelegate

open class WarpLinkSceneDelegate: UIResponder, UIWindowSceneDelegate

Drop-in UIWindowSceneDelegate that forwards Universal Links to WarpLink, covering cold launch, warm continue, and URL contexts.

Member	Description
window	UIWindow?, the scene's window.
scene(_:willConnectTo:options:)	Forwards the connection options' user activities and URL contexts to WarpLink.continue(_:) and WarpLink.open(_:) on cold launch.
scene(_:continue:)	Forwards the incoming NSUserActivity to WarpLink.continue(_:) on warm continue.
scene(_:openURLContexts:)	Forwards each incoming URL context to WarpLink.open(_:).

Thread Safety

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