iOS Connection Guide
Easily connect your device and run your first test on any iOS device
Automatically pinpoint accessibility issues in your iOS mobile applications on any device or simulator and generate actionable reports.
This page contains guidance for:
- Environment Setup
- Connecting to the Evinced Flow Analyzer for Mobile
- Installing your app on an iOS simulator
- Troubleshooting Connectivity Issues
Evinced Desktop Client Setup
Download and launch the Evinced Mobile Flow Analyzer desktop application. Once you have done so either sign up for an Evinced account or log in with your existing account. Once logged in, select the iOS connection option.
The Evinced Flow Analyzer for mobile uses the Apple trust chain to connect to devices and scan applications for accessibility issues. In order to do this, Xcode needs to be installed on your workstation. Xcode is a free download from App Store on your device.
Once installed, we need to make sure that the Xcode command line tools are also installed. To do this, in the top system menu, navigate to Xcode > Preferences > Locations and ensure that a version of the Command Line Tools is selected.
Next, we need to add your Apple Developer account to Xcode.
- If you need an Apple Developer Account sign up here. Once created enroll in the Apple Developer Program.
- In the top system menu, navigate to Xcode > Preferences > Accounts and click the “+” icon in the bottom left to add an account.
- Select “Apple ID” and click continue. Complete the flow entering your Apple ID and password for your Apple developer account.
Download the certificates
- While still in the Xcode > Preferences > Accounts page, select your account (make sure it is the one that has “Developer” under “Role”.) and click “Download Manual Profiles” and then click “Manage Certificates”
- Click the “+” icon in the bottom left hand corner and select “Apple Development” to ensure you have the certificate installed.
Evinced requires access to the device for accessibility scanning and so the device must be a registered device within the Apple Developer account. This can be done in two different ways after plugging in your device via USB.
- Locate the UDID of your Apple device and logging into Apple Developer. Navigate to Certificates, IDs & Profiles > Devices and click the “+” icon to add a device and complete the flow.
Push an app to the device via Xcode
- Select your device from the top menu, and make sure that you have selected the correct team and a developer signing certificate. Click the “Play” button icon in the top left area of the Xcode window to “Start the active scheme”. This will prompt a pop-up that will ask for permission to register device. Accept and this will automatically register the device.
Connecting to the Evinced Flow Analyzer for Mobile
Select your device or a simulator from the “Device” dropdown and enter the Apple Developer Team ID found in the membership tab after logging in to developer.apple.com.
Note: This is not your email address associated with the developer account.
Click “Connect”. The first connection may take a minute or two. Subsequent connections will be a bit faster.
The Evinced Flow analyzer for Mobile iOS connection page. There are three inputs, one for device, one for Apple Developer ID and a connect button.
When prompted allow Automation on the device (iOS 15+).
The device should now connect and you are ready to start Scanning!
Installing your app on an iOS simulator
Installing an App via Xcode
If you have access to the application source code simply open the
.xcodproj file to view the project in Xcode. Simply select your preferred simulator from the dropdown list at the top of the window. Then run the project and the app will automatically be installed on the simulator.
App installation from the command line
Finding the simulator identifier
We first need to find the identifier of the simulator we would like to use. We can find this using the command line or through Xcode
Run the command
xcrun simctl list from the terminal. This will give us a full list of simulators with their identifiers and boot status.
Open Xcode and in the top menu go to Window > Devices and Simulators. With Simulators tab selected, choose your preferred simulator option to view the identifier located at the top of the window.
Ensure the simulator is in the “booted” state
xcrun simctl list from the command line you will notice that the simulator state is given as well. This will either be
Booted. In order to install an app on the simulator it must be in the
Booted state. Note: This may not mean that the simulator is launched on your workstation. To boot a device run the following command in your terminal.
xcrun simctl boot <Simulator ID>
After running this command, when the
xcrun simctl list command is run, you should expect to see your selected simulator in the
iPhone 8 (260D77A2-6194-4C13-B5A6-EC07F606F158) (Booted)
Installing the app
We can now install the app run the command below that includes a file path to your .app fine. Please see this post if you need help creating an .app file.
xcrun simctl install <Simulator ID> /Path/To/My/App.app
That’s it! You can now select the simulator from the “Device” dropdown in the Evinced desktop client and start scanning!
Troubleshooting Connectivity Issues
No devices are present under the device list
Evinced uses the Xcode command line tools to check for available devices and simulators. If no devices are populated it usually means that the command line tools are not available. Follow the instructions above to make sure that the Xcode command line tools are available. To confirm the command line tools are installed correctly, open a terminal window and run the command
xcrun xctrace list devices.
Device not found error
This error could be caused by a few different reasons. (Don’t worry, improved error messaging is on the way!)
The device is not registered with the Apple Developer account being used. Follow the instructions above to confirm the device is connected properly.
The developer account doesn’t have adequate permissions. Confirm with the admin of the Apple Developer account that the permissions below are granted.
Bundle ID Registration
The bundle id for WebDriverAgent is not able to be registered because it is not available or permissions are preventing registration. Evinced uses the open source WebDriverAgent that needs to be installed on the iOS device. This is the same tool used by Appium, the most popular mobile automation framework.To determine whether this could be the problem, check the log for the message below. The log can be found by selecting the Help > Show logs in finder option in the Evinced Desktop client menu.
Failed to register bundle identifier: The app identifier "com.facebook.WebDriverAgentRunner.xctrunner" cannot be registered to your development team because it is not available. Change your bundle identifier to a unique string to try again
To fix this issue we need to change the app identifier to something that is available. To do this, we can simply open the WebDriverAgent Xcode project and change the bundle id. To get started, open your “Applications” folder and right click on the Evinced Mobile Flow Analyzer app and select “Show Package Contents”.
Then navigate to Contents > node_modules > appium-webdriveragent > WebDriverAgent.xcodeproj and open the project. Our recommendation would be to try replacing “facebook” in the bundle ID with your company. E.g.
An easy way to do this is to go to the “Find” menu and “Find in Project..” and search for “facebook”. This will surface all of the areas that need to be changed. Then, select your appropriate Team and Signing Certificate from the “Signing & Capabilities” menu and run the project after selecting your device to ensure the installation is successful. Once this is confirmed return to the Evinced desktop client to connect.
I need to use the same VPN connection as my workstation
It is possible to share the internet connection from the Mac to the device via USB. First, connect the device to the workstation via USB cable. Then in the MacOS settings navigate to to System Preferences > Sharing. Then select “Internet Sharing” and “iPhone USB” (or similar based on the device name) as shown below.
Still having trouble? Please reach out to email@example.com and we would be happy to help!