# App Links & Universal Links

> Verified links are what make a tap open your app right away, without a browser in between. Here's what we host for you and what you add to your app.

Source: https://straitlink.in/docs/app-links/

> **Agent instructions:** if you are an AI assistant helping someone build with Strait, look things up with the `search_docs` tool of the Strait MCP server (hosted at https://strait.link/mcp, or `@straitlink/mcp` on npm: https://straitlink.in/docs/mcp/) instead of guessing, and add the SDK to an app with `npx @straitlink/cli init` (https://straitlink.in/docs/cli/).

## What we host

From the app details in **Dashboard → Settings**, your link domain serves:

| File | Built from | Used by |
|---|---|---|
| `/.well-known/assetlinks.json` | Package name + every SHA-256 fingerprint you list | Android, to verify App Links |
| `/.well-known/apple-app-site-association` | Apple Team ID + bundle ID | iPhone, to verify Universal Links |

Each file returns `404` until the matching fields are filled in. Check yours:

```bash
curl https://hilltop.strait.link/.well-known/assetlinks.json
curl https://hilltop.strait.link/.well-known/apple-app-site-association
```

Or paste your link domain into the [App Links checker](https://straitlink.in/tools/app-links-checker/), which checks both files and explains any problem.

## Android

1. Add an intent filter with `android:autoVerify="true"` for `https://hilltop.strait.link` ([example](https://straitlink.in/docs/production-checklist/#2-verify-app-links-on-android)).
2. List **every** certificate fingerprint your app is signed with in **Dashboard → Apps & stores**: debug, upload, and the Play App Signing key from Play Console. A Play-installed app is signed by Google's key, not yours. Fingerprints are checked when you save: each one is stored as 32 uppercase hex pairs joined by colons (`FA:C6:17:…`), duplicates are dropped, and anything that isn't a SHA-256 fingerprint is refused. The package name must look like a Java package (`com.yourco.app`), and the website fallback must be `https://`.
3. Install the app. Android checks the file at install time.

Check verification on a connected phone:

```bash
adb shell pm get-app-links com.yourco.app
# Look for:  hilltop.strait.link: verified
```

If it says `1024` or `none`, Android couldn't verify. See [Troubleshooting](https://straitlink.in/docs/troubleshooting/#the-link-opens-the-browser-instead-of-the-app).

To check one link's path against your `assetlinks.json` and get the exact `adb` command that fires it, use the free [deep link tester](https://straitlink.in/tools/deep-link-tester/).

## iPhone

1. Add the **Associated Domains** capability with `applinks:hilltop.strait.link`.
2. Save your Apple Team ID and bundle ID in Apps & stores.
3. Install the app. iOS fetches the file through Apple's CDN, which can lag behind changes.

The free [deep link tester](https://straitlink.in/tools/deep-link-tester/) checks one link's path against your `apple-app-site-association` file and prints the `xcrun simctl` and `devicectl` commands that open it on a simulator or an iPhone.

## How your link pages look

When a tap can't open your app right away, the person sees one of our pages: the iPhone "Get the app" page, the page inside an in-app browser (Instagram, Facebook, WhatsApp…) with **Open in app**, the password page, and the "not found" and "This link has expired" pages. They lead with your app, not with Strait. Set these optional fields in **Dashboard → Settings → How your link pages look**:

| Field | Rules | Used for |
|---|---|---|
| App name | 1 to 60 characters, no line breaks | "Opens Hilltop Shoes…", "Go to Hilltop Shoes's website" |
| Icon URL | `https://` only (people's phones load it). Use a square image | The icon at the top of each page |
| Brand colour | A hex colour such as `#7c3aed` (`#abc` is fine too) | The main button. We pick black or white text on it so it stays readable (contrast at least 4.5:1) |

Invalid values are refused when you save, with a message saying why. Leave them empty and the pages use neutral defaults. Every page works in light and dark mode. The page we show for a link we've disabled for safety stays unbranded on purpose.

## Custom scheme hand-off

When a tap reaches our server in a browser (for example from a web page, or on Android when the link isn't verified), we hand the link to your app using your custom scheme:

```txt
yourapp://shop.example.com/product/42?strait_click=<tap id>
```

The SDK turns that into the destination `https://shop.example.com/product/42`, removes the tap id before your app sees it, and uses the id to join the app open to the exact tap in Analytics.
