Using associated domains alternate mode during development

When working with associated domains, for example to support universal links, shared web credentials, or App Clips, iOS fetches the apple-app-site-association (AASA) file through Apple's CDN, not directly from the server where the file is hosted.

This works well in production, but during development it can be inconvenient: changes to the file may take a while to propagate, and local or staging servers might not be publicly reachable at all.

To make development easier, Apple offers an alternate mode.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

In this mode, iOS bypasses the CDN and talks directly to our server. We can enable it by modifying the associated domains entries in Xcode.

Let's say we have the following associated domain configured:

applinks:example.com

During development, we can add a mode parameter, for example:

applinks:example.com?mode=developer

To use developer mode, the device must also opt in. On the device, we enable Settings → Developer → Associated Domains Development.

Additionally, for developer mode to work, the app needs to be signed with a development provisioning profile.

Only with all of these in place (the ?mode=developer suffix in Xcode, the developer toggle on the device and signing with a development provisioning profile), changes to the AASA file become visible immediately, and we can even test against local or staging environments as long as they are reachable from the device.

Available alternate modes

• developer: works on devices in developer mode and with apps signed using a development profile.
• managed: intended for enterprise environments on devices enrolled in Mobile Device Management (MDM). Useful when organizations control device policies.
• developer+managed: a combination of the two. Direct fetching is enabled only when the device is both in developer mode and managed by MDM.