# Quickstart for iPhone: open your Swift app from a link

> After this page, tapping https://hilltop.strait.link/summer on your iPhone opens your Swift app, and your app prints the screen it should show, /product/42.

- 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

Source: https://straitlink.in/docs/quick-start/iphone/

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](#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](https://straitlink.in/docs/quick-start/#1-create-a-workspace) and [step 3](https://straitlink.in/docs/quick-start/#3-make-a-link) 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**.

| Box | Example | Where to find it |
|---|---|---|
| Apple Team ID | `ABCDE12345` | Apple Developer → Membership details. 10 letters and digits |
| Bundle ID | `com.yourcompany.yourapp` | Xcode → your target → Signing & Capabilities |

**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:

```bash
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:

```text
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:

```swift title="ShopApp.swift"
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)](https://straitlink.in/docs/sdks/ios/#handle-deep-links) 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](https://straitlink.in/docs/troubleshooting/#the-app-opened-but-matched-is-false).

## Next steps

- [iOS (Swift)](https://straitlink.in/docs/sdks/ios/): open the right screen from `event.path`, deferred links after an App Store install, and events.
- [Go-live checklist](https://straitlink.in/docs/production-checklist/): your App Store ID, Android, and keys in the right place.