Integrate the Aternity iOS SDK into your App

Use the Aternity iOS SDK to integrate Aternity functionality into your app, to monitor events, errors and launch times automatically, or you can also optionally add your own API calls for even more fine-tuned monitoring.

The Aternity iOS SDK is a set of files which you add to your development environment. Integrating the Aternity iOS SDK only requires adding a header file, a library file, some core frameworks, and then rebuilding your app.

Embed monitoring to an iOS app using the Aternity iOS Mobile SDK

Without adding your APIs, the end result is similar to wrapping the app with the Aternity iOS Wrapper, but with the iOS Wrapper you do not need any access to the source code. If you add APIs, you can fine-tune your monitoring.

If you want to add further API calls, you must first integrate the Aternity iOS SDK as a prerequisite. 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. A custom activity for mobile apps starts and ends when the app reports specific events which match the events of an activity's signature file. If Aternity already reports these events by default, you do not need to add manual API calls. However, for some custom activities, you must manually tag and report those events using API calls.

For example, to measure the response time between the start of a sign in and its response, if those events are not automatically reported, insert an API to tag the sign in action, and add another API call to tag its response. When you report each tag to Aternity, it matches them to the custom activity already in place, and then reports the response time in the dashboards. To create your own custom activities, contact Customer Services.

The instructions in this section use Apple Xcode as an example.

Before you begin

Ensure your app compiles and builds cleanly with no errors, and runs on a simulator or a mobile device.

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

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

Attribute Requirement

iOS operating system of monitored device

iOS 9 or later.

Procedure

  1. Step 1 Contact Customer Services to download the Aternity iOS Mobile SDK.
    Contents of the Aternity iOS Mobile SDK

    The Aternity iOS SDK includes the following files:

    File Description
    Aternity.h

    The header file which links your source code to the Aternity iOS SDK library.

    Aternity.plist

    The configuration file which defines the monitoring settings locally in the app, and initializes the Aternity iOS SDK together with the app initialization.

    libAternitySDK.a

    (Aternity iOS SDK v9.3 onwards) The libAternitySDK library file contains the Aternity functionality.

    (Aternity iOS SDK v9.2 or earlier) There are two flavors of the libAternitySDK library file:

    • libAternitySDK_PublicAppStore.a (v9.1 or 9.2 only) is for apps uploaded to the official Apple App Store. These apps have slightly less monitoring capabilities because they conform to the rules of the public app store.

    • libAternitySDK_PrivateAppStore.a (v9.1 or 9.2 only) is for apps uploaded to an enterprise's private app store. These apps can track additional metrics such as the device's signal strength, and the actual hardware device ID (rather than the vendor ID).

  2. Step 2 Add the required files to your Xcode project:

    Add the header file Aternity.h, the configuration file Aternity.plist, and the correct library file:

    • (Aternity iOS SDK v9.3 onwards) libAternitySDK.a

    • (Aternity iOS SDK v9.2 or earlier) libAternitySDK_PrivateAppStore.a or libAternitySDK_PublicAppStore.a depending on whether you distribute this app through a private app store or the official Apple App Store.

    Tip

    Adding the plist file to the project initializes the Aternity iOS SDK functionality when you launch the app. If you want finer control of the initialization of the Aternity iOS SDK, for example, only when you enter a specific screen, you can manually initialize it using API calls (see Initialize the Aternity iOS Mobile SDK Manually (activateWithDictionary)).

    Ensure the Destination field is set to Copy items if needed.

    Add the header, plist and library to your Xcode project
  3. Step 3 Ensure all the Aternity library's methods and classes are preserved by adding a flag in the Build Settings.

    Select the Build Settings tab, search for the Other Linker Flags field, and add either -ObjC to load all libraries, or -force_load <library_pathname> to load a specific library.

    Link the library to the project
  4. Step 4 Verify the Aternity.plist settings file contains the values you need to report monitoring activity to Aternity.

    Select Aternity.plist from the sidebar of Xcode, and verify the following settings:

    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.

    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, "https://aggserver.company.com:443"

    Note

    Typically, you secure the connection to the Aggregation Server with https. If you are temporarily testing with the unsecured http protocol, you must add an extra property to your Xcode project.

    In the Info tab, in Custom iOS Target Properties and add a new entry: Set App Transport Security Settings, and within it, add another entry: Allow Arbitrary Loads, and set its value to YES. This allows the app to communicate to another server using unsecured http.

    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 Add the core frameworks which are required when using the Aternity library.

    Select the Build Phases tab, and open the Link Binary With Libraries section.

    Select + to add the following libraries (if they were not already added by default):

    • CFNetwork

    • CoreFoundation

    • CoreGraphics

    • CoreLocation

    • CoreTelephony

    • Foundation

    • libxml2

    • libz

    • Security

    • SystemConfiguration

    • UIKit

    • WebKit

    Add the frameworks which support the Aternity library
  6. Step 6 Verify the library file appears in the same list of linked libraries.

    If you added the Aternity.plist to the project for automatic initialization when the app starts, verify this file also appears in the Copy Bundle Resources section immediately under the list of frameworks.

    Verify added files are linked and copied
  7. Step 7 Build the app and run it in the simulator.

    Open the debug area of Xcode, and look for the message SDK successfully connected to the Aternity server.

    View the connection message
  8. Step 8 Within a few minutes, you can see the device in Aternity.

    Select the device icon in the top bar to open the Device Inventory dashboard. Select the Smartphone circle in the Device Types section and view the simulator there.

    Verify the details of the device in the Device Inventory dashboard
  9. Step 9 Include the Aternity.h header file (in Objective-C) into your source code file. To add it to a Swift project, use a bridging header (see Apple's documentation).

    For more information on the available API calls for adding monitoring functionality, see Embed Monitoring in your iOS App with the Aternity iOS SDK.

    Include the Aternity header file in any code with an API call