How Deep Linking Works

A deep link is a URL that opens a specific screen inside a mobile app rather than a web page. Instead of landing on your app's home screen, users go directly to the content they were looking for — a product page, a profile, an article, or any other destination.

This page explains the types of deep links, how they work on each platform, and how OpenLynk handles metadata.

Types of Deep Links

Standard Deep Links

A standard deep link opens the app directly if it is already installed. If the app is not installed, the link fails or falls back to a web URL.

Example flow:

1. User taps https://myapp.openlynk.to/abc123
2. OS recognizes the URL as belonging to your app
3. App opens to the destination encoded in the link (e.g., /product/123)

Deferred Deep Links

A deferred deep link preserves the destination even when the app is not installed. The user is sent to the app store first, and after installing, the app opens to the correct screen.

See How Deferred Deep Linking Works for a detailed explanation.

Contextual Deep Links

A contextual deep link carries custom metadata (key-value pairs) in addition to the destination. This metadata is available to your app when the link is opened, enabling use cases like:

• Attribution (which campaign drove this install?)
• Personalization (show a welcome screen with the referrer's name)
• Promotions (apply a discount code automatically)

In OpenLynk, all deep links can carry metadata, making every link contextual.

Universal Links (iOS)

Universal Links are Apple's mechanism for deep linking on iOS. They use standard HTTPS URLs that the operating system intercepts and routes to your app.

How they work:

1. You register your domain in your app's Associated Domains entitlement (e.g., applinks:myapp.openlynk.to)
2. OpenLynk hosts an Apple App Site Association (AASA) file at https://myapp.openlynk.to/.well-known/apple-app-site-association
3. When iOS encounters a URL matching your domain, it checks the AASA file to determine if the URL should open your app
4. If the app is installed and the AASA file matches, iOS opens the app directly without loading the web page

note

The AASA file is generated dynamically by OpenLynk based on your app's iOS configuration in the dashboard. You do not need to host it yourself.

App Links (Android)

App Links are Android's equivalent of Universal Links. They use verified HTTPS URLs that Android routes to your app.

How they work:

1. You declare intent filters in your AndroidManifest.xml for your OpenLynk subdomain
2. OpenLynk hosts a Digital Asset Links file at https://myapp.openlynk.to/.well-known/assetlinks.json
3. When Android encounters a matching URL, it verifies the assetlinks.json file and opens your app
4. If verification succeeds and the app is installed, Android opens the app without showing a disambiguation dialog

note

The assetlinks.json file is generated dynamically by OpenLynk based on your app's Android configuration (SHA-256 fingerprint and package name) in the dashboard.

In-App Browser Detection

When users click links inside social media apps (Instagram, Facebook, Twitter/X), the link opens in an in-app browser rather than the system browser. In-app browsers do not support Universal Links or App Links, which means the OS cannot route the URL to your app.

OpenLynk detects in-app browsers by inspecting the User-Agent string. When an in-app browser is detected, OpenLynk displays an interstitial page that prompts the user to open the link in their system browser, where Universal Links and App Links function correctly.

Metadata

Every OpenLynk deep link can carry metadata — a set of key-value pairs attached when the link is created.

System-Added Fields

When you create a link, OpenLynk automatically adds the following fields to the metadata:

Field	Description
destination_path	The path portion of the destination (e.g., /product/123)
destination_full	The full destination including query parameters
created_via	How the link was created ("sdk", "dashboard", etc.)

Custom Metadata

Any additional key-value pairs you provide when creating the link are stored as custom metadata. Common examples:

{
  "campaign": "summer-sale",
  "utm_source": "instagram",
  "referrer_id": "user_456",
  "discount_code": "SAVE20"
}

Accessing Metadata in Your App

When a deep link opens your app, the SDK provides two ways to access metadata:

• parameters — contains only your custom metadata, with internal fields stripped out. Use this for application logic.
• metadata — contains the full metadata object including system fields. Use this for debugging or when you need access to system-generated values.

See the Data Types Reference for the exact fields available on each type.

What's Next?

• Set up iOS Universal Links for your app
• Set up Android App Links for your app
• Learn how to handle deep links in your app code
• Understand deferred deep linking for users who do not have your app installed