iOS SDK

Resolve Universal Links, deferred journeys, and outcomes from Swift applications.

Choose this SDK when#

Use the iOS SDK for Swift applications targeting iOS 15 or later when native application code owns Universal Link routing.

Warning

LocusViaSDK 0.1.4 is available from a reviewed source checkout. Registry publication is pending, and the monorepo URL cannot be added directly as a Swift package because its package manifest is nested.

Choose another SDK when: navigation is owned by React Native or shared Kotlin code. Integrate at the shell that actually receives the URL.

Before you start#

Xcode 15 or later and Swift 5.9 or later.
An Associated Domains entitlement matching the verified LocusVia domain.
A LocusVia App Platform ID, SDK key, and API origin from the same environment.

Note

Use an environment-scoped public SDK key. Never embed a server, admin, or privileged credential in an app.

1. Add the reviewed local package#

Obtain a reviewed checkout, then add its sdk/ios directory as a local package in Xcode. Pin the checkout revision in your build process; a registry or remote Swift package install is not available yet.

swift

.package(path: "../locusvia/sdk/ios")
// Product: LocusViaSDK

2. Create the client#

Create one client with an environment-scoped SDK key. Clipboard-assisted processing is an explicit product choice and may trigger an operating-system prompt.

swift

import LocusViaSDK

let config = try LocusViaConfig(
    appID: "REPLACE_WITH_APP_ID",
    apiKey: "REPLACE_WITH_SDK_KEY",
    baseUrl: "https://staging.locusvia.com",
    linkProcessingMode: .all,
    shouldUseClipboard: false
)
let client = LocusViaClient(config: config)

3. Resolve and route#

Handle matched, not-found, and server-error results separately. A not-found result is a normal first open, not an exception.

swift

switch try await client.resolveDeferredLink() {
case .native(let link):
    if let pathname = link.pathname {
        route(to: pathname, params: link.params ?? [:])
    } else {
        showFallback()
    }
case .unattributed, .notFound: showHome()
case .error: showFallback()
}

Verify the integration#

Fetch apple-app-site-association over HTTPS with no redirect and confirm your app identifier and paths.
Install a signed build, tap a Universal Link from outside the app, and confirm the destination opens directly.
Exercise the fallback-install-first-open journey and confirm not-found remains a safe normal launch when no match exists.

Warning

A successful build proves source compatibility only. Test a real link on the target browser or signed device before release.

Troubleshoot by symptom#

Safari opensVerify the Associated Domains entitlement, app identifier, association-file content type, and CDN cache.

Config initializer throwsConfirm non-empty app ID and SDK key and a valid HTTP(S) API origin.

Deferred result is not foundTreat it as normal first open unless a real click/install journey was expected; then inspect the journey trace.

Unexpected pasteboard promptSet shouldUseClipboard to false unless the user-mediated clipboard recovery flow is intentionally enabled.

Next steps#

Confirm your domain associations, then add conversion and revenue events only after link resolution works end to end.