DEV Community: LinkTrail

Deferred Deep Links in Android: Complete Integration Guide

LinkTrail — Sat, 26 Sep 2026 19:12:49 +0000

Same problem as always: a user without your app taps a link, gets routed to the Play Store, installs, opens the app — and lands on the default launch screen with no memory of what they originally tapped. App Links get an existing user routed correctly. They do nothing for the install gap. This is the Android-native (Kotlin) integration guide for closing that gap with LinkTrail, alongside the direct case so both work end to end.

The two cases

Direct link — app is already installed. Android hands your Activity an Intent with the link's data, through onCreate (cold start) or onNewIntent (already running).
Deferred link — app is not installed. There's no Intent carrying anything, because the app wasn't there to receive it. The match has to happen server-side, keyed off something durable enough to survive the install (device/install-time fingerprint), and get pulled down on first open.

1. Add the dependency

// app/build.gradle
dependencies {
    implementation("com.linktrail:android-sdk:1.4.0")
}

2. Configure App Links in the manifest

This part is identical to correct deep linking in general — deferred linking is built on top of it, not instead of it:

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="links.yourapp.com" />
    </intent-filter>
</activity>

android:launchMode="singleTask" matters — without it, a second intent while the app is already running can spin up a duplicate Activity instead of hitting onNewIntent on the existing one.

Serve assetlinks.json at https://links.yourapp.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourcompany.yourapp",
    "sha256_cert_fingerprints": ["YOUR:APP:SIGNING:CERT:FINGERPRINT"]
  }
}]

Get the SHA-256 fingerprint from your actual release signing config, not your debug keystore — this is the single most common reason App Links verify in testing and silently fail in production:

keytool -list -v -keystore your-release-key.jks -alias your-key-alias

3. Initialize the SDK

In your Application class, as early as possible:

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        LinkTrail.configure(this, apiKey = "YOUR_LINKTRAIL_API_KEY")
    }
}

4. Handle the direct case

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        handleIntent(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)
        handleIntent(intent)
    }

    private fun handleIntent(intent: Intent?) {
        val data: Uri? = intent?.data
        if (data != null) {
            LinkTrail.resolve(data) { link ->
                routeFromLink(link)
            }
        }
    }
}

onCreate covers a cold start where the app is launched directly by the link. onNewIntent covers the app already being alive in the background. Both need to be wired — missing either one means links only half-work depending on app state, which is a very confusing bug to chase down later.

5. Handle the deferred case

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    handleIntent(intent)

    // Only relevant on first open after install — a no-op on every
    // subsequent launch, so it's safe to always call.
    LinkTrail.getFirstOpenLink { link ->
        link?.let { routeFromLink(it) }
    }
}

getFirstOpenLink resolves from a server-side match, not from anything the OS handed you — there is no Intent data to read on a cold install, which is exactly the problem it exists to solve.

6. Route on the resolved link

private fun routeFromLink(link: LinkTrailLink) {
    when (link.path) {
        "/product" -> {
            val id = link.params["id"]
            navController.navigate("product/$id")
        }
        "/invite" -> {
            val ref = link.params["ref"]
            navController.navigate("onboarding?referrer=$ref")
        }
        else -> navController.navigate("home")
    }
}

7. Test it properly

Direct, cold start: app force-stopped, tap a link, confirm onCreate → handleIntent fires with the right data.
Direct, warm: app open in background, tap a link, confirm onNewIntent fires instead — this is the path people forget to test.
Deferred: uninstall completely (not just force-stop — App Links verification and any local state need a real uninstall), tap the link, go through the Play Store, install, open. Confirm getFirstOpenLink resolves with the same path.
Verify App Links independently of your app, with adb:

adb shell pm get-app-links com.yourcompany.yourapp

If that command doesn't show your domain as verified, nothing above will work, and it's worth checking before you spend time debugging the SDK — the fingerprint or the assetlinks.json host is the far more common culprit.

What's next

This gets you routed correctly, in both states, with the actual link data available. It doesn't cover attribution — matching an install back to which specific campaign or creative drove it — which sits on top of the same underlying resolution and is worth its own post.

Deferred Deep Links in iOS: Complete Integration Guide

LinkTrail — Sat, 26 Sep 2026 19:12:05 +0000

Universal Links solve exactly one case: a user who already has your app taps a link and iOS hands it straight to scene(_:continue:). They do nothing for the user who doesn't have the app yet — taps the link, gets sent to the App Store, installs, opens — and lands on a plain launch screen, because there's no OS mechanism to carry anything across an install on iOS. This is the native Swift integration guide for both cases with LinkTrail.

The two cases

Direct link — app is already installed. iOS routes the tap to your app via Universal Links, delivered as an NSUserActivity of type NSUserActivityTypeBrowsingWeb.
Deferred link — app is not installed. Nothing is delivered by the OS on first launch — no Universal Link, no custom scheme, nothing. The match has to happen server-side and get pulled down on first open, which is a fundamentally different mechanism from Universal Links, not an extension of them.

1. Add the SDK

CocoaPods:

# Podfile
pod 'LinkTrail', '~> 1.3'

Or Swift Package Manager — add https://github.com/linktrail/linktrail-ios-sdk in Xcode's package manager.

2. Enable Associated Domains

In Xcode, under Signing & Capabilities, add the Associated Domains capability:

applinks:links.yourapp.com

Serve the AASA file at https://links.yourapp.com/.well-known/apple-app-site-association — no extension, Content-Type: application/json, and critically: no redirects. Apple's crawler doesn't follow them.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAMID.com.yourcompany.yourapp"],
        "components": [{ "/": "/*" }]
      }
    ]
  }
}

TEAMID is your Apple Developer Team ID, not your bundle ID alone — this is the single most common typo in an AASA file, and it fails silently: the file loads fine, it just never matches.

3. Initialize the SDK

In AppDelegate (or your App struct's init if you're on pure SwiftUI lifecycle):

import LinkTrail

@mainclass AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        LinkTrail.configure(apiKey: "YOUR_LINKTRAIL_API_KEY")
        return true
    }
}

4. Handle the direct case

Universal Links arrive through continue userActivity, either in AppDelegate or your SceneDelegate, depending on your app's lifecycle:

func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return false
    }

    LinkTrail.resolve(url) { link in
        self.routeFromLink(link)
    }
    return true
}

If you're using the UIScene lifecycle instead:

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else { return }

    LinkTrail.resolve(url) { link in
        self.routeFromLink(link)
    }
}

Only implement one of these — whichever matches your actual app lifecycle. Implementing both and expecting either to silently no-op is a common source of double-handling bugs.

5. Handle the deferred case

Call this once, on first launch — it's safe to call on every launch, since it resolves to nil on every run after the first:

func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    LinkTrail.configure(apiKey: "YOUR_LINKTRAIL_API_KEY")

    LinkTrail.getFirstOpenLink { link in
        guard let link = link else { return }
        self.routeFromLink(link)
    }

    return true
}

Under the hood this is a probabilistic match against signals captured when the link was tapped in the browser — there's no cookie or identifier surviving the App Store install, so it's inherently a best-effort resolution, not a guarantee. That's worth knowing going in: test it, but don't expect 100% match rates in every environment (the simulator in particular is not representative).

6. Route on the resolved link

func routeFromLink(_ link: LinkTrailLink) {
    switch link.path {
    case "/product":
        let id = link.params["id"]
        coordinator.navigate(to: .productDetail(id: id))
    case "/invite":
        let ref = link.params["ref"]
        coordinator.navigate(to: .onboarding(referrer: ref))
    default:
        coordinator.navigate(to: .home)
    }
}

7. Test it for real

Direct: send yourself the link over Messages or Notes (Safari's own address bar won't trigger a Universal Link — it treats it as browsing, not an app hand-off). Tap it with the app installed, confirm continue userActivity fires.
Deferred: delete the app completely, tap the link, go through the App Store, install, open cold. Confirm getFirstOpenLink resolves — and don't test this on the same device/network too many times in a row; iOS and ad networks alike will start deprioritizing signals that look automated.
Validate the AASA file independently of your app — a 404, an HTML error page instead of JSON, or a redirect from yourapp.com to www.yourapp.com (Apple treats those as different hosts and doesn't follow the hop) are the most common reasons Universal Links silently fail, and none of them show up as a crash or an error in your app — they just don't route.

What's next

This gets both cases routed with real link data in hand. What it doesn't cover is attribution — matching an install back to the campaign or creative that drove it, layered on top of this same resolution — which deserves its own post.

Deferred Deep Links in Flutter: Complete Integration Guide

LinkTrail — Sat, 26 Sep 2026 19:11:47 +0000

Flutter's go_router or uni_links-based setup gets you clean routing once a link actually reaches the app. That's the easy 90%. The part that quietly doesn't work by default on either platform is a new install: user taps a link, has no app, goes through the store, installs, opens — and Flutter boots to your normal initial route with zero memory of the link. This is the complete guide to wiring up both the direct and deferred cases in a Flutter app with LinkTrail, covering the Dart side and the native config both platforms still require underneath it.

The two cases

Direct link — app is already installed. Both iOS and Android hand the link to the native layer (Universal Link / App Link), and it needs to be routed into Flutter through a platform channel.
Deferred link — app is not installed. Neither OS delivers anything on first launch — there's no event to catch, on either platform. Resolving it means matching against a server-side record from a signal captured at tap-time, which is a different mechanism from link routing entirely, not a Flutter-side gap.

Flutter doesn't remove the native setup — it just needs to happen once, in each platform project, same as a fully native app.

1. Add the package

# pubspec.yaml
dependencies:
  linktrail_flutter: ^1.1.0

flutter pub get

2. Native configuration (still required)

Android — `android/app/src/main/AndroidManifest.xml`

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">

    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" android:host="links.yourapp.com" />
    </intent-filter>
</activity>

Serve assetlinks.json at https://links.yourapp.com/.well-known/assetlinks.json with your release-key SHA-256 fingerprint — a debug-keystore fingerprint here is the single most common reason this works in dev and silently fails in production.

iOS — Associated Domains

In Xcode, add the Associated Domains capability to the Runner target:

applinks:links.yourapp.com

Serve apple-app-site-association at https://links.yourapp.com/.well-known/apple-app-site-association, Content-Type: application/json, no redirects:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAMID.com.yourcompany.yourapp"],
        "components": [{ "/": "/*" }]
      }
    ]
  }
}

Both files need to exist and be correct before anything on the Dart side matters — if they're wrong, the OS never hands your app anything to resolve in the first place.

3. Initialize the SDK

import 'package:linktrail_flutter/linktrail_flutter.dart';
import 'package:flutter/material.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await LinkTrail.configure(apiKey: 'YOUR_LINKTRAIL_API_KEY');

  runApp(const MyApp());
}

4. Handle the direct case

class _MyAppState extends State<MyApp> {
  StreamSubscription<LinkTrailLink>? _linkSub;

  @override  void initState() {
    super.initState();

    // Fires for a link tapped while the app is already installed —
    // whether it was running in the background or launched cold by the tap.
    _linkSub = LinkTrail.linkStream.listen((link) {
      _routeFromLink(link);
    });
  }

  @override  void dispose() {
    _linkSub?.cancel();
    super.dispose();
  }
}

5. Handle the deferred case

@overridevoid initState() {
  super.initState();

  _linkSub = LinkTrail.linkStream.listen(_routeFromLink);

  // Resolves once, only on the first launch after install.
  // Safe to always call — it completes with null on every later launch.
  LinkTrail.getFirstOpenLink().then((link) {
    if (link != null) _routeFromLink(link);
  });
}

linkStream is your ongoing listener for the app's lifetime; getFirstOpenLink is a one-shot future you check once at startup. Mixing them up — say, only checking getFirstOpenLink and never subscribing to the stream — means links stop working the moment a user has the app installed, which is a bug that's easy to miss in testing if you only ever test on a fresh install.

6. Route on the resolved link

void _routeFromLink(LinkTrailLink link) {
  switch (link.path) {
    case '/product':
      final id = link.params['id'];
      context.go('/product/$id');
      break;
    case '/invite':
      final ref = link.params['ref'];
      context.go('/onboarding?referrer=$ref');
      break;
    default:
      context.go('/home');
  }
}

(Swap context.go for your router of choice — Navigator, auto_route, whatever the rest of the app already uses. The resolution logic above doesn't care.)

7. Test both platforms, both cases

Deferred linking is resolved natively under the hood even in a Flutter app, so test per-platform, not just once:

Android direct: app installed, tap a link, confirm linkStream fires. Then background the app and tap again — confirm it still fires, not just on cold start.
Android deferred: uninstall completely, tap the link, install via Play Store, open. Confirm getFirstOpenLink resolves.
iOS direct: send yourself the link via Messages (not Safari's address bar — that doesn't trigger a Universal Link). Tap with the app installed.
iOS deferred: delete the app, tap the link, install via App Store, open cold.
Check native verification independently of Flutter — adb shell pm get-app-links your.package.name on Android, and a direct fetch of the AASA file on iOS. If either fails at the native layer, no amount of Dart-side debugging will fix it, because the link never reaches Flutter to begin with.

What's next

This gets link data flowing into your Flutter app in both states. Attribution — which campaign or creative actually drove the install — sits on top of this same resolution and is worth covering separately.

Deferred Deep Links in React Native: Complete Integration Guide

LinkTrail — Sat, 26 Sep 2026 19:02:11 +0000

If you've shipped a React Native app, you've probably wired up universal links / app links already. Existing users tap a link, the OS hands it to your app, Linking.addEventListener fires, you push the right screen. Done.

Then someone runs a paid campaign, or an email blast, or an influencer post — and every single new install lands on the plain home screen. No error. No crash. Just a slightly worse first run, and no idea what they originally tapped.

That's deferred deep linking: carrying link context across the install gap, when there's no app running yet to receive anything. This post is a complete, code-level walkthrough of wiring it up in React Native with LinkTrail, alongside the direct (already-installed) case so you have both working end to end.

The two cases, quickly

Direct deep link — app is already installed. The OS routes the tap straight to your app via a universal link (iOS) or app link (Android). Standard Linking API territory.
Deferred deep link — app is not installed yet. User taps, lands in the browser/store, installs, opens the app for the first time. There is no OS mechanism for this — something has to persist the link's intent server-side and hand it back on first open.

Both need to be handled for a link campaign to actually work end to end. Below is the full setup for both.

1. Install the SDK

npm install linktrail-react-native
# or
yarn add linktrail-react-native

cd ios && pod install

2. Native configuration

iOS — Associated Domains

In Xcode, enable the Associated Domains capability and add your link domain:

applinks:links.yourapp.com

Your server needs a valid apple-app-site-association file at https://links.yourapp.com/.well-known/apple-app-site-association, served with Content-Type: application/json, no redirects:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAMID.com.yourcompany.yourapp"],
        "components": [{ "/": "/*" }]
      }
    ]
  }
}

Android — App Links

In AndroidManifest.xml, add an intent filter to your launcher activity:

<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https" android:host="links.yourapp.com" />
</intent-filter>

And serve a matching assetlinks.json at https://links.yourapp.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourcompany.yourapp",
    "sha256_cert_fingerprints": ["YOUR:APP:SIGNING:CERT:FINGERPRINT"]
  }
}]

Both files are exactly what a link validator checks first — get these right before writing any app code, or nothing downstream will work no matter how correct your JS is.

3. Initialize the SDK

Do this once, as early as possible — before your navigation container mounts, so a deferred link isn't dropped by a race with the first render.

// App.tsx
import { useEffect, useState } from 'react';
import { LinkTrail } from 'linktrail-react-native';
import { NavigationContainer } from '@react-navigation/native';LinkTrail.configure({  apiKey: 'YOUR_LINKTRAIL_API_KEY',
});

export default function App() {
  const [initialRoute, setInitialRoute] = useState(null);

  useEffect(() => {
    // Direct link: app already installed, tapped while running or cold-started via the OS
    const subscription = LinkTrail.addLinkListener((link) => {
      routeFromLink(link);
    });

    // Deferred link: first open after install, resolved from the server-side match
    LinkTrail.getFirstOpenLink().then((link) => {
      if (link) routeFromLink(link);
    });

    return () => subscription.remove();
  }, []);

  function routeFromLink(link) {
    // link.path, link.params, link.campaign are all populated
    setInitialRoute({ path: link.path, params: link.params });
  }

  return <NavigationContainer>{/* ... */}</NavigationContainer>;
}

The split matters: addLinkListener only fires for a link tapped by a user who already has the app — it's the same event Linking.addEventListener('url', ...) gives you. getFirstOpenLink is the deferred case — it resolves once, on first launch after install, from a server-side match rather than anything the OS passed in, because on a cold install there's no OS event carrying that data at all.

4. Route on the resolved link

Whatever router you use, treat both cases the same way once you have a link object — the app shouldn't care whether it came from the OS or from the deferred resolver:

function routeFromLink(link) {
  switch (link.path) {
    case '/product':
      navigation.navigate('ProductDetail', { id: link.params.id });
      break;
    case '/invite':
      navigation.navigate('Onboarding', { referrer: link.params.ref });
      break;
    default:
      navigation.navigate('Home');
  }
}

5. Test both paths before you trust either

This is the step people skip, and it's the one that actually matters:

Direct case — install the app, background it, tap a link. Confirm addLinkListener fires with the right path.
Deferred case — uninstall completely, tap the same link, get sent to the store, install, open cold. Confirm getFirstOpenLink resolves with the same path — not just that the app opens.
Run your static files through a validator, not just a browser tab — you want to know if assetlinks.json is missing the right fingerprint or the AASA file is being blocked by bot protection, not just that a manual check looked fine once.

If step 2 doesn't resolve, check first whether the native config from step 2 above is actually correct on your domain — that's the failure mode that looks like an SDK bug but almost always isn't.

What's next

This covers getting context across the install gap. It doesn't cover attribution — which campaign, which creative, which referrer gets credit for the install — which is really a separate concern layered on top of the same link. That's worth its own post.

If you want to sanity-check your own assetlinks.json / apple-app-site-association setup before wiring any of this up, LinkTrail has a free validator that checks both files against the same criteria described above, rather than a plain pass/fail.

DEV Community: LinkTrail

Deferred Deep Links in Android: Complete Integration Guide

The two cases

1. Add the dependency

2. Configure App Links in the manifest

3. Initialize the SDK

4. Handle the direct case

5. Handle the deferred case

6. Route on the resolved link

7. Test it properly

What's next

Deferred Deep Links in iOS: Complete Integration Guide

The two cases

1. Add the SDK

2. Enable Associated Domains

3. Initialize the SDK

4. Handle the direct case

5. Handle the deferred case

6. Route on the resolved link

7. Test it for real

What's next

Deferred Deep Links in Flutter: Complete Integration Guide

The two cases

1. Add the package

2. Native configuration (still required)

Android — android/app/src/main/AndroidManifest.xml

iOS — Associated Domains

3. Initialize the SDK

4. Handle the direct case

5. Handle the deferred case

6. Route on the resolved link

7. Test both platforms, both cases

What's next

Deferred Deep Links in React Native: Complete Integration Guide

The two cases, quickly

1. Install the SDK

2. Native configuration

iOS — Associated Domains

Android — App Links

3. Initialize the SDK

4. Route on the resolved link

5. Test both paths before you trust either

What's next

Android — `android/app/src/main/AndroidManifest.xml`