Docs
← Back to siteDashboardStart free

Domains & Association Files

Set up LinkTrail link domains: a free linktrail.io subdomain or your own host with CNAME and TXT records, its statuses, and the association files served.

A link domain is the host in your link URLs. LinkTrail serves the short links on it and the two association files that let iOS and Android open your app instead of the browser. There are two kinds:

Provisioned subdomainCustom domain
Exampleyourapp.linktrail.iogo.yourbrand.com
DNSNone — LinkTrail owns the zoneA CNAME and a TXT record at your DNS provider
TLSImmediateIssued automatically once DNS checks pass
ReadyAs soon as it is addedWhen its status reaches Active
PlansEvery planGrowth (up to 5) and Scale (unlimited)

Domains belong to a workspace, like apps, links and API keys, and a host can be in one workspace only — adding a host another workspace uses fails with "This domain is already in use".

  1. Add the domain

    Dashboard → Domains → Add domain. Choose Custom domain and enter the host — a subdomain you control, such as go.yourbrand.com. The next screen shows the exact DNS records to add.

  2. Add the DNS records

    Add both records at your DNS provider, copying the values from the dashboard:

    DNS recordsText
    Type   Name                          Value
CNAME  go.yourbrand.com              custom.linktrail.io
TXT    _linktrail.go.yourbrand.com   linktrail-verify=<token>
    • The CNAME sends the host's traffic to LinkTrail; the TXT record proves you control the zone.
    • Remove any A or AAAA record on the host first. An address record and a CNAME cannot coexist, and most providers silently ignore the CNAME — the verify check names the conflicting record.
    • A TXT name can hold several values, so linktrail-verify= entries for staging and production can sit side by side.

  3. Verify

    Click Verify once the records are live. The checks run in order — CNAME, TXT, then TLS — and the domain moves through three statuses:

    StatusDashboard showsMeaning
    pending_dnsAction neededA DNS record is missing or conflicting. The check says which, and the fix.
    pending_tlsIssuing certificate…DNS passed; the certificate is being issued, usually within a few minutes.
    activeActiveShort links redirect and the association files are served.
    Warning

    A custom domain's short links only redirect once it is Active. Don't put the domain in a campaign while it is still pending.

  4. Point your app at it

    Add the host to the app and ship an update: applinks:go.yourbrand.com in the iOS Associated Domains entitlement (Xcode setup), and an android:autoVerify="true" intent filter for the host on Android (Deep-link setup). If you set linkDomains in the SDK options, add the host there too.

Association files

Every active domain serves /.well-known/apple-app-site-association and /.well-known/assetlinks.json, generated from the apps registered in its workspace. There is nothing to upload: the AASA lists each iOS app as <Team ID>.<bundle ID>, and assetlinks.json lists each Android package with its SHA-256 fingerprints. To change them, edit the app in the dashboard.

  • By default a domain serves every app in the workspace. To serve a subset, set associatedAppIds with the Domains API.
  • A removed domain serves no files and its short links stop redirecting. Adding the same host again from the same workspace brings it back with its links — a subdomain as Active, a custom domain as Action needed (pending_dns), to be verified again before its links redirect.
  • iOS devices read the AASA through Apple's CDN, which caches it — after a change, reinstall the app to pick it up sooner. Android caches its verification per device; see Troubleshooting.
Check what a domain servesShell
curl -s https://go.yourbrand.com/.well-known/apple-app-site-association
curl -s https://go.yourbrand.com/.well-known/assetlinks.json

Or check both files, the Content-Type and redirects with the free Universal Links validator.