iOS distribution

iOS ad-hoc distribution requires every test device's UDID to be registered with Apple and included in the provisioning profile. buildtree includes a UDID collection flow to manage this.

Collect device UDIDs

Each project has a registration URL on the dashboard's Devices card. Share it with testers.

For each tester:

1. Open the registration URL in Safari on the iPhone. Chrome and other browsers cannot read the UDID.
2. Enter an email address.
3. Tap Register this device.
4. Install the configuration profile when iOS prompts.

The UDID appears in the dashboard as pending.

Approve devices

In the Devices card, each pending registration shows the email, IP, and user agent the tester submitted. Click Approve to allow the device.

Pending devices never appear in any export. Approval is the security control.

Register UDIDs with Apple

Click Download for Apple Dev Portal on the Devices card. The download is a .txt in Apple's bulk-add format and contains approved devices only.

Upload the file at Apple Developer → Devices → Register Multiple Devices.

Regenerate the provisioning profile

1. Apple Developer → Profiles → your ad-hoc profile → Edit.
2. Tick the newly added devices.
3. Save and download the updated .mobileprovision.
4. Rebuild the .ipa with the new profile.

Bundle id conflicts

Feature-branch builds that share a bundle id overwrite each other on the same test device. For side-by-side installs, use different bundle ids per branch. See the Expo or React Native guides.

Common gotchas

"Unable to download app at this time"

• The tester's UDID is not in the provisioning profile. Verify the device was added in Apple Developer, the profile was regenerated, and the .ipa was rebuilt with the new profile.
• The .ipa was built with the development export method instead of ad-hoc. Rebuild with --export-method ad-hoc.
• The install URL is being opened on a Mac. Use the iPhone instead.

"Untrusted Developer" with no trust option

iOS sometimes hides the trust option. Try:

• Toggle Airplane Mode off and on.
• Reopen Settings → General → VPN & Device Management.
• Reinstall the app.

Profile does not appear after registration

The tester needs to open Settings → Profile Downloaded manually and tap Install. iOS does not always pop the install sheet automatically.

Apple's 100-device limit

A standard Apple Developer account allows 100 devices per device type per year. The counter resets on the account anniversary.