Package an iOS app manually with the iOS Enabler

The iOS Enabler utility is provided to simplify and support the re-signing and repackaging of apps. The iOS Enabler is available in both GUI and command line versions.

Prerequisites

The following must be installed on the Mac machine that you use for packaging an iOS app:

  • OS X 10.8 or 10.9, or macOS Sierra 10.12, High Sierra 10.13, Mojave10.14, or Catalina 10.15.
  • Xcode 6 or higher

Additional required resources

Copy the following resources to your Mac machine:

iOS Enabler

The Enabler is located in the Agent directory on the UFT Mobile server machine:
Linux:
<Path to your server installation folder>/server/Agent

Windows:
<Path to your server installation folder>\server\Agent

You can also download it from the ADM Marketplace.

The iOS Enabler tool is available in both GUI and command line versions.

Agent apps (only when using the iOS  Enabler to sign the Agent apps) Download the 4 Agent apps from the APPS tab of the UFT Mobile Lab console (admin users only).
UFT Mobile dylib This library enables your apps to work with UFT Mobile. The library is included in the iOS Enabler package that you can download by selecting your version of UFT Mobile on ADM Marketplace. It can also be found in the following location on the UFT Mobile server machine:
Linux:<Path to your server installation folder>/server/Agent

Windows: <Path to your server installation folder>\server\Agent
Code signing certificate

This is the certificate your organization uses to code sign apps. The certificate must be installed on the Mac machine that you are using, and can be seen in the Keychain Access program. For more details on the certificates needed, see iOS app signing.

Code signing provisioning profile This is the mobile provisioning profile that your organization uses to code-sign apps. This is originally a file downloaded from the Apple Developer Member Website and installed on your Mac. For details on how to generate a provisioning profile, see Generate a development provisioning profile.

Back to top

iOS Enabler on Mac - GUI version

The GUI version of iOS Enabler allows you to enter the required values in an accurate and simple manner, using a graphical interface.

To re-sign or repackage apps using the GUI iOS Enabler:

  1. Extract the files onto your Mac machine from the downloaded Enabler.zip package.
  2. Open HPMCEnabler-GUI.app: Ctrl+click or right-click on the app and select Open from the context menu.

    Note: The GUI version of the Enabler is not distributed via the Mac App Store. If you try to install it through the App Store, it will issue a security warning indicating that the application cannot be opened since it is from an unidentified developer. Instead, use the method described above.

  3. Fill in the fields in the iOS Enabler.

    User interface elements are described below:

    UI Element Description
    Agent/L - AUT
    The Enabler mode:
    Agent/L mode. For code signing the Agent apps
    AUT mode. For signing and packaging apps
    Original IPA
    The full path to the original ipa file that you want to re-sign. For example, if you are re-signing the Agent app, enter /<full_path>/HP4M-Agent.ipa
    UFT Mobile Dylib

    In AUT mode only. A library to inject that enables your apps to work with UFT Mobile. The library is included in the MCEnabler.zip file. It can also be found in the Agent directory on the UFT Mobile server machine.

    SV Framework

    In AUT mode only. The full path of the folder containing the SV (Service Virtualization) framework. For details, see Use Service Virtualization (on-premises).

    Destination
    A destination for the generated files on your Mac machine.
    Provision Profile
    The path to the provisioning profile file on your Mac machine.
    Certificate Name

    A drop-down list of the installed certificates from the Keychain. Select a certificate from the list or click Suggest to get the recommended one. If the certificate is not listed, it is not properly installed on this Mac machine.

    Note: The iOS Enabler does not check the validity of the certificate, so you must ensure that it is valid.

    Verbose
    Displays warning and error messages in the text area, if the Agent is not enabled properly.

    Tip: To keep existing entitlements, clear the contents of the Provision Profile field and make sure the Certificate Name is the same as the original ipa.

  4. Click Run. This generates an additional ipa file, customized with your code signing certificate and a provisioning profile.

    To keep existing entitlements, clear the contents of the Provision Profile field and make sure the Certificate Name filed is the same as the original ipa.

  5. A new ipa file is created:
    Agent apps: Proceed to Distribute the re-signed Agent apps (manual signing only)
    Other apps: Upload the new ipa to UFT Mobile.

    Note: Whenever you upload a new or modified ipa file, as a result of adding or changing an iOS device, make sure to unplug the device and plug it in again.

Back to top

iOS Enabler on Mac - command line version

The command line version of iOS Enabler allows you to re-sign and repackage apps using the terminal command line.

Use the following syntax when running the Enabler from the terminal command line.

$ <path>/MCEnabler <path>/<original_ipa>.ipa [<options>]

Command line options:

-inject

Inject the dylib into the app. Provide the full path to the HPMobileCenter.dylib.

-codesign

Codesign the app with a certificate. This is the certificate your organization uses to code sign apps. The certificate must be installed on the Mac machine that you are using, and can be seen in the OSX Keychain Access program.

Use the full name of the certificate as shown in the Keychain.

For more details on the certificates needed, see iOS app signing.

-p Attach a mobile provisioning profile to the App. Provide the path to the provisioning profile on your Mac machine.
-e   Entitlements file.
-f  (or -framework) The full path of the folder containing the SV (Service Virtualization) framework. For details, see Use Service Virtualization (on-premises).
-r Resources rules list. Your custom resource rules file.
--original-res-rules Use the Resources rules file from the original IPA, ResourceRules.plist.
--generic-res-rules Apply a generic Resources rules definition. If the codesign fails due to problems with the resources, try this option. A generic template will be used.
--force-res-rules Runs the enabler as if the --original-res-rules option was set. If no original rules were found, it runs the enabler as if the --generic-res-rules option was used.
--no-url-scheme    Do not add a unique URL scheme in Info.plist. By default, it is added. The format of scheme is hpmc-(a 32 char uid)
--verify-agent     Issue a warning if the Agent is not enabled properly.
-d destination folder   An optional path to the folder in which to place the new .ipa file. The folder must exist.
-n new file name     An optional name for the new .ipa file.
-v verbose
-V print version
-h print usage

After you run the Enabler, a new ipa file is created.

Note: Whenever you upload a new or modified ipa file, as a result of adding or changing an iOS device, make sure to unplug the device and plug it in again.


Back to top

Distribute the re-signed Agent apps (manual signing only)

Once you re-sign the Agent apps, deploy them in the following way:

  1. Rename the files by removing -Codesigned from the file name. For example, the Agent file should be renamed from HP4M-Agent-Codesigned.ipa to HP4M-Agent.ipa. Upload the apps to UFT Mobile.

  2. Upload the apps to UFT Mobile.
  3. Navigate to DEVICE LAB > CONNECTORS, select the required connectors in the grid, and click Distribute Agents . After the updated Agent apps have been distributed to connectors, select the relevant connectors from the grid and click Reconnect Devices. For more information , see View and manage connectors (Admin only).
    Note that even if an earlier upload of an Agent app is selected in the app card, the latest upload is always used for distribution to connectors.

    Note: If the Agent doesn't install or run on a device, there is most likely a problem with your code-signing certificate or provisioning profile. Make sure that:

    • The “get-task-allow” entitlement is set to true.
    • All the UDIDs of your devices are included in the list.

    Back to top

    See also: