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.3 is source-ready through Swift Package Manager, but registry publication is pending. Confirm the sdk-v0.1.3 tag or use a reviewed local package path.

Choose another SDK when: navigation is owned by React Native, Capacitor, Unity, 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 package#

Add the repository in Xcode and pin the reviewed sdk-v0.1.3 tag. For local evaluation, add the sdk/ios directory as a local package.

text

https://github.com/NanFengCheong/locusvia.git
Product: LocusViaSDK
Revision: sdk-v0.1.3

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 .matched(let link): route(to: link.pathname, params: link.params)
case .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.