Expo

Documentation

Installing a Custom iOS Expo client

Build and install a custom version of the Expo client with your own Apple Credentials using our build service. This custom version of the Expo client contains features that were previously only available on the Android versions. Our build service will prepare your custom Expo client, and you can install it to your iOS device directly from our website.

Adhoc Builds Overview

  • You’ll need a paid Apple Developer Account to configure credentials required for the development and distribution process of an app. Learn more here.
  • Install the expo-cli command line app by following the instructions here.
Windows users must have WSL enabled. You can follow the installation guide here. We recommend picking Ubuntu from the Windows Store. Be sure to launch Ubuntu at least once. After that, use an Admin powershell to run: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Run expo client:ios

You are given a choice of letting expo-cli create the necessary credentials for you, while still having a chance to provide your own overrides. Your Apple ID and password are used locally and never saved on Expo's servers.
Letting Expo handle credentials for you will greatly simplify the build process. Learn more here on what these credentials are and how we store them.
$ expo client:ios
[16:44:37] Checking if current build exists...

[16:44:37] No currently active or previous builds for this project.
[16:44:37]
Please enter your Apple Developer Program account credentials. These credentials are needed to manage certificates, keys and provisioning profiles in your Apple Developer account.

The password is only used to authenticate with Apple and never stored.

? What's your Apple ID? xxx@yyy.zzz
? Password? [hidden]
✔ Authenticated with Apple Developer Portal successfully!
[16:44:46] You have 4 teams associated with your account
? Which team would you like to use? 3) ABCDEFGHIJ "John Turtle" (Individual)

? Select an iOS distribution certificate to use for code signing:
❯ [Create a new certificate]
  [Upload an existing certificate]

? Select an authentication token signing key to use for push notifications: (Use arrow keys)
❯ Used in apps: @john-turtle/expo-client-home-xxx (Key ID: XXX)
  [Create a new key]
  [Upload an existing key]
If valid credentials are found on the Expo servers from your previous use of expo-cli building an iOS binary, they will be automatically used.

If a Distribution Certificate cannot be found on the Expo servers, expo-cli will give you options to produce one. We describe these choices in more detail here.

We'll also help you handle your Push Notifications service key and provisioning profile. Remember that Push Notifications service keys can be reused across different Expo apps as well. If a Push Key cannot be found on the Expo servers, expo-cli will give you options to produce one. We describe these choices in more detail here.
Note: Push Notifications will be disabled on the Expo client if you choose not to upload your credentials. See here for more details.

In order to install your custom build of the Expo client on your iOS device, we will need to determine your device UDID so we can configure your provisioning profile and authorize your device to download the Expo client.
Custom builds of the Expo client can only be installed on devices which have been registered with Apple at build-time.
These devices are currently registered on your Apple Developer account:
┌───────────────┬──────────────────────────────────────────┐
│ Name          │ Identifier                               │
├───────────────┼──────────────────────────────────────────┤
│ muh iphone    │ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx         │
└───────────────┴──────────────────────────────────────────┘

? Would you like to register new devices to use the Expo client with? (Y/n) Y
If you would like to install the Expo client on an iOS device that is not listed above, follow the prompts to register your device.
? Would you like to register new devices to use the Expo client with? Yes

==================
[QR Code redacted]
==================

Open the following link on your iOS device (or scan the QR code) and follow the instructions to install the development profile:

https://expo.io/udid/XXXXXXXXXXXXX


After you register your device, we'll start building your client, and you'll receive an email when it's ready to install.
You will need to open this QR code on the iOS device you wish to register. Read this if you wish to register more than one iOS device.
On iOS versions earlier than 12.2, if you aren't taken to the Installing Profile page after pressing the Register button, try quitting your Settings app and try again.
UDID Workflow

On iOS versions 12.2 or later, a window will popup saying Profile Downloaded. Close the popup, go to the Settings app and navigate to the Profile Downloaded option to download the device enrollment challenge.
UDID Workflow

You can monitor the status of your Expo client build by visiting the link. You will also be notified via email when there are updates to your build. More details can be found on your build dashboard here.
==================
[QR Code redacted]
==================

Your custom Expo client is being built! 🛠
Open this link on your iOS device (or scan the QR code) to view build logs and install the client:

https://expo.io/client/XXXXXXXXXX

Install Workflow
Once your build is complete, open the status page on your iOS device and tap the Install button.

You're all set to use the custom version of the Expo client, containing features that were previously only available on the Android versions 🎉

Troubleshooting

Note: Push Notifications are currently unavailable with ad hoc clients until we complete our work to add an extra authentication layer to the Expo Push Notification service.

You will need to run expo client:ios in a project directory with a valid app.json, or pass in the flag to your custom configuration file with --config <path-to-file.json>. Make sure you set your Google API key in ios.config.googleMapsApiKey as described here.

If you are part of an organization with an Apple Enterprise account, you will need to ensure that you are given sufficient permissions to create and revoke certificates.
The administrator of the Apple Enterprise account will need to make you an App Manager and give you access to Developer Resources from the Apple Development Portal.
Apple Development Portal Permissions

If your app icon is blacked out like this or if it crashes at the splash screen like this, check that your ad hoc provisioning profile is still valid. You can do this by navigating to the Apple Development Portal profile list. The Expo client ad hoc profile should be prefixed with *[expo] for a bundle identifier that starts with dev.expo.client.
An invalid profile can be caused by revoking the distribution certificate or disabling the iOS devices associated with the profile. You can fix this by associating valid certificates and devices to the profile and pressing Save from the Apple Development Portal interface.
Invalid Profile

Frequently Asked Questions

expo-cli will give you options to produce a distribution certificate, and this section describes these options in more detail.

This will create a new iOS distribution certificate with a password. This option won't be available if you've already reached Apple's limit of two active certificates in your developer account.

Revoking an existing distribution certificate associated with an app is safe if:
  • Your app is distributed through the App Store and you are NOT on an Apple Enterprise account.
Revoking an existing distribution certificate associated with an app is NOT safe if:
  • Your app is distributed through the App Store and you are on an Apple Enterprise account.
  • Your app is distributed ad hoc (distributed outside of the App Store for testing purposes).
An App Store app gets re-signed with an Apple certificate when it goes on the store with non-Enterprise accounts. Revoking the certificate therefore won't affect it. Enterprise apps and apps distributed ad hoc use the original certificate, which means revoking it will cause the app to stop functioning on all devices it is installed on.

If you have a password-protected certificate, you can provide the path to your .p12 file as well as your password for upload. We recommend following this excellent guide on making a P12 file for making your own certificates.
Note: this guide recommends leaving the P12's password blank, but a P12 password is required to upload your own certificate to Expo's service. Please enter a password when prompted.

expo-cli will give you options to produce a push key, and this section describes these options in more detail.

This will create a new push key. This option won't be available if you've already reached Apple's limit of two active keys in your developer account.

If you revoke an existing push key, you will no longer be able to send Push Notifications to your apps with the revoked key.

If you have your push key on file, you can provide the path to your .p8 file for upload.

Push Notifications will be disabled on the Expo client if you choose not to upload your credentials. See here for more details.

You can register multiple iOS devices by submitting multiple requests to build the Expo client. We've currently limited one iOS device registration per build request.

We do not support simulator builds for adhoc Expo client builds yet.