Initialize the Aternity iOS Mobile SDK Manually (activateWithDictionary)

To use the API calls of Aternity iOS Mobile SDK, you must first initialize it. You can activate it either automatically when the app launches, by adding Aternity.plist to your development project, or initialize it explicitly by calling activateWithDictionary in the Aternity iOS SDK.

For example, you might want to explicitly activate the Mobile SDK after the UI of your app has loaded, so you can configure its settings dynamically and start the data reporting to Aternity without delaying the UI.

Note

In this example, if you delay the initialization of the Mobile SDK, it would impact on the app's reported launch times.

If you have an Android app, use the Aternity Android SDK's init method.

The Aternity class provides the sharedManager method, which returns a singleton object. You should call the class's methods using this singleton object, to avoid manually creating and maintaining the Aternity object.

To initialize the Aternity iOS SDK with specific settings, first prepare a dictionary containing those settings, and then pass it to activateWithDictionary using the singleton.

For example, in Objective-C:

[[Aternity sharedManager] activateWithDictionary:name_of_dictionary];

In Swift:

Aternity.sharedManager().activateWithDictionary(name_of_dictionary)
Initialize the Mobile SDK

For backward compatibility only, the API also maintains an initialization with five prescribed arguments: initWithServerAddr in Objective-C, or activateWithServerAddr in Swift, and initWithDictionary in Objective-C only which is identical to activateWithDictionary. For more information on these legacy methods, see the API documentation from previous versions.

Before You Begin

Before you begin, verify you have performed the following tasks:

  • Integrate the Aternity iOS Mobile SDK into your app development environment.

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

  • 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).

Method Definition

-(void) activateWithDictionary:(NSDictionary *)config;

This method accepts a single dictionary object (of type NSDictionary) whose key-value pairs define the configuration of the Mobile SDK.

Define the dictionary's values using the predefined keys in the header file. For example:

[dictionary_name setObject:@"value" forKey:KEYNAME];
Note

You can set most of the configuration settings centrally in Aternity, and update them without requiring you to distribute an updated version of the app. We therefore recommend to define the settings which define the app usage locally on the device side: username, device name, location site name. You also need to specify your company's account key (for Aternity SaaS deployments) or Aternity Aggregation Server address (for on-premise deployments) so you can access your data reported to Aternity.

The most common key names are as follows:

Parameter Type Description

ATERNITY_CONFIG_ACCOUNT_KEY (Aternity SaaS only)

String

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

ATERNITY_CONFIG_USER_NAME

String

(Optional) Specify the user name to be displayed in the Aternity dashboards for this monitored session. Alternatively, use userNameStr to define the username separately.

ATERNITY_CONFIG_USE_LOCATION

Bool

(Optional) Specify YES or NO to determine if the app collects and reports the location of the device.

ATERNITY_CONFIG_DEVICE_NAME

String

(Optional) Specify the name of the mobile device to appear in the Aternity dashboards for this monitored session. Alternatively, use setDeviceName to define the name of the device separately.

ATERNITY_CONFIG_SITE

String

(Optional) Specify the name of the business location to be displayed in the dashboards. This overrides any geo-location information reported by the device. Alternatively, use setSite to define the name of the device separately.

ATERNITY_CONFIG_HTTP_FILTERS

JSON

(Optional) Use this key to regulate the reporting of URLs which the device visited, by defining regex patterns in double quotes as follows:

  • To report all URLs without their parameters, remove this key completely from the dictionary. This is the default behavior.

    For example, to report http://xyz.com/a/main.html?prod=p&ver=v without its parameters (http://xyz.com/a/main.html), do not add ATERNITY_CONFIG_HTTP_FILTERS to the dictionary.

  • To report only specific URLs while excluding all others, add only their regex patterns to INCLUDE_URLS.

    For example, to report only URLs containing yahoo or cnn, define the key as [config setObject:@"{\"INCLUDE_URLS\":[{\".*yahoo.*\",\".*cnn.*\"}]}" forKey:ATERNITY_CONFIG_HTTP_FILTERS];

  • To report some URLs along with their parameters, while reporting the rest without parameters, add those with parameters with a value of true, while those without their parameters should have the value false.

    For example, to report all google URLs together with their parameters, while all others are without parameters, define the key as [config setObject:@"{\"INCLUDE_URLS\":[{\".*google.*\":\"true\"},{\".*\":\"false\"}]}" forKey:ATERNITY_CONFIG_HTTP_FILTERS];

  • To exclude (not report) specific URLs from reporting, add their regex patterns to EXCLUDE_URLS. For example, to exclude all yahoo and cnn URLs, define this key as [config setObject:@"{\"EXCLUDE_URLS\":[\".*yahoo.*\",\".*cnn.*\"]}" forKey:ATERNITY_CONFIG_HTTP_FILTERS]

Important

If you define this key without any rules, it excludes (filters) all URLs.

For a complete list of configuration settings, see (Configure Advanced Settings for Mobile App Monitoring).

Example

The following is an example in Objective-C to initialize the Aternity iOS SDK using activateWithDictionary, where the dictionary defines the following keys:

  • The address of the Aternity Aggregation Server

  • Enable crash monitoring

  • Disable HTTP monitoring for UIWebView

  • Limits HTTP reporting to omit reporting anything with apple or yahoo in the URL, but all URLs containing google are reported together with their parameters.


//Define a dictionary called 'config'
NSMutableDictionary* config = [NSMutableDictionary dictionary];

//Set address of the Aternity Aggregation Server (on-premise deployments only)
[config setObject:@"https://my_server:60080" forKey:ATERNITY_CONFIG_SERVER];
//Set account key for your company in Aternity (SaaS deployments only)
[config setObject:@"123456ABCD" forKey:ATERNITY_CONFIG_ACCOUNT_KEY];

//Enable location services
[config setObject:[NSNumber numberWithBool:YES] forKey:ATERNITY_CONFIG_USE_LOCATION];

//Set HTTP Filters using regex. Exclude any URL containing 'apple' or 'yahoo'. All others are
//reported without parameters, except URLs containing 'google', whose reports do include parameters
[config setObject:@"{\"INCLUDE_URLS\":[{\".*google.*\":\"true\"},{\".*\":\"false\"}],
                 \"EXCLUDE_URLS\":[\".*yahoo.*\",\".*apple.*\"]}" forKey:ATERNITY_CONFIG_HTTP_FILTERS];

// Enable crash monitoring (enabled by default)
[config setObject:[NSNumber numberWithBool:YES] forKey:ATERNITY_CONFIG_MONITOR_CRASH];

// Disable error monitoring
[config setObject:[NSNumber numberWithBool:NO] forKey:ATERNITY_CONFIG_MONITOR_ERRORS];

//Initialize the SDK with the dictionary entries defined above
[[Aternity sharedManager] activateWithDictionary:config];

Below is Swift example to initialize the Aternity iOS SDK using activateWithDictionary, where the dictionary defines the following keys:

  • The address of the Aternity Aggregation Server

  • The level of detail in the log

  • The application name

  • Enable location services.


// Define a dictionary called 'config' 
var config = Dictionary<String, AnyObject>()  

// Set address of the Aternity Aggregation Server for on-premise 
config[ATERNITY_CONFIG_SERVER] = "https://my_server:60080"
//Set account key for your company in Aternity SaaS
config[ATERNITY_CONFIG_ACCOUNT_KEY] = "123456ABCD" 

// Set the level of detail in the log file on the device 
config[ATERNITY_CONFIG_LOG_LEVEL] = 4 
config[ATERNITY_CONFIG_MAX_LOG_SIZE] = 10*1024*1024 

//Set HTTP Filters using regex. Exclude any URL containing 'apple' or 'yahoo'. All others are
//reported without parameters, except URLs containing 'google', whose reports do include parameters
config[ATERNITY_CONFIG_HTTP_FILTERS] = "{\"INCLUDE_URLS\":[{\".*google.*\":\"true\"},{\".*\":\"false\"}],
                          \"EXCLUDE_URLS\":[\".*yahoo.*\",\".*apple.*\"]}"

// Enable location services 
config[ATERNITY_CONFIG_USE_LOCATION] = true 

//Initialize the SDK with the dictionary entries defined above
Aternity.sharedManager().activateWithDictionary(config)