Embed Monitoring in an iOS App with the iOS Wrapper

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 Start Embedding 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.10 or later.

Programming environment

Apple XCode 7 or newer.

Connectivity

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%.

Java Developer Kit

JDK 1.8 or later (iOS Wrapper only)

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

  • To run a monitored app, the device must have the following operating systems:

    Attribute Requirement

    iOS operating system of monitored device

    iOS 10 or later.

    Android operating system of monitored device

    Android 4.4 or later.

  • 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 developer.apple.com 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.

Procedure

  1. Step 1 Download Aternity Mobile by selecting the Gear Icon > Agent Download.

    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.

    Select the embedding tool for your mobile operating system.

    Download Aternity Mobile
    Field Description
    Wrapper for iOS / Wrapper for Android

    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.

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

    SDK for Android / SDK for iOS

    With the Mobile SDK you can insert API calls to fine-tune the monitoring, by dynamically setting properties (like the device name, location), or tag events for use in some types of custom activities, or you can use APIs to report breadcrumbs for later troubleshooting of crashes.

  2. Step 2 Extract the zip file to view the AternityWrapper folder containing the wrapper tool.
  3. Step 3 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.

  4. Step 4 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
    AccountKey (Aternity SaaS deployments only)

    (Aternity SaaS only) This value is the account ID for your company, which you received from Customer Services.

    UseLocation

    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:
    http[s]://AggSrv_IP_or_Name[:Agg_port],[user]:[password]@ProxySrv_IP_or_Name:Proxy_port
    • 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) sign in 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.

  5. Step 5 On a Mac with Xcode, Java and the wrapper tool installed, open a command shell.
  6. Step 6 To view a brief description of the Aternity Wrapper's parameters, type AternityWrapper/wrapper.sh -h
  7. Step 7 To activate the Aternity Wrapper, type the following:
    AternityWrapper/wrapper.sh -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).

    input_app

    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

    wrapped_app

    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
    -appstore

    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.

    -ce

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

    Note

    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.

    -f

    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.

  8. Step 8 View the result of the wrapping, like:
    Finished processing <wrapped app> successfully

Example

Wrapping a standard .ipa app:

./AternityWrapper/wrapper.sh -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.