WarpLink iOS SDK API Reference (Swift)

The complete Swift API reference for the WarpLink iOS SDK: initialization, deep link handling, and attribution methods.

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.0"`).
`isConfigured`	`Bool`	Whether `configure()` has been called. Thread-safe.

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

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, .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 fingerprint. 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]`	Custom parameters on the link. 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). Useful for reporting, not for a trust decision.
`matchGuaranteed`	`Bool`	True only for a deterministic match. Gate anything sensitive (auto sign-in, showing personal data) on this rather than on a confidence threshold.

Access custom params with the typed accessors:

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

MatchType

public enum MatchType: String, Codable, Sendable

Case	Description
`.deterministic`	Matched via IDFV. Confidence is always 1.0.
`.probabilistic`	Matched via enriched fingerprint. Confidence varies.

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.
`.decodingError(Error)`	Response parsing failed.

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

API Reference