Flutter SDK

Source: github.com/WarpLinkApp/warplink-flutter-sdk

Installation

flutter pub add warplink_flutter

This adds the package to your pubspec.yaml:

dependencies:
  warplink_flutter: ^1.1.0

The plugin wraps the native WarpLink iOS and Android SDKs, so link handling, deduplication, and attribution behave exactly as they do in a native app. The iOS SDK is distributed through Swift Package Manager. If your Flutter version does not use Swift Package Manager by default, turn it on once:

flutter config --enable-swift-package-manager

There is no Podfile change and no pod to install.

Platform Setup

A Flutter app is one WarpLink app that covers both platforms. Register it once in the dashboard with iOS and Android selected, and do not create a second app for the other platform. Both platforms need the link domain configured. The plugin registers itself with Flutter's iOS and Android lifecycles, so you edit no AppDelegate, SceneDelegate, or MainActivity.

iOS

1. Open ios/Runner.xcworkspace in Xcode, select the Runner target > Signing & Capabilities
2. Add Associated Domains > applinks:yourapp.aplnk.to
3. Enable Associated Domains in your App ID at developer.apple.com

Find your app's subdomain in the dashboard: open the app, then Settings. Or see Your app's own link address.

That is the whole iOS setup. The capability can also live in ios/Runner/Runner.entitlements.

Android

Add the intent filter to your main Activity in android/app/src/main/AndroidManifest.xml:

<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="yourapp.aplnk.to" />
</intent-filter>

Then set the minimum SDK to 26 in android/app/build.gradle.kts. The Flutter default can be lower, and the manifest merge then fails because the native WarpLink SDK needs API 26:

android {
    defaultConfig {
        minSdk = 26
    }
}

Keep the android:launchMode your Flutter project already has. The default Flutter template uses singleTop, which routes a link tapped on a running app to the existing Activity. standard and singleInstance are not supported.

Serving links from a custom domain? Add it to the associated domains and the intent filter alongside yourapp.aplnk.to, then declare it in configure().

Every app has its own subdomain, yourapp.aplnk.to. Add that exact host, never a wildcard such as applinks:*.aplnk.to on iOS. If your app existed before subdomains, keep aplnk.to listed next to the new address: links you already have stay on aplnk.to and keep opening your app. See Your app's own link address.

Flutter's Built-In Link Handling

Flutter has its own deep link handler, on by default. It forwards every incoming link to your router as a route, so https://yourapp.aplnk.to/abc123 becomes a lookup for /abc123 and can land on an unknown-route page. Switch it off and let onLink drive navigation.

In ios/Runner/Info.plist:

<key>FlutterDeepLinkingEnabled</key>
<false/>

In android/app/src/main/AndroidManifest.xml, inside your main <activity>:

<meta-data android:name="flutter_deeplinking_enabled" android:value="false" />

If your app must keep Flutter's own deep linking for other, non-WarpLink domains, WarpLink cannot share the same links safely. Keep the WarpLink domains out of Flutter's route table. See Routing with go_router.

Configure the SDK

Call WarpLink.configure() once from your root widget's initState. Pass an onLink callback and the SDK wires cold start, warm start, and the deferred deep link check into that single sink.

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

void main() => runApp(const App());

class App extends StatefulWidget {
  const App({super.key});

  @override
  State<App> createState() => _AppState();
}

class _AppState extends State<App> {
  @override
  void initState() {
    super.initState();
    WarpLink.configure(
      apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
      debugLogging: true, // Enable native console logging
      onLink: (event) {
        switch (event) {
          case LinkEvent(:final deepLink):
            // Fired for taps AND deferred installs. Check deepLink.isDeferred.
            navigateTo(deepLink.deepLinkUrl ?? deepLink.destination);
          case ErrorEvent(:final error):
            debugPrint('WarpLink ${error.wireCode}: ${error.message}');
        }
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(navigatorKey: navigatorKey, onGenerateRoute: buildRoutes);
  }
}

navigateTo waits for the navigator before it pushes a route, so a link that launches the app is never dropped. See Deep Links for navigatorKey and navigateTo.

onLink receives a WarpLinkEvent, which is either a LinkEvent or an ErrorEvent. A switch over the two is exhaustive.

configure() returns a Future<void> that completes when native configuration completes. A configuration failure is delivered to onLink as an ErrorEvent when you pass onLink, as in the example above. Only when you omit onLink does the returned future complete with a WarpLinkException, so await it in that case:

try {
  await WarpLink.configure(apiKey: 'wl_live_yoursdkkeyhere000000000000000000');
} on WarpLinkException catch (error) {
  // No onLink was passed, so a configuration failure surfaces here instead.
}

Declare Your Link Domains

The SDK always recognizes aplnk.to. List your app's subdomain, yourapp.aplnk.to, and any custom domain you serve links from in linkDomains. configure() passes the list straight to the native iOS and Android SDKs, so a link on those hosts resolves on the very first launch, with no network round trip.

// Call from your root widget's initState
WarpLink.configure(
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  linkDomains: ['yourapp.aplnk.to', 'links.yourapp.com', 'go.yourapp.com'],
  onLink: (event) {
    if (event is LinkEvent) {
      navigateTo(event.deepLink.deepLinkUrl ?? event.deepLink.destination);
    }
  },
);

Without it, the native side only learns your domain after it has reached the server, and the decision to claim a URL is made synchronously before that answer arrives. That is why a fresh install can hand your own link back to your router.

The native declaration works too, and is read before any Dart runs: a WarpLinkDomains array in ios/Runner/Info.plist on iOS, an app.warplink.DOMAINS meta-data entry in AndroidManifest.xml on Android. See the iOS and Android guides.

Every form is optional and additive. Domains are normalized natively (trimmed, lowercased, a full URL reduced to its host), so paste whichever form you have.

Opt Out of Automatic Handling

Both pieces are on by default. Disable either to drive it yourself with the manual methods:

WarpLink.configure(
  apiKey: 'wl_live_yoursdkkeyhere000000000000000000',
  automaticDeepLinks: false,          // use onDeepLink / getInitialDeepLink yourself
  automaticDeferredDeepLinks: false,  // use checkDeferredDeepLink yourself
);

automaticDeepLinks only takes effect when you pass onLink.

Testing

iOS: Physical Device Required

1. Build and run on a physical device with flutter run -d <device-id>
2. Open your test link in Safari (e.g., https://yourapp.aplnk.to/abc123)
3. The app should open and trigger the deep link callback
4. Check the Xcode console for [WarpLink] log messages

Android: Physical Device or Emulator

# Verify App Links status
adb shell pm get-app-links com.yourcompany.yourapp

# Open a test link
adb shell am start -a android.intent.action.VIEW \
    -d "https://yourapp.aplnk.to/abc123" com.yourcompany.yourapp

# Filter Logcat for WarpLink messages
adb logcat -s WarpLink

Android App Links work on both a physical device and the emulator, unlike iOS Universal Links.

Deferred Deep Links

Testing a deferred deep link, meaning a click that happens before the app is installed, needs a delete/uninstall-then-reinstall cycle so the SDK treats it as a fresh install. See Testing in the Deferred Deep Links guide.

Next Steps

• Deep Links: Cold start, warm start, routing, and delivery limits
• Deferred Deep Links: Preserve context through installs
• Attribution: Platform-specific matching and privacy
• API Reference: Full Dart API documentation