Skip to main content

Link Resolution Architecture

When a user clicks an OpenLynk deep link, a series of steps determine where they end up — the correct app, the app store, or a web fallback. This page explains the full resolution flow.

URL Structure​

Every OpenLynk deep link follows this format:

https://{app-slug}.openlynk.to/{link-slug}
  • app-slug — the subdomain identifying your app (set when you create the app in the dashboard)
  • link-slug — the unique identifier for a specific link

Example: https://myapp.openlynk.to/abc123

Subdomain Routing​

OpenLynk uses subdomain-based routing to associate links with apps. When a request arrives:

  1. Middleware extracts the subdomain from the Host header
  2. The subdomain is set as an internal header (x-whl-sub) for downstream processing
  3. The subdomain is used to look up the corresponding app

This means each app gets its own namespace. The slug abc123 under myapp.openlynk.to is entirely separate from abc123 under otherapp.openlynk.to.

Resolution Flow​

When a user clicks a deep link, the following steps execute:

Step-by-Step Details​

Step 1-2: App identification. The subdomain is extracted and matched against the apps table. If no app is found, a 404 is returned.

Step 3: Link lookup. The link slug is looked up within the scope of the matched app. Each link belongs to exactly one app, so slugs only need to be unique within an app.

Step 4: Device detection. The User-Agent header is parsed to determine the device type:

  • iOS — redirected via Universal Link (if supported) or to the App Store URL configured in the dashboard
  • Android — redirected via App Link (if supported) or to the Play Store URL configured in the dashboard
  • Desktop — redirected to the web fallback URL

Step 5: UTM parameters. If the link's metadata contains UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content), they are appended to the redirect URL as query parameters.

Step 6: Analytics logging. A click record is created asynchronously, capturing timestamp, device type, OS, country, user agent, referrer, UTM parameters, and an IP hash. This operation does not block the redirect.

Step 7: Redirect. The user is sent to the appropriate destination via an HTTP redirect.

Custom Domain Resolution​

If you use a custom domain (e.g., links.yourapp.com), the resolution flow is the same with one difference at Step 2:

Instead of matching the subdomain against the apps table, the full domain is looked up in the custom_domains table. The matched custom domain record points to the app, and resolution continues from Step 3 onward.

Short URL Resolution​

OpenLynk also supports short URLs in the format:

https://oplk.to/{code}

Short URL resolution follows a simpler path:

  1. Extract the code from the URL path
  2. Look up the code in the short_links table
  3. If the short link is associated with a full OpenLynk link, resolve it using the standard flow above
  4. If the short link points to an external destination_url, redirect directly to that URL

AASA and assetlinks.json Generation​

OpenLynk dynamically generates the verification files required by iOS and Android:

  • /.well-known/apple-app-site-association — generated per subdomain using the Team ID and Bundle ID from your app's iOS configuration in the dashboard
  • /.well-known/assetlinks.json — generated per subdomain using the package name and SHA-256 certificate fingerprint from your app's Android configuration in the dashboard

These files are served automatically. You do not need to host them yourself.

info

Changes to your iOS or Android configuration in the dashboard take effect immediately for new requests. However, iOS caches the AASA file and may take up to 24 hours to reflect changes on devices.

What's Next?​