Documentation

Integrating the UserTesting iOS SDK

Download SDK Here

No one likes adding complicated third-party libraries to their app. At UserTesting, we’ve made it as easy as possible for you to use our kit - usually with zero modifications to your project. In fact, it may be the world’s easiest installation: for most users, it requires zero lines of code and zero configuration — just a throw-away ad-hoc build of your app, like you make for TestFlight or internal distribution. 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.

Here’s how to find out if you need to integrate the SDK:

Your app uses in-app purchases, in-app payments, associated domains, or iCloud

If you use the above functionality in your app, and have an Enterprise certificate, you will need to integrate the UserTesting SDK. 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.

If you use the above functionality in your app, and do not have an Enterprise certificate, contact your Customer Success Manager or support@usertesting.com for more information – support for this functionality requires a different approach to remain secure.

Your app doesn't use in-app purchases, in-app payments, associated domains, or iCloud

If your app does not use in-app purchases, in-app payments, associated domains, or iCloud then there is no need to integrate our SDK. All you need to do to use UserTesting is generate an ad-hoc IPA and then upload it to UserTesting. (If you’re asking developers to do this for you, you can tell them “just like you would for TestFlight.”)

To do this in Xcode, select the appropriate target and set it to build for ‘Generic iOS Device’ rather than the simulator, and then choose ‘Archive’. In the Organizer, choose ‘export’ and pick “Ad Hoc”. Save that file - then upload it to UserTesting. We’ll do the rest.

Installing the UserTesting SDK

If you need to integrate the UserTesting SDK, don’t despair. It’s zero lines of code and requires just a few integration steps. Just follow these instructions to generate a build with UserTesting’s SDK embedded.

Link the UserTesting SDK:

  1. 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 'Embedded Binaries' list.

      IMPORTANT: When prompted, make certain to select to add the files to your app target! The framework will also automatically be added to "Linked Frameworks and Libraries".

    Adding the SDK Embedded Libraries

  2. Allow the app to run in the background.

    1. Select the "Capabilities" tab.
    2. Click to expand the "Background Modes" section.
    3. Toggle Background Modes ON if not already set.
    4. Check "Audio and Airplay".

    Background mode options

  3. Register the UserTesting test loading URL scheme

    1. Select the Info tab.
    2. Click on the disclosure button for URL Types.
    3. Click the + button.
    4. In the "Identifier" field, paste: com.usertesting.utstarttest
    5. In the "URL Schemes" field, paste: utstarttest-YOUR-APP-NAME-GOES-HERE, replacing YOUR-APP-NAME-GOES-HERE with the name of your application, minus any punctuation, spaces, or underscores. The exact contents don't matter; the value just has to be unique.

    URL Types

  4. Provide Camera and Microphone Usage Descriptions

    1. Open your app's info.plist file in Xcode.
    2. Select the last entry in the file and click on the + button to add a new entry.
    3. In the "Key" field of the new entry paste NSCameraUsageDescription (It will appear as Privacy - Camera Usage Description once entered if viewed in Xcode).
    4. In the "Type" field of the new entry select String.
    5. In the "Value" field type UserTesting uses the camera to record your feedback.
    6. Select the last entry in the file and click on the + button to add a new entry.
    7. In the "Key" field of the new entry paste NSMicrophoneUsageDescription (It will appear as Privacy - Microphone Usage Description once entered if viewed in Xcode).
    8. In the "Type" field of the new entry select String.
    9. In the "Value" field type UserTesting uses the microphone to record your feedback.

    Camera and Microphone Usage Descriptions

  5. Verify that the SDK is properly installed.

    1. Run your app in Simulator or on your device to confirm that the SDK is integrated. You should see a full-screen view labeled with the name of your application.

      Success!

Frequently Asked Questions

  • What version of iOS do testers use?

    Testers will run your app on iOS 8 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 a header (.h) file or call any methods to start or stop. UserTesting leverages the Objective-C runtime to run alongside your app without affecting its behavior.

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

    Yes! UserTesting customers have written plugins and modules for popular platforms. Please contact us if you would like to add a platform to the list.

  • 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. See some details below for a customer-supplied Xamarin DLL that may be helpful to other Xamarin users.

Removing Older Versions

If you integrated an earlier version of the SDK, you should delete them from your project. There were three files:

- libUserTesting.a
- UserTesting.bundle

Please delete these files, and then follow the steps above.

Troubleshooting

Note: By default the "Link Frameworks Automatically" is enabled in Build Settings. If it is not, you will need to link the following frameworks manually by adding them in "Link Binary with Libraries":

  • Foundation
  • AVFoundation
  • CoreMedia
  • MobileCoreServices
  • CoreTelephony
  • QuartzCore
  • UIKit