{"abstract":[{"text":"Connect your app and a website to provide both a native app and a browser experience.","type":"text"}],"hierarchy":{"paths":[["doc:\/\/com.apple.documentation\/documentation\/technologies","doc:\/\/com.apple.Xcode\/documentation\/Xcode","doc:\/\/com.apple.Xcode\/documentation\/Xcode\/projects-and-workspaces","doc:\/\/com.apple.Xcode\/documentation\/Xcode\/allowing-apps-and-websites-to-link-to-your-content"]]},"identifier":{"interfaceLanguage":"swift","url":"doc:\/\/com.apple.Xcode\/documentation\/Xcode\/supporting-associated-domains"},"kind":"article","legalNotices":{"copyright":"Copyright &copy; 2026 Apple Inc. All rights reserved.","privacyPolicy":"https:\/\/www.apple.com\/privacy\/privacy-policy","termsOfUse":"https:\/\/www.apple.com\/legal\/internet-services\/terms\/site.html"},"metadata":{"availableLanguages":["de-DE","en-US","es-419","fr-FR","it-IT","ja-JP","ko-KR","pt-BR","zh-CN"],"role":"collectionGroup","title":"Supporting associated domains"},"primaryContentSections":[{"content":[{"anchor":"Overview","level":2,"text":"Overview","type":"heading"},{"inlineContent":[{"text":"Associated domains establish a secure association between domains and your app so","type":"text"},{"text":" ","type":"text"},{"text":"you can share credentials or provide features in your app from your website. For","type":"text"},{"text":" ","type":"text"},{"text":"example, an online retailer may offer an app to accompany their website and enhance","type":"text"},{"text":" ","type":"text"},{"text":"the user experience.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"text":"Shared web credentials, universal links, Handoff, and App Clips all use associated","type":"text"},{"text":" ","type":"text"},{"text":"domains. Associated domains provide the underpinning to universal links, a feature","type":"text"},{"text":" ","type":"text"},{"text":"that allows an app to present content in place of all or part of its website. Users","type":"text"},{"text":" ","type":"text"},{"text":"who don’t download the app get the same information in a web browser instead of the","type":"text"},{"text":" ","type":"text"},{"text":"native app.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"text":"To associate a website with your app, you need to have the associated domain file","type":"text"},{"text":" ","type":"text"},{"text":"on your website and the appropriate entitlement in your app. The apps in the ","type":"text"},{"code":"apple-app-site-association","type":"codeVoice"},{"text":" ","type":"text"},{"text":"file on your website must have a matching ","type":"text"},{"identifier":"doc:\/\/com.apple.documentation\/documentation\/BundleResources\/Entitlements\/com.apple.developer.associated-domains","isActive":true,"type":"reference"},{"text":".","type":"text"}],"type":"paragraph"},{"anchor":"Add-the-associated-domain-file-to-your-website","level":3,"text":"Add the associated domain file to your website","type":"heading"},{"inlineContent":[{"text":"When a user installs your app, the system attempts to download the associated domain","type":"text"},{"text":" ","type":"text"},{"text":"file and verify the domains in your entitlement.","type":"text"}],"type":"paragraph"},{"content":[{"inlineContent":[{"text":"If your site uses multiple subdomains (such as ","type":"text"},{"code":"example.com","type":"codeVoice"},{"text":", ","type":"text"},{"code":"www.example.com","type":"codeVoice"},{"text":",","type":"text"},{"text":" ","type":"text"},{"text":"and ","type":"text"},{"code":"support.example.com","type":"codeVoice"},{"text":"), each requires its own entry in the ","type":"text"},{"identifier":"doc:\/\/com.apple.documentation\/documentation\/BundleResources\/Entitlements\/com.apple.developer.associated-domains","isActive":true,"type":"reference"},{"text":",","type":"text"},{"text":" ","type":"text"},{"text":"and each must serve its own ","type":"text"},{"code":"apple-app-site-association","type":"codeVoice"},{"text":" file.","type":"text"}],"type":"paragraph"}],"name":"Note","style":"note","type":"aside"},{"inlineContent":[{"text":"To add the associated domain file to your website, create a file named ","type":"text"},{"code":"apple-app-site-association","type":"codeVoice"},{"text":" ","type":"text"},{"text":"(without an extension). Update the JSON code in the file for the services you","type":"text"},{"text":" ","type":"text"},{"text":"support on the domain. For universal links, be sure to list the app identifiers for","type":"text"},{"text":" ","type":"text"},{"text":"your domain in the ","type":"text"},{"code":"applinks","type":"codeVoice"},{"text":" service. Similarly, if you create an App Clip, be sure","type":"text"},{"text":" ","type":"text"},{"text":"to list your App Clip’s app identifier using the ","type":"text"},{"code":"appclips","type":"codeVoice"},{"text":" service.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"text":"The following JSON code represents the contents of a simple association file:","type":"text"}],"type":"paragraph"},{"code":["{","  \"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\"]","    }","}"],"syntax":"other","type":"codeListing"},{"inlineContent":[{"text":"The ","type":"text"},{"code":"appIDs","type":"codeVoice"},{"text":" and ","type":"text"},{"code":"apps","type":"codeVoice"},{"text":" keys specify the application identifiers for the apps that","type":"text"},{"text":" ","type":"text"},{"text":"are available for use on this website along with their service types. Use the following","type":"text"},{"text":" ","type":"text"},{"text":"format for the values in these keys:","type":"text"}],"type":"paragraph"},{"code":["<Application Identifier Prefix>.<Bundle Identifier>"],"syntax":"javascript","type":"codeListing"},{"inlineContent":[{"text":"The ","type":"text"},{"code":"details","type":"codeVoice"},{"text":" dictionary only applies to the ","type":"text"},{"identifier":"doc:\/\/com.apple.documentation\/documentation\/BundleResources\/applinks","isActive":true,"type":"reference"},{"text":" ","type":"text"},{"text":"service type; other service types don’t use it. The ","type":"text"},{"code":"components","type":"codeVoice"},{"text":" key is an array","type":"text"},{"text":" ","type":"text"},{"text":"of dictionaries that provides pattern matching for components of the URL.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"text":"After you construct the association file, place it in your site’s .","type":"text"},{"code":"well-known","type":"codeVoice"},{"text":" directory.","type":"text"},{"text":" ","type":"text"},{"text":"The file’s URL should match the following format:","type":"text"}],"type":"paragraph"},{"code":["https:\/\/<fully qualified domain>\/.well-known\/apple-app-site-association"],"syntax":"other","type":"codeListing"},{"inlineContent":[{"text":"You must host the file using ","type":"text"},{"code":"https:\/\/","type":"codeVoice"},{"text":" with a valid certificate and with no redirects.","type":"text"}],"type":"paragraph"},{"anchor":"Add-the-associated-domains-entitlement-to-your-app","level":3,"text":"Add the associated domains entitlement to your app","type":"heading"},{"inlineContent":[{"text":"To set up the entitlement in your app, open the target’s Signing & Capabilities","type":"text"},{"text":" ","type":"text"},{"text":"tab in Xcode and add the Associated Domains capability. If they’re not already present,","type":"text"},{"text":" ","type":"text"},{"text":"this step adds the ","type":"text"},{"identifier":"doc:\/\/com.apple.documentation\/documentation\/BundleResources\/Entitlements\/com.apple.developer.associated-domains","isActive":true,"type":"reference"},{"text":" ","type":"text"},{"text":"to your app and the associated domains feature to your app ID.","type":"text"}],"type":"paragraph"},{"content":[{"inlineContent":[{"text":"For a single-target watchOS apps, add the Associated Domains capability","type":"text"},{"text":" ","type":"text"},{"text":"to the watchOS app target. For watchOS apps with separate WatchKit extensions, you","type":"text"},{"text":" ","type":"text"},{"text":"must add the Associated Domains capability to the WatchKit Extension target.","type":"text"}],"type":"paragraph"}],"name":"Important","style":"important","type":"aside"},{"inlineContent":[{"text":"To add your domain to the entitlement, click the Add button (+) at the bottom of the Domains","type":"text"},{"text":" ","type":"text"},{"text":"table to add a placeholder domain. Replace the placeholder with the appropriate prefix","type":"text"},{"text":" ","type":"text"},{"text":"for the service your app supports and your site’s domain. Make sure to only include","type":"text"},{"text":" ","type":"text"},{"text":"the desired subdomain and the top-level domain. Don’t include path and query components","type":"text"},{"text":" ","type":"text"},{"text":"or a trailing slash (","type":"text"},{"code":"\/)","type":"codeVoice"},{"text":".","type":"text"}],"type":"paragraph"},{"inlineContent":[{"identifier":"supporting-associated-domains-1.png","type":"image"}],"type":"paragraph"},{"inlineContent":[{"text":"Add the domains that share credentials with your app. For services other than","type":"text"},{"text":" ","type":"text"},{"code":"appclips","type":"codeVoice"},{"text":", you can prefix a domain with ","type":"text"},{"code":"*.","type":"codeVoice"},{"text":" to match all of its subdomains.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"text":"Each domain you specify uses the following format:","type":"text"}],"type":"paragraph"},{"code":["<service>:<fully qualified domain>"],"syntax":"other","type":"codeListing"},{"inlineContent":[{"text":"Starting with macOS 11 and iOS 14, apps no longer send requests for ","type":"text"},{"code":"apple-app-site-association","type":"codeVoice"},{"text":" ","type":"text"},{"text":"files directly to your web server. Instead, they send these requests to an Apple-managed","type":"text"},{"text":" ","type":"text"},{"text":"content delivery network (CDN) dedicated to associated domains.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"text":"While you’re developing your app, if your web server is unreachable from the public","type":"text"},{"text":" ","type":"text"},{"text":"internet, you can use the alternate mode feature to bypass the CDN and connect directly","type":"text"},{"text":" ","type":"text"},{"text":"to your private domain.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"text":"You enable an alternate mode by adding a query string to your associated domain’s","type":"text"},{"text":" ","type":"text"},{"text":"entitlement as follows:","type":"text"}],"type":"paragraph"},{"code":["<service>:<fully qualified domain>?mode=<alternate mode>"],"syntax":"other","type":"codeListing"},{"inlineContent":[{"text":"For more information about alternate modes, see ","type":"text"},{"identifier":"doc:\/\/com.apple.documentation\/documentation\/BundleResources\/Entitlements\/com.apple.developer.associated-domains","isActive":true,"type":"reference"},{"text":".","type":"text"},{"text":" ","type":"text"},{"text":"For information about universal links, see ","type":"text"},{"identifier":"doc:\/\/com.apple.Xcode\/documentation\/Xcode\/allowing-apps-and-websites-to-link-to-your-content","isActive":true,"type":"reference"},{"text":".","type":"text"},{"text":" ","type":"text"},{"text":"For information about Handoff, see ","type":"text"},{"identifier":"doc:\/\/com.apple.documentation\/documentation\/Foundation\/implementing-handoff-in-your-app","isActive":true,"type":"reference"},{"text":".","type":"text"},{"text":" ","type":"text"},{"text":"For information about App Clips, see ","type":"text"},{"identifier":"doc:\/\/com.apple.documentation\/documentation\/AppClip\/configuring-the-launch-experience-of-your-app-clip","isActive":true,"type":"reference"},{"text":".","type":"text"}],"type":"paragraph"},{"content":[{"inlineContent":[{"text":"Apple’s content delivery network requests the ","type":"text"},{"code":"apple-app-site-association","type":"codeVoice"},{"text":" file for your domain within 24 hours. Devices check for updates approximately once per week after app installation.","type":"text"}],"type":"paragraph"}],"name":"Important","style":"important","type":"aside"}],"kind":"content"}],"schemaVersion":{"major":0,"minor":3,"patch":0},"sections":[],"topicSections":[{"anchor":"Entitlements","identifiers":["doc:\/\/com.apple.documentation\/documentation\/BundleResources\/Entitlements\/com.apple.developer.associated-domains"],"title":"Entitlements"},{"anchor":"Services","identifiers":["doc:\/\/com.apple.documentation\/documentation\/BundleResources\/applinks"],"title":"Services"}],"references":{"Xcode-PageImage-card.png":{"alt":"The Xcode logo on a blue gradient background.","identifier":"Xcode-PageImage-card.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.Xcode\/Xcode-PageImage-card@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.Xcode\/Xcode-PageImage-card~dark@2x.png"}]},"doc://com.apple.Xcode/documentation/Xcode":{"abstract":[{"text":"Build, test, and submit your app with Apple’s integrated development environment.","type":"text"}],"identifier":"doc:\/\/com.apple.Xcode\/documentation\/Xcode","images":[{"identifier":"Xcode-PageImage-card.png","type":"card"}],"kind":"article","role":"collection","title":"Xcode","type":"topic","url":"\/documentation\/xcode"},"doc://com.apple.Xcode/documentation/Xcode/allowing-apps-and-websites-to-link-to-your-content":{"abstract":[{"text":"Use universal links to link directly to content within your app and share data securely.","type":"text"}],"identifier":"doc:\/\/com.apple.Xcode\/documentation\/Xcode\/allowing-apps-and-websites-to-link-to-your-content","kind":"article","role":"collectionGroup","title":"Allowing apps and websites to link to your content","type":"topic","url":"\/documentation\/xcode\/allowing-apps-and-websites-to-link-to-your-content"},"doc://com.apple.Xcode/documentation/Xcode/projects-and-workspaces":{"abstract":[{"text":"Manage the code and resources you use to build apps, libraries, and other","type":"text"},{"text":" ","type":"text"},{"text":"software for Apple platforms.","type":"text"}],"identifier":"doc:\/\/com.apple.Xcode\/documentation\/Xcode\/projects-and-workspaces","kind":"article","role":"collectionGroup","title":"Projects and workspaces","type":"topic","url":"\/documentation\/xcode\/projects-and-workspaces"},"doc://com.apple.documentation/documentation/AppClip/configuring-the-launch-experience-of-your-app-clip":{"abstract":[{"text":"Review how people launch your App Clip with invocation URLs, default and demo links, and advanced App Clip experiences.","type":"text"}],"identifier":"doc:\/\/com.apple.documentation\/documentation\/AppClip\/configuring-the-launch-experience-of-your-app-clip","kind":"article","role":"article","title":"Configuring App Clip experiences","type":"topic","url":"\/documentation\/appclip\/configuring-the-launch-experience-of-your-app-clip"},"doc://com.apple.documentation/documentation/BundleResources/Entitlements/com.apple.developer.associated-domains":{"abstract":[{"text":"The associated domains for specific services, such as shared web credentials, universal links, and App Clips.","type":"text"}],"identifier":"doc:\/\/com.apple.documentation\/documentation\/BundleResources\/Entitlements\/com.apple.developer.associated-domains","kind":"symbol","navigatorTitle":[{"kind":"identifier","text":"com.apple.developer.associated-domains"}],"role":"symbol","title":"Associated Domains Entitlement","type":"topic","url":"\/documentation\/bundleresources\/entitlements\/com.apple.developer.associated-domains"},"doc://com.apple.documentation/documentation/BundleResources/applinks":{"abstract":[{"text":"The root object for a universal links service definition.","type":"text"}],"fragments":[{"kind":"text","text":"object "},{"kind":"identifier","text":"applinks"}],"identifier":"doc:\/\/com.apple.documentation\/documentation\/BundleResources\/applinks","kind":"symbol","navigatorTitle":[{"kind":"identifier","text":"applinks"}],"role":"symbol","title":"applinks","type":"topic","url":"\/documentation\/bundleresources\/applinks"},"doc://com.apple.documentation/documentation/Foundation/implementing-handoff-in-your-app":{"abstract":[{"text":"Create, send, and receive user activities directly.","type":"text"}],"identifier":"doc:\/\/com.apple.documentation\/documentation\/Foundation\/implementing-handoff-in-your-app","kind":"article","role":"article","title":"Implementing Handoff in Your App","type":"topic","url":"\/documentation\/foundation\/implementing-handoff-in-your-app"},"doc://com.apple.documentation/documentation/technologies":{"abstract":[],"identifier":"doc:\/\/com.apple.documentation\/documentation\/technologies","kind":"technologies","role":"overview","title":"Technologies","type":"topic","url":"\/documentation\/technologies"},"supporting-associated-domains-1.png":{"alt":"A screenshot of the Associated Domains table in Xcode with two domains listed.","identifier":"supporting-associated-domains-1.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.Xcode\/supporting-associated-domains-1@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.Xcode\/supporting-associated-domains-1~dark@2x.png"}]}}}