# Your App's Own Link Address

## What this is and why

Every WarpLink app has its own link address: `yourapp.aplnk.to`, with its own Apple App Site
Association and Digital Asset Links files. Links that belong to no app stay on `aplnk.to`.

Apple and Google only look at the host in your entitlement, not at the link path. With one
address per app, the association files on your host list your app and nothing else.

## Your existing links keep working

If your app existed before app addresses, none of its links change.

- **Your links stay where they are.** A link on `aplnk.to` stays on `aplnk.to` and keeps opening
  your app. A link on one of your custom domains stays on that domain.
  `aplnk.to` stays one of your app's allowed link domains, with no end date.
- **Your default is set for you.** Existing apps start with the domain of their most recent link
  as the default for new links. That is `aplnk.to`, or one of your custom domains when that
  domain is live and your plan serves it. If your latest link is on anything else, such as a custom
  domain that is not live or is over your plan's limit, new links default to `aplnk.to`. Owners
  and admins can change the default per app in the app's Settings.
- **Nothing moves.** Choosing your app's own address never edits a link you already have and never
  creates a redirect.
- **You choose when.** The address is yours to set up when you are ready. New apps use their own
  address from the start.

## Find your app's address

Each app shows its address in three places:

- **Dashboard.** Open the app, then **Settings**. The checklist shows the full host and the
  three steps below. A bar also appears at the top of the dashboard until the
  address is the default. **Not now** hides it for 24 hours, and **Dismiss** hides it for good.
- **MCP.** Call the `get_app` tool. The response includes `link_handle`, `link_domain`,
  `legacy_apex_enabled`, `default_link_domain`, and `allowed_link_domains`.
- **API.** `GET /v1/apps/{id}` returns the same fields. See [API Overview](https://warplink.app/docs/api) for
  authentication.

## Set it up in three steps

1. **Choose your address.** It starts as a name made from your app's name. You can change it in
   the app's settings until a link uses it, as often as you like, on every plan.
2. **Add it to your app.** Add the address to your build, ship the build, and test it on a phone.
   The steps are below.
3. **Make it the default.** New links then use your address unless you choose another domain.

The steps are guidance, not a locked wizard. You can do them in any order, and nothing blocks the
default if you want to choose it early.

## Update your app

Add the address to your app next to `aplnk.to`. Replace `yourapp` with your app's own handle.
Keep `aplnk.to` in your app next to the new address, so links you already have keep opening it.

**iOS.** In Xcode, under **Signing & Capabilities > Associated Domains**, add:

```
applinks:yourapp.aplnk.to
```

**Android.** In `AndroidManifest.xml`, add a second `<data>` line to your existing WarpLink intent
filter:

```xml
<data android:scheme="https" android:host="yourapp.aplnk.to" />
```

Release the updated build for every platform your app uses.

Never add `applinks:*.aplnk.to` as a wildcard entitlement. A wildcard claims every subdomain
under `aplnk.to`, including other apps' subdomains, not only yours. List your own address
explicitly.

## Declare the host in the SDK

Pass your app's host in `linkDomains` as well as the OS declarations above. The SDK accepts a
host locally before server validation completes, which matters on the first launch of a build
that has no network. Every SDK recognizes `aplnk.to` on its own.

**iOS:**

```swift
WarpLink.configure(
    apiKey: "YOUR_SDK_KEY",
    options: WarpLinkOptions(linkDomains: ["yourapp.aplnk.to"], onLink: routeLink)
)
```

**Android:**

```kotlin
WarpLink.configure(
    context = this,
    apiKey = "YOUR_SDK_KEY",
    options = WarpLinkOptions(linkDomains = listOf("yourapp.aplnk.to"), onLink = ::routeLink)
)
```

**React Native:**

```typescript
WarpLink.configure({
  apiKey: 'YOUR_SDK_KEY',
  linkDomains: ['yourapp.aplnk.to'],
  onLink: routeLink,
});
```

**Flutter:**

```dart
await WarpLink.configure(
  apiKey: 'YOUR_SDK_KEY',
  linkDomains: ['yourapp.aplnk.to'],
  onLink: routeLink,
);
```

## Test it on a phone

Every app address has a permanent test link: `https://yourapp.aplnk.to/test`. The app's
settings page shows it with a copy button and a QR code.

Tap the link on a phone with your new build, from a message or a note. If your app opens, the
build is set up. Your app may show a link-not-found screen, and that is expected: `test` is not a
real link.

If the link opens in the browser instead, the page says "Your app did not open this link. Check
the setup steps." Check that the build lists the address, then try again. An older build, or a
phone with no app installed, shows the same page.

The slug `test` is reserved on app addresses, so no link can use it there. It stays free on
`aplnk.to` and on custom domains. Opening the test link adds no click, install or attribution.
Use the test link to confirm an installed build works.

When your app has opened links on its address, the settings page also shows "Seen opening on N
devices", based on network addresses in the last 14 days.

iOS caches your Associated Domains association file on the device, not just at install time. A
device that installed your app before a change may keep using its cached file for up to about a
week before it checks again. Users who install afterward pick up the change immediately.

## Make it the default for new links

The default decides which domain a new link gets when you name none. Existing apps start with the
domain of their most recent link, or `aplnk.to` when that domain cannot serve new links. Any team member can change it per app in the app's Settings, through `PUT /v1/apps/{id}/link-domain`, or with the
`set_app_link_domain` MCP tool. Pick your app's own address, `aplnk.to`, or a live custom domain,
and change it back at any time.

- **Existing links keep their addresses.** A default change updates no link and creates no
  redirect.
- **An explicit domain wins.** A link that names a domain always gets that domain. We never
  replace it with the default.
- **On older builds.** A link on your address opens your app on builds that list the address. On
  older builds it opens in the browser and goes to your fallback.
- **Reversible.** You can change the default to any allowed domain, `aplnk.to` included, whenever you like.

A new link can also choose any allowed domain one by one, in the link form, the API or MCP,
whatever the default is.

## When two apps share `aplnk.to`

`aplnk.to` still lists every app that existed before app addresses, because those apps' links
still live there. Listing both hosts in a build keeps every link opening your app. Your app's own address keeps
your app's links apart from other apps' links. Setting it up is optional, and you choose when.

## Safe order for a build

1. Add `yourapp.aplnk.to` to your app next to `aplnk.to`. Do not remove the `aplnk.to` entry.
2. Ship the build on every platform the app uses.
3. Open the test link on a phone with the new build.
4. Make the address the default when you want new links on it.

Both hosts keep working, so there is no rush, and users on older builds keep opening links on
`aplnk.to`.

On Android 11 and earlier, verification requires matching `assetlinks.json` files for every
manifest host. WarpLink serves a file for each host, so a build that declares both hosts verifies
both. See [Android's verification rules](https://developer.android.com/training/app-links/verify-applinks).
iOS verifies the two Associated Domains independently.

## Changing your app's address

While no link and no redirect uses your app's address, you can change it as often as you like, on
every plan, with a plain save in the app's settings. There is no confirmation and no rename
period. Saving the name unchanged confirms it. Through the API, send `expected_link_handle` with
`link_handle`, the handle you last read.

A released address is held for 7 days. Only your app can take it back during that time, and any
other app can claim it after that.

Once a link or a redirect uses the address, a change is a rename. Choosing your own address as the
default never makes a rename free, and changing the default again never bypasses the
rename rules.

## Renaming a subdomain

Once a link or a redirect uses your app's address, you can rename it once more, on every
plan. Links you already made stay on the old address.

After a rename, the old subdomain keeps working, including its association files, so your
app keeps opening links from it.

- **Extend.** Through `POST /v1/apps/{id}/extend-subdomain-rename` or the `extend_subdomain_rename`
  MCP tool you can add 1 month to the period's end date, up to 2 times.
- **New links.** During the period new links never use the old subdomain, and a new link cannot
  take a slug that a link on the old subdomain still has. That request fails and names the link.
- **The old address keeps working.** We tell you first if links move. If we move the links still on the old subdomain, they go to the new one with the same
  slug and the old URLs redirect with a `301`. A link whose slug is already
  taken on the new subdomain stays where it is until you pick a new slug or keep it, from the
  app's settings.
- **Builds.** Once the old subdomain stops serving your app's files, app builds that do not list
  the new subdomain open these links in the browser. Ship a build with the new subdomain soon, so a move never catches your app out. On Android 11 and earlier, a build that still lists the old
  host can fail link verification for every host.
- **Confirm.** The dashboard asks you to type the new name when links use the old host. Through
  the API you pass `confirm: true` when links use the old host.
- **One at a time.** You cannot rename again, including renaming back, while the old subdomain is still active.

On the Android tab, the setup page in the dashboard shows the old subdomain while its period is
open. On Android 11 and earlier, a build that still lists the old host can fail link verification
for every host.

An old subdomain name stays reserved for the whole period, and after it while links or redirects use it.

## New apps

A new app always uses its own address. Creating an app asks for it, prefilled from the app name. Keep it or edit it, then
confirm. Through the API and MCP, leave `link_handle` out and we derive it from the app name, adding a
suffix if that name is taken. A `link_handle` you send that another app already holds returns
`APP_HANDLE_TAKEN`.
