Skip to main content

Custom Domain Configuration

Paid feature

Custom domain support is currently available on paid plans — we're planning to bring it to the Starter plan soon. Reach out to upgrade or learn more.

Direct Domain Integration (Self-Serve)​

In this mode, your users stay on your custom domain (e.g., links.yourdomain.com) throughout their session. Detour automatically handles the domain hosting, SSL certificates, and Universal / App Link verification files — no manual server configuration needed.

1. Configure the Domain in the Dashboard​

  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 Your DNS Records​

After adding your domain, the dashboard will display the exact DNS record you need to configure at your DNS provider. The values are generated per-domain and unique to your setup — 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 (e.g., links.yourdomain.com) → a CNAME record
  • Apex/Root Domains (e.g., yourdomain.com) → an A record

If the dashboard shows additional records (e.g., a TXT record), add all of them — this happens when your domain requires extra ownership verification.

3. Verify and Activate​

Once you have updated your DNS records, click Verify DNS in the dashboard. It may take a few minutes for DNS changes to propagate. After verification succeeds, the domain status will change to active.

4. Assign Apps to the Custom Domain​

After activating your domain, you can assign it to one or more of your Apps under the Assign to apps checklist on the same settings page.

Once an App is assigned:

  • All short links and deferred links generated for that App will automatically use your custom domain (e.g., https://links.yourdomain.com/<app_hash>).
  • Detour will automatically serve the required Universal Link / App Link verification files (/.well-known/apple-app-site-association and /.well-known/assetlinks.json) directly on your custom domain.

Support​

Need help or found a bug? We are here to assist you! Join our developer community on Discord for quick support, or reach out via the Contact Form on our main homepage.

Legacy: Redirect-Based Integration (Deprecated)​

Deprecated

The redirect-based integration strategies below are deprecated. We recommend migrating to Direct Domain Integration for a better experience with automatic SSL, .well-known hosting, and no extra redirect hops.

Target Resolution​

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

ComponentVariableExample
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 is most efficient as it resolves directly to the canonical resource location, avoiding intermediate hops.

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

Example Configuration (Pseudo-code):

# 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. Our edge layer will detect this format and automatically redirect 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. Client requests client-domain.com
  2. Provider redirects to acme-corp_x9y8z7.godetour.link
  3. Detour redirects to acme-corp.godetour.link/x9y8z7 (Canonical)

Implementation Checklist​

  • SSL/TLS: Ensure your redirect service handles SSL termination for client-domain.com to avoid certificate warnings before the redirect occurs.
  • Path Preservation: If possible, ensure query parameters and sub-paths are preserved during the redirect
    (e.g., .../dashboard -> .../<app_hash>/dashboard).
  • DNS Propagation: Verify resolution using curl.
# Verification
curl -I https://client-domain.com

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

Mobile operating systems (iOS and Android) verify app ownership by fetching a configuration file from the URL the user clicked.

  • iOS: checks /.well-known/apple-app-site-association
  • Android: checks /.well-known/assetlinks.json

When using redirect-based strategies, mobile operating systems will abort verification if the /.well-known/ request returns a 301/302 redirect. You must configure a hybrid approach on your web server:

  1. Serve verification files locally: The .well-known paths must return the JSON files for your specific app with a 200 OK status — no redirect.
  2. Redirect all other traffic to the Detour platform.

Example Nginx configuration:

# 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;
}

Official Resources:

We are Software Mansion.

Hire us