Use the iOS Wrapper to Embed Monitoring in an iOS App

To add monitoring to a mobile app, you must embed Aternity's monitoring into the app itself, before it is encrypted. This automatically starts reporting a wealth of performance and usage data by default. This article describes how to embed monitoring in iOS apps using the Aternity iOS Wrapper.

Add a mobile app for monitoring

The Aternity Wrapper is a command line tool which quickly and automatically adds monitoring features to your mobile app, without requiring access to the app's source code.

To determine whether to use the Aternity iOS Wrapper or the Aternity iOS Mobile SDK to integrate monitoring in your app, see How To Embed Monitoring in a Mobile App.

You can use the Aternity Wrapper on your in-house app or on a third party app, so long as you have access to the unencrypted app file, in any of the following file formats:

  • A standard app with the extension .ipa, like appname.ipa

  • An Xcode archive of iOS applications (.xcarchive files)

  • Citrix XenStore MDX packages.

The Aternity iOS Wrapper works seamlessly with your existing MDM (mobile distribution management) system. If you distribute third party apps like WorxMail to your workforce, you typically already have access to the unencrypted appname.ipa file, to sign it with your own certificate.

With the Aternity Wrapper, you can sign the app at the same time as applying Aternity's monitoring functionality, all in a single command.

Before you begin

Before embedding Aternity's monitoring into an iOS mobile app, verify your Mac conforms to the following minimum system requirements (Aternity iOS Wrapper and Aternity iOS Mobile SDK):

Attribute Requirement (iOS Wrapper and Aternity iOS SDK)

Operating system

Mac OS X 10.7 or later.

Java Developer Kit

JDK 1.8 or later.

Programming environment

Apple XCode 7.


Internet access.

App resource usage

When you add Aternity functionality to an iOS app:

  • Disk storage size increases by 3.3MB.

  • RAM size is an extra 5-10MB.

  • CPU usage rises by 1%.

  • Your app must be fully functional and ready for deployment.

  • Ensure the iOS device is running iOS 8 or newer.

  • Download and install JDK on your Mac. Once installed, type java -version in the command shell to verify the Java installation and version.

  • Download and install Xcode on your Mac, with its command line tools. Once installed, type xcode-select -p in the command shell to verify the Xcode installation. To install Xcode command line tools, type xcode-select --install in the command shell.

  • Ensure you have your provisioning profile which includes your Apple Developer ID and other security information required to sign your app with your certificate. For more information, check and search for provisioning profile. Your certificate must also be properly installed in the keychain of the computer you are using to wrap the app.


  1. Step 1 Contact Customer Services for a link to download and install the Aternity iOS Wrapper.

    To install, extract the Aternity iOS Wrapper <version>.zip file into a folder to create an AternityWrapper sub-folder containing the wrapper tool.

  2. Step 2 Copy the tool's plist file (AternityWrapper/samples/sampleAternity.plist) to your own directory.

    The plist file defines the monitoring settings locally in the app, where each setting has a value.

  3. Step 3 Configure the monitoring settings in the plist file.

    You can edit its raw XML, or open it in any standard plist editor.

    Verify the settings in Aternity.plist
    Field Description
    Server (on-premise deployments only)

    For Aternity on-premise, specify the full address of the Aternity Aggregation Server, including its protocol (mandatory) and port (optional). For example, ""


    Use a DNS name for your Aggregation Server which can be resolved externally by Apple. The iOS Wrapper adds this address to Apple's white list of servers enabling unsecured connections, or secured connections from TLS 1.0 and above.

    We recommend you configure your Aggregation Server to support secured and encrypted connections.


    Set this value to YES for apps which report their location.

    (Aternity on-premise only) If the app connects to your Aggregation Server via a proxy server, enter the server name then the proxy server name in the following format:
    • AggSrv_IP_or_Name is the address of the Aggregation Server, after going via the proxy server.

    • Agg_port is the (optional) port number for accessing the Aggregation Server.

    • user and password represent the (optional) login required to gain access to your proxy server.

    • ProxySrv_IP_or_Name is the address of your proxy server.

    • Proxy_port is the (mandatory) port to access the proxy server. Use 80 for unsecured http, or 443 for a secured https access to the proxy server.

  4. Step 4 On a Mac with Xcode, Java and the wrapper tool installed, open a command shell.
  5. Step 5 To view a brief description of the Aternity Wrapper's parameters, type AternityWrapper/ -h
  6. Step 6 To activate the Aternity Wrapper, type the following:
    AternityWrapper/ -p profile.provision -l Aternity.plist input_app wrapped_app
    Field Description
    -p <filename>

    Use -p or --profile to sign the app using your own provisioning profile (the file you received from Apple).

    -l <filename>

    Use -l or --plist to add the configuration of Aternity's monitoring.

    For more information on configuring the server and account names in the monitor settings file, see (Configure Advanced Settings for Mobile App Monitoring).


    Use the filename of the unencrypted iOS app which you want to wrap. It must be in one of the following file types:

    • .ipa files

    • .mdx for Citrix XenStore packages

    • .xarchive for XCode archives of iOS applications


    Use the filename of the output app which is wrapped. Its file type must always be the same as the input_app.

    You can also add the following optional parameters:

    Field Description

    Use this parameter if your app is intended for upload to the official Apple App Store. These apps have slightly less monitoring capabilities because they conform to the store's rules.

    Apps uploaded to private enterprise app stores can track additional metrics such as the device's signal strength, or a stronger device ID.


    Use -ce or --copy-entitlements to create the wrapped app with the entitlements contained in your provisioning profile (not the original input app).


    If you are wrapping a third-party app (like WorkxMail), add -ce to copy your entitlements from your provisioning profile to the wrapped app.

    To copy all the entitlements but overwrite only those specified in your provisioning profile, use -ue or --update-entitlements.

    -s <signing ID>

    Use -s or --sign to add your signing identity. Use either the unique certificate name (as a string in quotes) or a certificate hash. For example -s "On iPhone: CompanyName Ltd."

    You must use this argument when the signing identity extracted from the provisioning profile matches more than one certificate in the Key Chain store. It is highly recommended though to always specify this argument in order to avoid ambiguous matching of signing identity.


    Use -f to allow the wrapper to overwrite the output file (if one exists).

    -e <file>

    Use the -e or --entitlements parameter to specify a .plist file containing a custom set of entitlements for the wrapped app. By default, if you do not use this parameter, the entitlements of the wrapped app are the same as those in the original app.

  7. Step 7 The system displays the result of the wrapping, like:
    Finished processing <wrapped app> successfully


Wrapping a standard .ipa app:

./AternityWrapper/ -l "./Aternity/Aternity.plist" -p ./myApp1/wildcardEntDist.mobileprovision -s "iPhone Distribution: My Company" ./myApp1/myApp1.ipa ./Aternity/myApp1-mon.ipa

To overwrite the output file, add the -f parameter.