diff --git a/articles/setup-experience.md b/articles/setup-experience.md index e13965d00f..12a4caa725 100644 --- a/articles/setup-experience.md +++ b/articles/setup-experience.md @@ -264,6 +264,21 @@ When this feature is enabled, any failed software will immediately end the setup End users won't continue through setup experience unless they press Command (⌘) + Shift + X. +### App Store (VPP) apps in setup experience + +App Store (VPP) apps are installed by Apple. Fleet sends an [InstallApplication](https://developer.apple.com/documentation/devicemanagement/install-application-command) MDM command, and the device downloads and installs the app from the App Store. As a result, VPP installs during setup depend on Apple's services and the device's connection to the App Store while it's still in Setup Assistant. + +Because Apple performs the install, things outside Fleet's control, such as an App Store or Apple Business outage, `InstallApplication` throttling, an expired VPP token, or too few licenses, can cause installs to fail or hang for every host at once. Fleet retries automatically (up to 4 attempts, waiting 10 minutes each time to verify), but retries won’t help while Apple itself is unavailable, and until an install finishes, the end user waits at the Setup Assistant screen. + +To reduce these risks: + +- Only add apps that end users need before their first login. Deliver everything else after enrollment using [automatic install](https://fleetdm.com/guides/automatic-software-install-in-fleet), which runs in the background and doesn't hold the device in Setup Assistant. +- Keep the setup experience software list short. Each item extends setup time. +- Before a large rollout, confirm your VPP token is valid and you have enough available licenses for the apps you're installing. +- If available, choose Fleet-maintained app over App Store (VPP) app for better control + +If a host gets stuck, you can send the [`DeviceConfigured`](https://developer.apple.com/documentation/devicemanagement/device-configured-command) command using Fleet's [Run MDM command](https://fleetdm.com/docs/rest-api/rest-api#run-mdm-command) API to let the end user through. + ## Run script To configure a script to run during setup experience: