# Custom Domain

Links can run on your own host, for example `links.yourdomain.com` instead of
`your-org.godetour.link`. Point a DNS record at Detour. Detour then serves TLS
certificates, the `.well-known` association files, and per-app routing.

## Direct domain integration

In this mode, your users stay on your custom domain throughout their session. Detour handles domain hosting, SSL certificates, and the Universal / App Link verification files, with no manual server configuration needed.

:::note[Scale plan and above]
Direct domain integration is part of the **Scale** plan. Free and Starter
organizations serve links from their `.godetour.link` subdomain. See
[Billing](https://detour.swmansion.com/docs/platform/fundamentals/billing#available-plans) for what each plan
includes.
:::

### 1. Add the domain

1. Go to the **Detour Dashboard** and select your organization.
2. Navigate to **Organization Settings** and open the **Custom Domain** tab.
3. Enter your custom domain name and click **Add Domain**.

### 2. Update DNS records

After adding your domain, the dashboard displays the **exact DNS record** you need to configure at your DNS provider. The values are generated per-domain and unique to your setup, so always copy them directly from the dashboard.

:::tip
The dashboard shows a **Type**, **Name**, and **Value** table with a copy button next to each value. Use those exact values at your DNS provider.
:::

The record type depends on your domain:

- **Subdomains** (for example `links.yourdomain.com`) → a **CNAME** record, named after the subdomain label (`links`)
- **Apex/Root Domains** (for example `yourdomain.com`) → an **A** record, named `@`

If the dashboard shows additional records (for example a `TXT` record), add all of them. Extra records appear when your domain requires extra ownership verification, typically because it is already in use on Vercel elsewhere.

### 3. Verify and activate

With the records in place, click **Verify DNS** in the dashboard. Propagation usually takes a few minutes, occasionally up to 48 hours. The domain carries a **Pending DNS** badge until the record is detected, then switches to **Verified** and starts serving links.

:::tip
If your DNS finishes propagating later, you do not need to come back and click **Verify DNS** again. Detour re-checks every custom domain daily and also syncs the status when you open the dashboard.
:::

### 4. Assign apps

An active domain can be assigned to one or more apps, from the **Assign to apps** checklist on the same settings page. Once an app is assigned:

- Its short links and deferred links use your custom domain, for example `https://links.yourdomain.com/<app_hash>`.
- Detour serves that app's `/.well-known/apple-app-site-association` and `/.well-known/assetlinks.json` on the custom domain.

Unassigning an app, or removing the domain, reverts both back to your `.godetour.link` subdomain.

An organization can hold **several custom domains** at once and assign different
apps to different domains. An app is served from one domain at a time.

:::caution[Changing the host breaks old links]
Assigning or unassigning a domain replaces the host the app is served from
instead of adding one, and the links already shared on the old host stop working.
Read the section below before you do this on a live app.
:::

## Moving an app between hosts

An app is served from one host at a time. Three operations replace that host,
and they all behave the same way:

- assigning a custom domain
- unassigning it
- losing it when a paid plan is canceled

### What changes

- **The app's links move.** `https://<old-host>/<app-hash>/…` stops resolving,
  so a link already shared on the old host returns a 404.
- **The association files move with it**, so only the current host opens the app
  directly.
- **Short links are the exception.** They are looked up by their hash rather
  than by host, so they keep resolving on either one. On the old host they open
  in the browser instead of the app.

### Planning the switch

Change the host only when you are ready to publish links on the new one. Do not
change it while links on the old host are still being distributed. There is no
redirect from the old host, so anything already printed, scheduled or embedded on
it has to be reissued.

A host change also needs a new native build. The host goes into
`associatedDomains` on iOS and into the App Link `<intent-filter>` on Android,
and both are compiled into the app. Assign the domain first, then copy the
snippets the dashboard generates for it. They are written for the host the app is
assigned to at the time you copy them. The installation guide for your SDK
shows where each one goes.

Keep the DNS record for as long as links published on that host should keep
resolving. Removing it also removes the host from Detour, and no dashboard
setting restores those links.

---

## Legacy redirect-based integration

:::caution[Deprecated]
The redirect-based strategies below are **deprecated**. Migrate to [Direct domain integration](#direct-domain-integration) for automatic SSL, `.well-known` hosting, and no extra redirect hops.
:::

### Redirect target

Construct your redirect target using your **Organization Subdomain** and **App Hash**.

| Component        | Variable     | Example     |
| :--------------- | :----------- | :---------- |
| **Organization** | `<org_slug>` | `acme-corp` |
| **App Hash**     | `<app_hash>` | `x9y8z7`    |

### Strategy A: path-based redirect

**Best for** — providers with Layer 7 capabilities (Cloudflare Page Rules, AWS ALB, Vercel Edge, Netlify).

This method resolves directly to the canonical resource location, with no intermediate redirect.

- **Source** — `client-domain.com/*`
- **Destination** — `https://<org_slug>.godetour.link/<app_hash>/$1`
- **Status** — `301 Permanent Redirect`

**Example configuration (pseudo-code)**

```nginx
# Nginx / Reverse Proxy Example
server {
    server_name client-domain.com;
    location / {
        return 301 https://acme-corp.godetour.link/x9y8z7$request_uri
    }
}
```

### Strategy B: host-based redirect

**Best for** — basic DNS registrars (Namecheap, GoDaddy) or limited forwarding services that do not support path appending or complex routing rules.

If your provider validates the destination field as a strict hostname (disallowing slashes/paths), use the underscore-delimited format. The Detour edge layer detects this format and redirects the client to the canonical path.

- **Source** — `client-domain.com`
- **Destination** — `https://<org_slug>_<app_hash>.godetour.link`
- **Status** — `301 Permanent Redirect`

**Flow behavior**

1. The client requests `client-domain.com`.
2. Your provider redirects to `acme-corp_x9y8z7.godetour.link`.
3. Detour redirects to the canonical `acme-corp.godetour.link/x9y8z7`.

### Checklist

- **SSL/TLS** — your redirect service must terminate SSL for `client-domain.com`, or users see a certificate warning before the redirect happens.
- **Path preservation** — carry query parameters and sub-paths through the redirect where you can, so `.../dashboard` becomes `.../<app_hash>/dashboard`.
- **DNS propagation** — verify resolution with `curl`.

```bash
# Verification
curl -I https://client-domain.com

# Expected Output
HTTP/2 301
location: https://acme-corp.godetour.link/x9y8z7/
```

### Universal and App Links

iOS and Android verify app ownership by fetching a file from the URL the user clicked:

- **iOS** — `/.well-known/apple-app-site-association`
- **Android** — `/.well-known/assetlinks.json`

Both **abort verification** if that request answers with a 301 or 302, which is exactly what a redirect-based strategy does. Your web server needs a hybrid configuration:

1. **Serve the verification files locally.** The `.well-known` paths must return your app's JSON with `200 OK`, never a redirect.
2. **Redirect everything else** to the Detour platform.

**Example Nginx configuration**

```nginx
# 1. Serve your app's deep link files locally (NO REDIRECT)
location /.well-known/ {
    root /var/www/html;
}

# 2. Redirect everything else to Detour
location / {
    return 301 https://orgname.godetour.link/apphash$request_uri;
}
```

The Detour side of this setup is described in [Universal and App Links](https://detour.swmansion.com/docs/platform/fundamentals/universal-app-links). Apple documents the iOS requirements in [Supporting Associated Domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains), and Google documents the Android requirements in [Android App Links](https://developer.android.com/training/app-links/about).

## Support

:::tip[Need help?]
Support is available on the [Detour Discord server](https://discord.gg/tj7uFuymne) and through the [contact form](https://detour.swmansion.com/#contact).
:::