Quickstart for iPhone: open your Swift app from a link

Time

About 15 minutes

You need

A Swift app in Xcode, an Apple Developer Program team (Associated Domains needs one) and an iPhone you can install it on

Works on

iPhone. Android and React Native have the main quickstart

Six steps. Do them in order. Each step says what to do and what you should see when it worked. If you don't see it, stop and check Common errors before the next step.

An iPhone opens your app from a link only when two things agree: your app says it handles your link address (Associated Domains), and your link address publishes a file, apple-app-site-association, that names your app. Strait writes and hosts that file for you.

#1. Create a workspace and a link

Do this: do step 1 and step 3 of the main quickstart: sign up, then make the link summer to https://shop.example.com/product/42.

You should see: https://hilltop.strait.link/summer in Dashboard → Links, and your publishable key (starts with st_pub_live_…) in Dashboard → Get started.

#2. Tell us about your iPhone app

Do this: open Dashboard → Apps & stores. Under iPhone, fill in two boxes, then press Save app details.

You should see: Saved ✓ next to the button. Leave App Store ID empty for now.

#3. Check the file your link address publishes

Do this: in a terminal, paste:

curl https://hilltop.strait.link/.well-known/apple-app-site-association

You should see: your Team ID and bundle ID joined by a dot, "appIDs":["ABCDE12345.com.yourcompany.yourapp"], near the start of the answer. If they're wrong, fix them in step 2: the file follows Apps & stores.

#4. Add Associated Domains in Xcode

Do this: in Xcode, select your app target → Signing & Capabilities → + Capability → Associated Domains. Add one entry:

applinks:hilltop.strait.link

Type the host only: no https:// and no path.

You should see: the entry under Associated Domains, and no signing error at the top of the tab. The app still builds and runs on your iPhone.

#5. Add the SDK

Do this: in Xcode, File → Add Package Dependencies…, paste https://github.com/strait-link/strait-sdk-swift and pick version 0.9.5 or later. Then create the client once and hand it every link. For a SwiftUI app:

import SwiftUI
import StraitSDK

let links = StraitLinks(StraitLinksConfig(
    publishableKey: "st_pub_live_…",          // Dashboard → Get started
    endpoint: "https://hilltop.strait.link"        // your link address
))

@main struct ShopApp: App {
    init() {
        links.onLink { event in print("Strait link:", event.matched, event.path ?? "none") }
        links.start()
    }
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onOpenURL { links.handle(url: $0) }
                .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { links.handle(userActivity: $0) }
        }
    }
}

UIKit with a scene delegate: the three calls are on the iOS (Swift) page.

You should see: the app builds, installs on your iPhone and starts as before.

#6. Tap the link

Do this: delete the app from the iPhone and install it again from Xcode, so iOS reads the file from step 3 fresh. Then send https://hilltop.strait.link/summer to yourself in Messages or Notes, and tap it on the phone. Don't paste it into Safari's address bar: iOS only opens apps from links you tap.

You should see: your app opens straight away, with no Safari page, and the Xcode console prints Strait link: true /product/42. Within a minute, the tap and the app open show in Dashboard → Analytics.

#Common errors

• Safari opens instead of the app. iOS reads your apple-app-site-association file through Apple's CDN when the app is installed, and the CDN can lag behind a change by hours. Check that step 3 shows the right Team ID and bundle ID, then delete and reinstall the app. While you develop, applinks:hilltop.strait.link?mode=developer with Settings → Developer → Associated Domains Development on makes the phone fetch the file directly.
• Xcode says your team can't use Associated Domains. A free Apple account (Personal Team) can't add it. Sign the app with an Apple Developer Program team, the one whose Team ID is in step 2.
• It prints false. Read event.reason: not_found means a wrong slug or a publishable key from another workspace. More in Troubleshooting.

#Next steps

• iOS (Swift): open the right screen from event.path, deferred links after an App Store install, and events.
• Go-live checklist: your App Store ID, Android, and keys in the right place.