HeadSpin Documentation
Documentation

Bring Your Own Device

HeadSpin supports connecting a device to a local machine and bridging the connection to the platform. This allows all devices on the local machine to become visible on the platform for you and your team to use just like any other device in HeadSpin's distributed device cloud. All that's needed is a mobile device and a computer that can run the HeadSpin CLI.

iOS

Android

iOS

Note Regarding iOS 17

Currently HeadSpin only has limited support for the use of our proprietary CLI with devices running iOS 17. Particular commands, including <code class="dcode">hs connect</code> and <code class="dcode">hs provide</code> are not yet enabled for iOS 17. When this functionality is enabled, this section will be updated. For more information on what is and is not supported on iOS 17 devices, please see our iOS 17 support documentation.

Windows Users and iOS

A note for users testing iOS on Windows machines: In order to properly support iOS device testing on a Windows machine, you will need to install iTunes for Windows. However, iTunes MUST NOT be installed from the Microsoft Store; this version of the program will not have the necessary support components. Please only install iTunes from Apple’s support page using one of the links under “If you can’t access the Microsoft Store”. By default, Apple will offer the current version of iTunes for download; we recommend installing this, rather than looking for a legacy version of iTunes. (If you are using an older version of iTunes, we also recommend updating to the most up-to-date version compatible with your Windows OS.) After this is done, iOS devices can be attached to Windows. They will not be visible in iTunes itself, but they will be connected as network devices and can be seen following the proper steps with the HeadSpin CLI tool.

Generate app signing credentials

As of iOS 15 (and later), so long as an enterprise profile is enabled by the developer and any devices intended for testing trust that profile manually, apps no longer need to be specially signed as they were in the past. Generally speaking this will allow iOS devices to be easier and more accessible as BYOD devices, since these previously necessary signing credentials are optional for iOS 15+. Please ensure your iOS BYOD devices trust the HeadSpin Inc. Enterprise app profile. Detailed steps for performing this task are below under the 'Provide iOS device' section. Note that older iOS versions' signing needs will still apply to devices with those versions installed, so the steps for signing apps are still included here in this section.

The Bring Your Own Device (BYOD) feature works by depending on the host using the HeadSpin CLI to sign apps before they can be installed on BYOD devices. The signing is performed automatically with no action required by the user but this does require a one-time setup procedure. If the host already has valid signing credentials you may skip this section and use Set signing credentials to configure the HeadSpin CLI to use them.

The following instructions will guide you in creating the Xcode Wildcard App ID and downloading the associated provisioning profile.

You will need an Apple ID enrolled in the Apple Developer Program. You may enroll as either an Individual or an Organization. Once enrolled, download and install Xcode.

IMPORTANT: To create the wildcard App ID and the corresponding provisioning profile, your Apple ID enrolled in an Organization must be the Account Holder or an Admin. Otherwise someone in your Organization with those roles will need to follow these steps to generate the profile. Once the admin has accomplished this task any other user in the Organization, admin or not, can repeat the steps to automatically configure their signing credetials and download the profile.

Navigate to the Accounts preferences tab in Xcode. With Xcode open, select Xcode > Preferences (⌘,) from the menu bar and choose the Accounts tab. Use the plus (+) to add your Apple ID enrolled in the Apple Developer Program.

accounts

Create a new Xcode project, i.e., File > New > Project (⇧⌘N). Depending on your version of Xcode the interface may vary but you need to select the iOS app template.

Once Xcode opens the project, select your app Target in the Project Editor, open the Signing & Capabilities tab, and make sure that "Automatically Manage Signing" is enabled. This will allow Xcode to generate signing credentials including the Apple Developer certificate and the wildcard provisioning profile.

profile

Select the Team that registered your device UDIDs and Xcode should indicate that an Xcode Managed Profile is ready. Hover over the info icon and you should see the details of a wildcard provisioning profile with an App ID "<code class="dcode">*</code>". That's it, you're ready to use BYOD for iOS.

Provide iOS device

Note that before you can utilize an iOS device with HeadSpin, you must trust our platform's app on the device to enable communication between the device and HeadSpin's tools. To do this, navigate to Settings > General > Profiles & Device Management (the specific name of Profiles & Device Management may vary slightly depending on iOS version). Select the HeadSpin Inc. Enterprise app profile and click Trust. When the profile is trusted, you will be able to proceed.

The CLI facilitates initiating the bridge between a local device and HeadSpin's platform. To provide a device, run:


hs provide -t {api-token} --platform ios {device-udid}

Your device should now be accessible in Remote Control and can be used like any other device on the platform.

ios remote

To stop providing a local device to the platform, run:


hs unprovide {device-udid}

iOS Troubleshooting

The following is a list of possible issues that can arise.

If you are having trouble launching any of our platform apps, first double-check that the device has trusted our enterprise profile. Steps for this can be found in the 'Provide iOS device' section.

Xcode automatic signing management generates an explicit App ID provisioning profile

  • Your Developer Program account may already have a wildcard App ID. Check the Identifiers page for an entry containing a * identifier.
  • Your Apple ID does not have the privileges required to create a provisioning profile. Verify that an account with admin privileges has generated the wildcard identifier profile and that it's not expired on the Profiles page.
  • An explicit App ID provisioning profile exists for the given bundle identifier. Choose a unique bundle identifier relative to the App IDs available on the Identifiers page.

Android

Provide Android device

The HeadSpin CLI facilitates initiating the bridge between a local device and HeadSpin's platform. To provide a device, run:


hs provide -t {api-token} --platform android {device-serial}

Your device should now be accessible in Remote Control and can be used like any other device on the platform.

android remote

To stop providing a local device to the platform, run:


hs unprovide {device-serial}