Table of contents 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 login and its response, if those events are not automatically reported, insert an API to tag the login action, and add another API call to tag its response. When you report each tag to Aternity, the system 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.7 or later. Java Developer Kit JDK 1.8 or later. Programming environment Apple XCode 7. 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%. ProcedureStep 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. For API calls in a web page, add aternity_api.js in the web page. 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). 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 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 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) For Aternity SaaS, 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) 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. 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 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 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 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 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 Start Using the Aternity iOS SDK to Embed Monitoring in your iOS App. Include the Aternity header file in any code with an API call Parent topic Start Using the Aternity iOS SDK to Embed Monitoring in your iOS AppRelated tasks(Add Breadcrumbs to Troubleshoot Mobile App Crashes (leaveBreadcrumb())Related referenceInitialize the Aternity iOS Mobile SDK Manually (activateWithDictionary)Set the Username with the Aternity iOS Mobile SDK (userNameStr)Set the Location's Site Name with the Aternity iOS Mobile SDK (setSite and setOffSite)Tag an Event in an iOS App (tagApplicationWithName)Set Contextual Data to Report from an iOS App (setContextValue)Report a Tagged Event in an iOS App (reportTag) SavePDF Selected topic Selected topic and subtopics All content Related Links
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 login and its response, if those events are not automatically reported, insert an API to tag the login action, and add another API call to tag its response. When you report each tag to Aternity, the system 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.7 or later. Java Developer Kit JDK 1.8 or later. Programming environment Apple XCode 7. 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%. ProcedureStep 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. For API calls in a web page, add aternity_api.js in the web page. 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). 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 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 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) For Aternity SaaS, 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) 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. 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 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 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 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 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 Start Using the Aternity iOS SDK to Embed Monitoring in your iOS App. Include the Aternity header file in any code with an API call Parent topic Start Using the Aternity iOS SDK to Embed Monitoring in your iOS AppRelated tasks(Add Breadcrumbs to Troubleshoot Mobile App Crashes (leaveBreadcrumb())Related referenceInitialize the Aternity iOS Mobile SDK Manually (activateWithDictionary)Set the Username with the Aternity iOS Mobile SDK (userNameStr)Set the Location's Site Name with the Aternity iOS Mobile SDK (setSite and setOffSite)Tag an Event in an iOS App (tagApplicationWithName)Set Contextual Data to Report from an iOS App (setContextValue)Report a Tagged Event in an iOS App (reportTag)
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 login and its response, if those events are not automatically reported, insert an API to tag the login action, and add another API call to tag its response. When you report each tag to Aternity, the system 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.7 or later. Java Developer Kit JDK 1.8 or later. Programming environment Apple XCode 7. 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%. ProcedureStep 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. For API calls in a web page, add aternity_api.js in the web page. 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). 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 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 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) For Aternity SaaS, 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) 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. 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 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 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 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 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 Start Using the Aternity iOS SDK to Embed Monitoring in your iOS App. Include the Aternity header file in any code with an API call Parent topic Start Using the Aternity iOS SDK to Embed Monitoring in your iOS AppRelated tasks(Add Breadcrumbs to Troubleshoot Mobile App Crashes (leaveBreadcrumb())Related referenceInitialize the Aternity iOS Mobile SDK Manually (activateWithDictionary)Set the Username with the Aternity iOS Mobile SDK (userNameStr)Set the Location's Site Name with the Aternity iOS Mobile SDK (setSite and setOffSite)Tag an Event in an iOS App (tagApplicationWithName)Set Contextual Data to Report from an iOS App (setContextValue)Report a Tagged Event in an iOS App (reportTag)