Documentation

Unreleased iOS App Testing With UserTesting

At UserTesting, we’ve made it as easy as possible for you to use our kit - usually with zero modifications to your project, zero lines of code and zero configuration required. In fact, for most users, all that's needed is a regular ad-hoc build of your app, like you make for TestFlight or internal distribution, which you'll upload to the UserTesting platform when you launch your test. For some users with more complex entitlements, there’s a bit of configuration – but still zero lines of code.

UserTesting requires zero integration for Android testing.

How to Create an Ad-hoc Build:

When launching an unreleased iOS app test, the UserTesting platform will ask you to upload an ad-hoc build of your app. If you have a development team they should know what an "Ad-hoc build" is and be able to create one for you.

To create an ad-hoc build, in Xcode, select the appropriate target and set it to build for ‘Generic iOS Device’ rather than the simulator, then choose ‘Archive’ once that process completes find the newly created archive in the Organizer. In the Organizer, choose ‘export’ and pick “Ad Hoc”. Save that file - then upload it to UserTesting. We’ll do the rest.

Determining if Your App is Supported by the UserTesting Platform:

The easiest way to determine if your app is compatible with the UserTesting platform is to upload an ad-hoc build of your app when creating a test. When you upload your app the UserTesting platform will check your app for compatibility. If it's compatible UserTesting automatically integrate your app with our SDK and ready it for testing. If your app is not currently compatible, you will see an error.

If your app is not currently compatible you may need to modify your app's entitlements or manually integrate our SDK.

Configuring Incompatible Apps for the UserTesting Platform:

The UserTesting platform supports the vast majority (if not all) types of iOS apps but it only supports a subset of app entitlements.

Your app only uses some or all of the following entitlements:

application-identifier get-task-allow com.apple.developer.team-identifier beta-reports-active keychain-access-groups aps-environment com.apple.developer.associated-domains

There is no need to manually integrate the UserTesting SDK if your app only requires some or all of the above entitlements. All that is needed is a regular ad-hoc build of your app which you'll be able to upload to the UserTesting platform without issue.

Your app uses additional entitlements not found in the list above and you have an Enterprise certificate:

You can manually integrate the SDK and then create an enterprise build of your app which you'll be able to upload to the UserTesting platform without issue. Enterprise certificates are used to distribute apps internally to hundreds or thousands of users. If your app is in the App Store, then you probably do not have one. If you do use enterprise distribution, skip to “Installing the SDK”, below.

Your app uses additional entitlements not found in the list above and you do not have an enterprise certificate:

If you do not have an enterprise certificate, you will need to remove the entitlements that do not appear in the list above and then create a regular ad-hoc build of your app. You should be able to upload this build to the UserTesting platform without issue. There is no need to manually integrate the UserTesting SDK or make any other changes to your app beyond removing the unsupported entitlements.

Installing the UserTesting SDK

Download SDK Here

If you need to manually integrate the UserTesting SDK, don’t despair. It’s zero lines of code and requires just a single integration step.

Add UserTestingSDK.framework to your project

  1. Select your project in the "Project Navigator".
  2. Select your app's main target from the list of targets.
  3. In the 'General' tab, drag UserTestingSDK.framework into the 'Frameworks, Libraries, and Embedded Content' list.

    IMPORTANT: When prompted, make certain to select to add the files to your app target!

Adding the SDK Embedded Libraries

Verify that the SDK is properly installed

Run your app on device to confirm that the SDK is integrated (running in the simulator is not supported). You should see a full-screen view blocking access to your app; our framework only allows access to your app during a UserTesting test.

Frequently Asked Questions

  • What version of iOS do participants use?

    Participants will run your app on iOS 12 or above.

  • Does UserTesting require any code to activate?

    No. The UserTesting SDK starts automatically when your app runs. It does not require developers to import any code or call any methods to start or stop. The UserTesting SDK runs alongside your app without affecting its behavior.

  • Can I test hybrid and cross-platform apps with UserTesting's SDK?

    Yes!

  • Can I integrate the SDK with Xamarin or other cross-platform tools?

    The SDK has no header file or initialization, so adding it following the above instructions should work with minimal modifications.

Removing Older Versions

If you integrated an earlier version of the SDK, you should delete it from your project and reintegrate the latest version using the steps above.