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. When every app's association files live on the same shared host, a device that has one app installed can see a link that belongs to a different app and still try to open the first one. One address per app removes that ambiguity: 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. Owners and admins also see a bar 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 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:

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

Release the updated build for every platform your app uses.

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:

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

Android:

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

React Native:

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. The dashboard Tester simulates routing and does not prove an installed build works, so use the test link for that.

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. It does not show how many users updated.

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 owner or admin 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. A shared host cannot give one app exclusive ownership of its links, so the address is the clean way to keep 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. 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, as an owner or admin. 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. The app's settings offer it once we run moves.
• 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 set no date for moving links, and the app's settings and setup page show no end date for the period while we are not moving links. An end date in the API is not a promise to move on that day. If we ever move the links still on the old subdomain, they go to the new one with the same slug, the old URLs redirect with a 301, and we tell you first. 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.

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.