LinkHopp for Flutter
Deferred deep links for Flutter. Token-based, no device fingerprinting, flat price per app, contract with a German company.
- Live link: the installed app opens through an Android App Link or iOS Universal Link. The SDK resolves the short URL to the destination and metadata.
- Deferred deep link: the user taps a link, the app is not installed yet, they install it from the store, and on first launch the app learns which link it was.
Deferred checks report why they matched. The SDK sends a token for deferred matching and the original short URL for direct resolution. It sends no device signals.
LinkHopp is a service for business customers. Prices are on linkhopp.com/pricing. Documentation: linkhopp.com/docs/flutter.
Honest status
- On Android the SDK reads the Play Install Referrer. Tested once on 15 Nov 2026 with an install from the internal test track in a Play Store emulator (Android 15): the link arrived on first launch.
- On iOS the app takes the link from the clipboard after the user has tapped a button on the interstitial page. Tested once on an iPhone on 15 Nov 2026; one of two iPhone runs found no token, the cause is still open (details under "Known limits").
- Links open your app only after you have entered your app data and your
project address (
<subdomain>.linkhopp.com) in the dashboard under App verbinden (see section 3; the dashboard label is German).
Everything else is listed under "Known limits".
1. Install
These instructions describe version 1.1.0. Once that version is available on pub.dev, install it with:
dependencies:
linkhopp: ^1.1.0
For an unpublished release candidate, point your app to the supplied local SDK instead:
dependencies:
linkhopp:
path: /path/to/linkhopp-sdk
Use the project's app key from the dashboard. Keep the management key on your server.
import 'package:flutter/widgets.dart';
import 'package:linkhopp/linkhopp.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
// flutter run --dart-define=LINKHOPP_API_KEY=your_app_key
await LinkHopp.init(apiKey: const String.fromEnvironment('LINKHOPP_API_KEY'));
runApp(const MyApp());
}
2. Check for a deferred deep link
Call this once on first launch, for example in initState of your start
screen.
final result = await LinkHopp.checkDeferredLinkResult();
if (result.matched) {
final link = result.link!;
Navigator.pushNamed(context, link.path); // e.g. /product/123
// link.campaign, link.utmSource, link.metadata ...
} else {
debugPrint('No deferred link: ${result.status.name} - ${result.message}');
}
The check runs per installation only until it gets a final answer. Network,
server and Play errors are not final; the check is repeated on the next
launch. LinkHopp.checkDeferredLink() still exists; it returns only the link
or null and does not tell you why.
The message text is a short English explanation meant for logs. Base your
logic on status, not on the message text.
| Status | Meaning |
|---|---|
matched |
Match, result.link is set. |
noMatch |
The server answered but does not know the token (expired, already redeemed, other project). |
noToken |
Android: the install did not come through a LinkHopp link. iOS: clipboard not allowed or no token in it. |
alreadyChecked |
The check already completed on this device. |
referrerUnavailable |
Android: Play Install Referrer not readable (Play service, timeout, plugin not linked). Rebuild and retry on the next launch. |
unauthorized |
API key rejected (HTTP 401/403). |
rateLimited |
HTTP 429. |
serverError |
HTTP 5xx or unreadable response. |
networkError |
No connection or timeout. |
unsupportedPlatform |
Web/desktop. |
inProgress |
A check is already running. |
internalError |
Unexpected error inside the SDK. |
Android: what has to be true
- The link in the dashboard needs an Android URL pointing to the Play
Store (
https://play.google.com/store/apps/details?id=...). Only then does the server append the token to the Play URL. With any other Android URL there is no token and therefore no deferred link. - The user must install the app from Google Play. Sideloading, other stores and devices without Play Store give no referrer.
- The plugin is linked automatically at build time. After adding the package, do a full rebuild; hot reload is not enough.
iOS: clipboard only after a tap
On iOS the SDK reads the clipboard only if you pass allowClipboard: true.
Do this only after an explicit user action, for example a button such as
"Accept invitation":
FilledButton(
onPressed: () async {
final r = await LinkHopp.checkDeferredLinkResult(allowClipboard: true);
if (r.matched) { /* navigate */ }
},
child: const Text('Accept invitation'),
)
Depending on the iOS version, the system itself shows an "Allow Paste" prompt. Check with your data protection advisor whether you need consent for the access.
3. Live links: set up Universal Links and App Links
Every LinkHopp project has its own address
https://<subdomain>.linkhopp.com/<code>. Replace <subdomain> below with
your project's address.
Step 1: enter your app in the dashboard under "App verbinden"
- your project address (
<subdomain>) - iOS: Team ID and Bundle ID
- Android: package name and SHA-256 fingerprint of your signing certificate
Only then does your address serve the verification files without which the system will not open the link in your app. They contain only the app of this project:
- iOS:
https://<subdomain>.linkhopp.com/.well-known/apple-app-site-association - Android:
https://<subdomain>.linkhopp.com/.well-known/assetlinks.json
Without these entries, links open in the browser instead of the app. Deferred deep links on Android (section 2) do not depend on them.
Step 2: Android (App Links)
In android/app/src/main/AndroidManifest.xml, inside the <activity>:
<meta-data android:name="flutter_deeplinking_enabled" android:value="false"/>
<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="<subdomain>.linkhopp.com"/>
</intent-filter>
Step 3: iOS (Universal Links)
Xcode, target "Runner", Signing & Capabilities, "+ Capability", Associated
Domains, entry applinks:<subdomain>.linkhopp.com. Set
FlutterDeepLinkingEnabled to false in Info.plist so that the AppLinks
plugin handles the incoming link. See Flutter's guide for plugin-based deep
linking.
Then in the app:
void openLink(LinkHoppLink link) {
if (!context.mounted) return;
Navigator.pushNamed(context, link.path);
}
LinkHopp.handleLink(openLink);
final initial = await LinkHopp.getInitialLink();
if (initial != null) openLink(initial);
Both resolve the incoming HTTPS LinkHopp short URL and return the configured
destination URL, metadata, campaign and UTM fields with matchMethod: 'direct'.
The listener runs only on success. An unavailable or password-protected link or a
failed request returns null from the getter, with a diagnostic that omits the
URL, keys and server error body. To retry a known short URL or resolve it on
demand, call await LinkHopp.resolveLink(originalUrl). This returns to the
caller without invoking the listener.
API
| Method | Description |
|---|---|
LinkHopp.init(apiKey:, baseUrl:) |
Initialize the SDK |
LinkHopp.checkDeferredLinkResult({allowClipboard}) |
Check for a deferred link, with status and reason |
LinkHopp.checkDeferredLink({allowClipboard}) |
Same, returns only LinkHoppLink? |
LinkHopp.getInitialLink() |
Resolve the link that launched the app |
LinkHopp.handleLink(callback) |
Receive resolved links while the app is running |
LinkHopp.resolveLink(url) |
Resolve a short URL on demand |
LinkHopp.dispose() |
Remove listeners |
LinkHoppLink: destinationUrl, path, metadata, campaign, utmSource,
utmMedium, utmCampaign, matchMethod (referrer, clipboard,
direct).
What it does not do
- No device fingerprinting. Installs without a Play referrer (Android) or without an allowed clipboard (iOS) get no deferred link.
- No web or desktop support for the deferred check (it reports
unsupportedPlatform).
Known limits
- Scope of the device test (15 Nov 2026). One run each: Android in a Play Store emulator with an install from the internal test track, iOS on an iPhone with the app installed by cable (not from the App Store). Covered: deferred link and opening the installed app directly. SDK unit tests cover the new resolver with mocked channels and HTTP. Device verification for the new resolver and installation from the App Store are pending.
- iOS deferred depends on the clipboard. The token is only there if the user taps the button on the interstitial page. If they copy something else before the first app launch (including on a Mac with shared clipboard), the token is gone. In one of two runs the app found no token; the cause is still open. The message names the reason (empty, other text, paste not allowed).
- Start link exactly once. The getter and startup event share an in-flight lookup. The SDK delivers the start link once and suppresses repeat notifications for the same URL within two seconds of delivery. A later user tap on a warm app can deliver the same link again.
- Universal Links / App Links work only after the entry under
"App verbinden" in the dashboard (section 3) and only through your
project's
<subdomain>.linkhopp.comaddress. - Token lifetime: the server keeps it for 24 hours. Anyone who installs
the app later gets
noMatch.
Libraries
- linkhopp
- LinkHopp — Deep Linking SDK for Flutter