Evinced announces first end-to-end mobile (iOS & Android) accessibility solution

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

Environment Setup

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's desktop app welcome screen. The heading is saying "Welcome to Evinced!" beneath the heading, a paragraph is saying "Let's scan your mobile app to analyze accessibility issues. Choose your mobile app OS:" Then there are two buttons to choose between iOS and Android.

Xcode Setup

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. Xcode as seen in the Apple App Store. Screenshot and download and open options are present.

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. The Xcode "Locations" screen with the "Command Line Tools" section highlighted

Next, we need to add your Apple Developer account to Xcode.

  1. If you need an Apple Developer Account sign up here. Once created enroll in the Apple Developer Program.
  2. In the top system menu, navigate to Xcode > Preferences > Accounts and click the “+” icon in the bottom left to add an account.
  3. Select “Apple ID” and click continue. Complete the flow entering your Apple ID and password for your Apple developer account. The Xcode Accounts screen. The "Select Account Type" is opened with the "Apple ID" option highlighted
  4. Download the certificates

    1. 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
    2. Click the “+” icon in the bottom left hand corner and select “Apple Development” to ensure you have the certificate installed. The Xcode "Signing certification" pop-up with the "add certification" drop-down list opened showing a single option: "Apple Development"

Device Registration

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.

  1. 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. The Devices page from the developer.apple.com website. The add a device button is highlighted.
  2. Push an app to the device via Xcode

    1. 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. The Xcode development application with the phone selection highlighted. The signing certificate dropdown is also highlighted with Development selected. Also highlighted is the play button to build and push the application to 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. 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+). An iPhone screen with a Touch ID alert permission to enable UI Automation

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. An open Xcode project with a list of available simulators including various models iPads and iPhones

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

Command Line

Run the command xcrun simctl list from the terminal. This will give us a full list of simulators with their identifiers and boot status. A terminal window with a list of available iPhone and iPad simulators, identifiers, and their boot state.

Xcode

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. The Xcode Devices and Simulators window with an iPhone 12 simulator selected. The identifier is shown in the window.

Ensure the simulator is in the “booted” state

When running xcrun simctl list from the command line you will notice that the simulator state is given as well. This will either be Shutdown or 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 Booted state.

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!)

Device Registration

The device is not registered with the Apple Developer account being used. Follow the instructions above to confirm the device is connected properly.

Account Permissions

The developer account doesn’t have adequate permissions. Confirm with the admin of the Apple Developer account that the permissions below are granted. The Users and Access page seen by an admin on the website developer.apple.com. Three options are highlighted, Access to Certificates, identifiers and profiles, Access to cloud managed distribution certificate, and Create Apps.

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”. A finder window showing the applications folder. The Evinced Mobile Flow Analyzer is highlighted and a menu is showing with Show Package Contents selected. 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. com.company.WebDriverAgentRunner.xctrunner.

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. Xcode window with a find text containing option open and lists of identifiers with the word facebook included. 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. The sharing window from within the Mac System preferences. Internet sharing and iPhone USB are selected.

Still having trouble? Please reach out to support@evinced.com and we would be happy to help!