Set up universal links for iOS

Deep linking allows an app user to launch an app with a URI. This URI contains scheme, host, and path, and opens the app to a specific screen.

A universal link, a type of deep link exclusive to iOS devices, uses only the http or https protocols.

To set up universal links, you need to own a web domain. As a temporary solution, consider using Firebase Hosting or GitHub Pages.

Write a Flutter app that can handle an incoming URL.

This example uses the go_router package to handle the routing. The Flutter team maintains the go_router package. It provides a simple API to handle complex routing scenarios.

1. To create a new application, type flutter create <app-name>.

   flutter create deeplink_cookbook

2. To include the go_router package as a dependency, run flutter pub add:

   flutter pub add go_router

3. To handle the routing, create a GoRouter object in the main.dart file:

   main.dart

   dart

   import 'package:flutter/material.dart';
   import 'package:go_router/go_router.dart';
   
   void main() => runApp(MaterialApp.router(routerConfig: router));
   
   /// This handles '/' and '/details'.
   final router = GoRouter(
     routes: [
       GoRoute(
         path: '/',
         builder: (_, __) => Scaffold(
           appBar: AppBar(title: const Text('Home Screen')),
         ),
         routes: [
           GoRoute(
             path: 'details',
             builder: (_, __) => Scaffold(
               appBar: AppBar(title: const Text('Details Screen')),
             ),
           ),
         ],
       ),
     ],
   );

1. Launch Xcode.

2. Open the ios/Runner.xcworkspace file inside the Flutter project's ios folder.

You have finished configuring the application for deep linking.

You need to host an apple-app-site-association file in the web domain. This file tells the mobile browser which iOS application to open instead of the browser. To create the file, find the appID of the Flutter app you created in the previous section.

Apple formats the appID as <team id>.<bundle id>.

• Locate the bundle ID in the Xcode project.
• Locate the team ID in the developer account.

For example: Given a team ID of S8QB4VV633 and a bundle ID of com.example.deeplinkCookbook, you would enter an appID entry of S8QB4VV633.com.example.deeplinkCookbook.

This file uses the JSON format. Don't include the .json file extension when you save this file. Per Apple's documentation, this file should resemble the following content:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appIDs": [
          "S8QB4VV633.com.example.deeplinkCookbook"
        ],
        "paths": [
          "*"
        ],
        "components": [
          {
            "/": "/*"
          }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": [
      "S8QB4VV633.com.example.deeplinkCookbook"
    ]
  }
}

1. Set one value in the appIDs array to <team id>.<bundle id>.

2. Set the paths array to ["*"]. The paths array specifies the allowed universal links. Using the asterisk, * redirects every path to the Flutter app. If needed, change the paths array value to a setting more appropriate to your app.

3. Host the file at a URL that resembles the following structure.

   <webdomain>/.well-known/apple-app-site-association

4. Verify that your browser can access this file.

Test a universal link using a physical iOS device or the Simulator.

1. Before testing, install the Flutter app on the iOS device or Simulator, Use flutter run on the desired device.

   

   When complete, the Flutter app displays on the home screen of the iOS device or Simulator.

2. If you test using the Simulator, use the Xcode CLI:

   xcrun simctl openurl booted https://<web domain>/details

3. If you test with a physical iOS device:

   1. Launch the Note app.
   2. Type the URL in the Note app.
   3. Click the resulting link.

   If successful, the Flutter app launches and displays its details screen.

   

You can find the source code for the deeplink_cookbook recipe in the GitHub repo.

Unless stated otherwise, the documentation on this site reflects the latest stable version of Flutter. Page last updated on 2024-12-13. View source or report an issue.