{"id":887,"date":"2026-04-23T13:00:00","date_gmt":"2026-04-23T18:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=887"},"modified":"2026-03-07T03:48:32","modified_gmt":"2026-03-07T08:48:32","slug":"flutter-deep-linking-setup","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/flutter-deep-linking-setup\/","title":{"rendered":"Flutter Deep Linking: Complete Setup Tutorial"},"content":{"rendered":"\n

Flutter handles deep linking through a combination of platform-specific configuration (iOS and Android) and Dart-level routing. This guide walks through the complete setup, from native configuration to handling URLs in your Flutter app.<\/p>\n\n\n\n

For go_router-specific patterns, see Flutter go_router Deep Links<\/a>. For a cross-platform overview, see Cross-Platform Deep Linking Guide<\/a>.<\/p>\n\n\n\n

How Flutter Deep Linking Works<\/h2>\n\n\n\n

Flutter's deep linking flow:<\/p>\n\n\n\n

    \n
  1. The OS receives a link tap and checks if an app is registered to handle it<\/li>\n
  2. If your app is registered, the OS launches it (or brings it to the foreground)<\/li>\n
  3. Flutter's engine receives the URL from the platform channel<\/li>\n
  4. Your router (go_router, auto_route, or the built-in Router<\/code>) matches the URL to a route<\/li>\n
  5. The matched screen is displayed<\/li>\n<\/ol>\n\n\n\n

    Flutter 3.x+ has built-in deep linking support through the Router<\/code> widget and RouteInformationParser<\/code>. The most popular routing package for deep linking is go_router<\/a>.<\/p>\n\n\n\n

    Step 1: iOS Configuration<\/h2>\n\n\n\n

    Associated Domains<\/h3>\n\n\n\n

    Open ios\/Runner.xcworkspace<\/code> in Xcode.<\/p>\n\n\n\n

      \n
    1. Select the Runner target<\/li>\n
    2. Go to Signing & Capabilities<\/li>\n
    3. Add the "Associated Domains" capability<\/li>\n
    4. Add applinks:go.yourapp.com<\/code><\/li>\n<\/ol>\n\n\n\n

      Info.plist (Custom URL Scheme, Optional)<\/h3>\n\n\n\n

      If you also want to support custom URL schemes, add to ios\/Runner\/Info.plist<\/code>:<\/p>\n\n\n\n

      <key>CFBundleURLTypes<\/key>\n<array>\n  <dict>\n    <key>CFBundleURLSchemes<\/key>\n    <array>\n      <string>yourapp<\/string>\n    <\/array>\n    <key>CFBundleURLName<\/key>\n    <string>com.yourapp<\/string>\n  <\/dict>\n<\/array>\n<\/code><\/pre>\n\n\n\n
      FlutterDeepLinkingEnabled<\/h3>\n\n\n\n
      Add this to your Info.plist<\/code> to enable Flutter's built-in deep link handling:<\/p>\n\n\n\n
      <key>FlutterDeepLinkingEnabled<\/key>\n<true\/>\n<\/code><\/pre>\n\n\n\n
      This tells the Flutter engine to automatically forward incoming URLs to your Dart router. Without this, you'd need to write platform channel code to pass URLs from the native side to Dart.<\/p>\n\n\n\n
      Step 2: Android Configuration<\/h2>\n\n\n\n
      AndroidManifest.xml<\/h3>\n\n\n\n
      Add intent filters to your main activity in android\/app\/src\/main\/AndroidManifest.xml<\/code>:<\/p>\n\n\n\n
      <activity\n  android:name=".MainActivity"\n  android:launchMode="singleTop">\n\n  <!-- Deep Links (App Links) -->\n  <intent-filter android:autoVerify="true">\n    <action android:name="android.intent.action.VIEW" \/>\n    <category android:name="android.intent.category.DEFAULT" \/>\n    <category android:name="android.intent.category.BROWSABLE" \/>\n    <data android:scheme="https" android:host="go.yourapp.com" \/>\n  <\/intent-filter>\n\n  <!-- Existing metadata... -->\n  <meta-data\n    android:name="flutter_deeplinking_enabled"\n    android:value="true" \/>\n<\/activity>\n<\/code><\/pre>\n\n\n\n
      The flutter_deeplinking_enabled<\/code> metadata is the Android equivalent of the iOS FlutterDeepLinkingEnabled<\/code> plist entry.<\/p>\n\n\n\n
      Digital Asset Links<\/h3>\n\n\n\n
      Ensure your domain serves a valid assetlinks.json<\/code> at https:\/\/go.yourapp.com\/.well-known\/assetlinks.json<\/code>. If using Tolinku, this is configured automatically in your Appspace settings.<\/p>\n\n\n\n
      Get your SHA-256 fingerprint:<\/p>\n\n\n\n
      keytool -list -v -keystore ~\/.android\/debug.keystore -alias androiddebugkey\n<\/code><\/pre>\n\n\n\n
      For release builds with Google Play App Signing, get the fingerprint from Play Console (Setup > App signing).<\/p>\n\n\n\n
      Step 3: Flutter Routing with go_router<\/h2>\n\n\n\n
      Install go_router<\/h3>\n\n\n\n
      # pubspec.yaml\ndependencies:\n  go_router: ^14.0.0\n<\/code><\/pre>\n\n\n\n
      Define Routes<\/h3>\n\n\n\n
      import 'package:go_router\/go_router.dart';\n\nfinal router = GoRouter(\n  routes: [\n    GoRoute(\n      path: '\/',\n      builder: (context, state) => const HomeScreen(),\n    ),\n    GoRoute(\n      path: '\/product\/:id',\n      builder: (context, state) {\n        final productId = state.pathParameters['id']!;\n        return ProductScreen(id: productId);\n      },\n    ),\n    GoRoute(\n      path: '\/invite\/:code',\n      builder: (context, state) {\n        final code = state.pathParameters['code']!;\n        return InviteScreen(code: code);\n      },\n    ),\n    GoRoute(\n      path: '\/promo\/:slug',\n      builder: (context, state) {\n        final slug = state.pathParameters['slug']!;\n        return PromoScreen(slug: slug);\n      },\n    ),\n  ],\n  errorBuilder: (context, state) => const NotFoundScreen(),\n);\n<\/code><\/pre>\n\n\n\n
      Use the Router<\/h3>\n\n\n\n
      class MyApp extends StatelessWidget {\n  @override\n  Widget build(BuildContext context) {\n    return MaterialApp.router(\n      routerConfig: router,\n    );\n  }\n}\n<\/code><\/pre>\n\n\n\n
      When a deep link arrives (e.g., https:\/\/go.yourapp.com\/product\/456<\/code>), go_router automatically matches the path \/product\/456<\/code> to the ProductScreen<\/code> route and extracts 456<\/code> as the id<\/code> parameter.<\/p>\n\n\n\n
      Handling Query Parameters<\/h3>\n\n\n\n
      For links with query parameters like https:\/\/go.yourapp.com\/search?q=shoes&sort=price<\/code>:<\/p>\n\n\n\n
      GoRoute(\n  path: '\/search',\n  builder: (context, state) {\n    final query = state.uri.queryParameters['q'] ?? '';\n    final sort = state.uri.queryParameters['sort'] ?? 'relevance';\n    return SearchScreen(query: query, sort: sort);\n  },\n),\n<\/code><\/pre>\n\n\n\n
      Step 4: Handling the Full URL<\/h2>\n\n\n\n
      By default, Flutter's deep link integration strips the scheme and host from the URL, passing only the path to your router. So https:\/\/go.yourapp.com\/product\/123<\/code> becomes \/product\/123<\/code>.<\/p>\n\n\n\n
      If you need the full URL (for example, to distinguish between different domains), you can use the app_links<\/code> package:<\/p>\n\n\n\n
      dependencies:\n  app_links: ^6.0.0\n<\/code><\/pre>\n\n\n\n
      import 'package:app_links\/app_links.dart';\n\nclass DeepLinkHandler {\n  final AppLinks _appLinks = AppLinks();\n\n  void init() {\n    \/\/ Listen for links while app is running\n    _appLinks.uriLinkStream.listen((Uri uri) {\n      handleLink(uri);\n    });\n\n    \/\/ Check for link that launched the app\n    _appLinks.getInitialLink().then((Uri? uri) {\n      if (uri != null) {\n        handleLink(uri);\n      }\n    });\n  }\n\n  void handleLink(Uri uri) {\n    \/\/ Full URL access: uri.host, uri.path, uri.queryParameters\n    if (uri.host == 'go.yourapp.com') {\n      router.go(uri.path);\n    }\n  }\n}\n<\/code><\/pre>\n\n\n\n
      Step 5: Testing<\/h2>\n\n\n\n
      iOS Testing<\/h3>\n\n\n\n
      On a physical device:<\/p>\n\n\n\n
        \n
      1. Paste https:\/\/go.yourapp.com\/product\/123<\/code> in Notes and tap it<\/li>\n
      2. Send the link via iMessage and tap it<\/li>\n
      3. Verify the app opens and displays the product screen<\/li>\n<\/ol>\n\n\n\n
        To test during development without a configured domain, use the custom URL scheme:<\/p>\n\n\n\n
        yourapp:\/\/product\/123\n<\/code><\/pre>\n\n\n\n
        Android Testing<\/h3>\n\n\n\n
        Use ADB:<\/p>\n\n\n\n
        adb shell am start -a android.intent.action.VIEW \\\n  -d "https:\/\/go.yourapp.com\/product\/123" \\\n  com.yourapp\n<\/code><\/pre>\n\n\n\n
        Flutter DevTools<\/h3>\n\n\n\n
        Flutter DevTools shows the current route state. Open DevTools, navigate to the "Router" tab, and trigger a deep link. You'll see the URL being parsed and the matched route.<\/p>\n\n\n\n
        Debug Logging<\/h3>\n\n\n\n
        Add logging to your router to trace deep link handling:<\/p>\n\n\n\n
        final router = GoRouter(\n  debugLogDiagnostics: true, \/\/ Logs route matching\n  routes: [\n    \/\/ ...\n  ],\n);\n<\/code><\/pre>\n\n\n\n
        This prints route matching information to the console, which is useful for debugging why a link isn't matching the expected route.<\/p>\n\n\n\n
        Common Issues<\/h2>\n\n\n\n
        Links Open in Browser Instead of App<\/h3>\n\n\n\n
        iOS<\/strong>: Verify that:<\/p>\n\n\n\n