website icon indicating copy to clipboard operation
website copied to clipboard

[docs] iOS deeplink `apple-app-site-association` file content is different from referenced Apple documentation and misleading

Open Daeon97 opened this issue 4 months ago • 0 comments

Looking at the docs in https://docs.flutter.dev/cookbook/navigation/set-up-universal-links#create-and-host-apple-app-site-association-json-file, we have this

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"
    ]
  }
}

But looking at the referenced Apple documentation at https://developer.apple.com/documentation/xcode/supporting-associated-domains I see this instead

The following JSON code represents the contents of a simple association file:

{
  "applinks": {
      "details": [
           {
             "appIDs": [ "ABCDE12345.com.example.app", "ABCDE12345.com.example.app2" ],
             "components": [
               {
                  "#": "no_universal_links",
                  "exclude": true,
                  "comment": "Matches any URL with a fragment that equals no_universal_links and instructs the system not to open it as a universal link."
               },
               {
                  "/": "/buy/*",
                  "comment": "Matches any URL with a path that starts with /buy/."
               },
               {
                  "/": "/help/website/*",
                  "exclude": true,
                  "comment": "Matches any URL with a path that starts with /help/website/ and instructs the system not to open it as a universal link."
               },
               {
                  "/": "/help/*",
                  "?": { "articleNumber": "????" },
                  "comment": "Matches any URL with a path that starts with /help/ and that has a query item with name 'articleNumber' and a value of exactly four characters."
               }
             ]
           }
       ]
   },
   "webcredentials": {
      "apps": [ "ABCDE12345.com.example.app" ]
   },


    "appclips": {
        "apps": ["ABCDE12345.com.example.MyApp.Clip"]
    }
}

My question now is

Image

Was this a typo or am I missing something because this seems to be misleading especially since the doc goes on to say

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.

But in the referenced Apple doc it seems this is actually done inside

"components": [...]

Which doc should I follow here the Flutter doc or the Apple doc or am I missing something

Daeon97 avatar Aug 19 '25 13:08 Daeon97