Apple App Site Association must contain activitycontinuation field
Ensure your apple-app-site-association file contains the activitycontinuation field for handoff to work properly.
apple-handoff
28 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Apple Handoff overview
Apple Handoff is a feature that enables users to continue browsing your app or website on another device. Expo Router automates runtime routing for this feature, but one-time configuration must be set up manually. The underlying iOS API (NSUserActivity) requires a webpageUrl which the OS uses as the current URL for switching to your app.
Apple Handoff restrictions and considerations
Handoff is Apple-only. It cannot be used in Expo Go app as it requires build-time configuration. Handoff requires universal links to be configured at least on iOS and contain the activitycontinuation object. Handoff requires the expo-router/head component to be used on each page you want to support, or in the root layout if you want all pages to be continuous.
Apple App Site Association file structure
The public/.well-known/apple-app-site-association file must include an activitycontinuation key with an apps array containing your app's bundle ID and Team ID formatted as <APPLE_TEAM_ID>.<IOS_BUNDLE_ID>. The file must contain applinks with details that include appIDs and components. The webcredentials object is optional but recommended.
Apple App Site Association example
Example apple-app-site-association file structure: { "applinks": { "details": [ { "appIDs": ["<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>"], "components": [ { "/": "*", "comment": "Matches all routes" } ] } ] }, "activitycontinuation": { "apps": ["<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>"] }, "webcredentials": { "apps": ["<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>"] } }
Setup Safari command to generate apple-app-site-association
Use the npx setup-safari command to generate the apple-app-site-association file based on your app config. npm: npx setup-safari, yarn: yarn dlx setup-safari, pnpm: pnpm dlx setup-safari, bun: bunx setup-safari.
Configure Handoff origin in app.config.tsx
Set the Handoff origin in app.config.tsx using the expo-router config plugin. The headOrigin property must start with https:// and is the URL that will be used for webpageUrl when the user switches to your app. Example configuration shows setting headOrigin to a development ngrok URL for development and a production URL for production.
Associated domains configuration example
In app.config.tsx under ios.associatedDomains, configure applinks, activitycontinuation, and webcredentials with the same domain. Example: ["applinks:example.ngrok.io", "activitycontinuation:example.ngrok.io", "webcredentials:example.ngrok.io"].
Prebuild native project after app.config changes
After configuring the app config with handoff settings, regenerate your native project with npx expo prebuild -p ios (or equivalent for yarn, pnpm, bun).
Start website before installing app for handoff
In development, you must start the website before installing the app on your device. When you install the app, the OS will trigger Apple's servers to ping your website for the .well-known/apple-app-site-association file. If the website is not running, the OS cannot find the file and handoff will not work. If this happens, rebuild the native app with npx expo run:ios -d.
Head component usage for handoff
Use the Head component from expo-router/head in any route that you want to support handoff. Inside the Head component, add the meta tag <meta property="expo:handoff" content="true" /> to enable handoff for that route.
Head component handoff example
Example usage of Head component for handoff: import Head from 'expo-router/head'; import { Text } from 'react-native'; export default function App() { return ( <> <Head> <meta property="expo:handoff" content="true" /> </Head> <Text>Hello World</Text> </> ); }
Meta tags supported by expo-router Head component
The expo-router/head component supports the following meta tags: - expo:handoff: Set to true to enable handoff for the current route. Defaults to false. (iOS only) - og:title and <title>: Set the title for NSUserActivity (unused with handoff) - og:description: Set the description for NSUserActivity (unused with handoff) - og:url: Set the URL that should be opened when the user switches to your app. Defaults to the current URL in-app with headOrigin prop in expo-router config plugin as baseURL. Relative paths will append headOrigin to the path.
Platform-specific Head meta tags
Use Platform.select to switch meta tag values between platforms. Example: <meta property="og:url" content={Platform.select({ web: 'https://expo.dev', default: null })} />
Enable Handoff on Apple devices
Ensure your Apple devices have Handoff enabled in system settings. Visit https://support.apple.com/en-us/HT209455 for instructions.
Test handoff on Mac and iPhone
To test handoff: 1) Open your native application on your device. 2) Navigate to a route that supports handoff and renders the <Head /> element. 3) To switch to Mac, click the app's Handoff icon in the Dock. 4) To switch to iPhone or iPad, open the App Switcher and tap the app banner at the bottom. If you only see the Safari icon in the App Switcher, handoff is not working.
Validate apple-app-site-association file
Test the apple-app-site-association file using a validator such as AASA Validator at https://branch.io/resources/aasa-validator/.
Troubleshooting: aggressive handoff settings
For debugging, enable aggressive handoff settings by ensuring the apple-app-site-association file matches all routes with {"applinks": {"details": [{"appIDs": ["<APPLE_TEAM_ID>.<IOS_BUNDLE_ID>"], "components": [{"/": "*", "comment": "Matches all routes"}]}]}}
Do not render Head component conditionally
Do not render the <Head /> element conditionally (for example, in an if/else block). It must be rendered on every page that you want to support handoff. Recommended to add it to the Root Layout component to ensure every route is linkable while debugging.
Test Ngrok URL accessibility before device installation
Ensure you can access the Ngrok URL via the browser before installing the app on your device. If you cannot access the URL, the OS will not be able to find the apple-app-site-association file and handoff will not work.
Code signing required for handoff
npx expo run:ios and Xcode will both codesign your app when associated domains is set up, which is required for handoff and universal links to work.
Handoff in Expo Go app limitation
Handoff between Mac and iPhone/iPad is not supported in the Expo Go app. You must build and install your app on your device.
Avoid developer mode suffix when testing handoff
Do not use the ?mode=developer suffix when testing handoff to native.
Do not use localhost URL for handoff testing
Do not use the local development server URL (for example, http://localhost:8081) for handoff testing as it cannot be used as a valid app site association link. Open the running Ngrok URL in your browser instead.
Bundle identifier prefix compatibility with iOS 16.3.1 and macOS 13.0
In iOS 16.3.1 and macOS 13.0 (Ventura), bundle identifiers starting with app. and io. will sometimes not trigger the native app to show up in the iOS task switcher. Use com. as the first part of your bundle identifier.
Apple App Site Association must use HTTPS
The apple-app-site-association file must be served from a secure URL (HTTPS). For development tunnels, use the EXPO_TUNNEL_SUBDOMAIN environment variable to configure the subdomain. Run npx expo start --tunnel to start with tunnel support.
Associated domains in entitlements file
Check your ios/project/project.entitlements file under the com.apple.developer.associated-domains key. This should contain the same domains as your web server/website. The URL cannot contain a protocol (https://), additional pathname, query parameters, or fragments.
Handoff web to native limitation
Handoff from web to native does not support client-side routing. The URL presented in the App Switcher will be the URL of the page you were on when you clicked the link or reloaded the page. This is a limitation of the web platform and not something that can be fixed by Expo Router.