iOS Agent Version 1.X

The embedded agent is a bridge between your mobile application and the App47 service. It provides an easy to use API for recording session times and durations, log messages and performance events. Once you've added your iOS App to the App47 Dashboard, be sure to record the App ID as it will be used to configure the agent after installation.

Download the iOS Embedded Agent, install and configure it in your iOS mobile App.

1. Download the embedded agent
2. Include embedded agent library in your project
3. Configure the embedded agent

• Add EmbeddedAgentSettings.plist file to set additional configuration parameters
• Sending Cached Data
• Add UncaughtException handler
• Add logging statements to capture both debug and error conditions
• Add timed events to capture performance data
• Add generic events to capture user behavior
• Using configuration groups

All of the above steps will be explained in the corresponding subsections below.

1. Download the embedded agent compressed disk image (DMG file) from: App47 Resource center
2. Once you have downloaded the file, open the DMG file and you should see the following files:

For version 1.9 or greater:For less than 1.9:

1. Create a folder in your project and copy the contents of the DMG file to the newly created folder

2. Add these files to your project by right clicking on the project, or on a folder of your choosing.

Note: Copy either the libEmbeddedAgent.a or libEmbeddedAgentWithNoCoreLocation.a to this directory.

3. Command-click on the app in which you are working and select Add Files to....

4. Select the App47 directory and click on the Add button.

Note: If you already use either the SBJSON or GoogleToolbox library in your application, do not include these directories.

There are several ways to include App47 into you iOS app, please make sure that you have selected only one option in each group below.

Select one of the libEmbeddedAgent libraries only, selecting more than one will cause compilation errors.

• libEmbeddedAgent.a - Use this if you are going through iTunes and want GEO data.
• libEmbeddedAgentEnterprise.a - Use this if you are deploying through App47's Enterprise App Store and want to use the security features with GEO data.
• libEmbeddedAgentWithNoCoreLocation.a - Use this if you are going through iTunes and do NOT want GEO data.
• libEmbeddedAgentEnterpriseWithNoCoreLocation.a - Use this if you are deploying through App47's Enterprise App Store and want to use the security features with NO GEO data.

1. Include either the JSON directory OR the libSBJSon.a file, but not both.
2. If you have an ARC project and using the JSON directory, make sure you exclude the files form the ARC compiler, please read this article on how to do exclude them.
3. If you are using the libSBJSon.a file, please include the -all_load flag in the linker flag.

1. Include either the GoogleToolbox directory OR the libGMStackTrace.a file, but not both.
2. If you have an ARC project and using the GoogleToolbox directory, make sure you exclude the files form the ARC compiler, please read this article on how to do exclude them.
3. If you are using the libGMStackTrace.a file, please include the -all_load flag in the linker flag.

The simplest way to configure the embedded agent is to include the EmbeddedAgent.h file and use the configureAgentWithAppID: selector with the App ID obtained from the App47 Dashboard. This configuration will record session start, duration, location and capture relevant device and App information.

#import "MyAppAppDelegate.h"

#import "MyAppViewController.h"
#import "EmbeddedAgent.h"
@implementation MyAppAppDelegate


@synthesize window=_window;

@synthesize viewController=_viewController;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // Override point for customization after application launch.
  [EmbeddedAgent configureAgentWithAppID:@"4d556ab4530a69fb4b000002"]; 
  self.window.rootViewController = self.viewController;
  [self.window makeKeyAndVisible];
    return YES;
}

The goal of the embedded agent is to provide a valuable management capability to your App without getting in the way of the App it is managing. Although nothing is free, we did try to limit the amount of resources we consume during the execution. Three key points were measure and the results are listed below.

The agent can also be configured with the included EmbeddedAgentSettings.plist file that includes the App ID as well as additional parameters for the embedded agent.

Configuration parameters

When using the EmbeddedAgentSettings.plist, the following configuration selector must be used.

#import "MyAppAppDelegate.h"

#import "MyAppViewController.h"
#import "EmbeddedAgent.h"
@implementation MyAppAppDelegate


@synthesize window=_window;

@synthesize viewController=_viewController;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // Override point for customization after application launch.
  [EmbeddedAgent configureAgent]; 
  self.window.rootViewController = self.viewController;
  [self.window makeKeyAndVisible];
    return YES;
}

The Embedded Agent can be configured to send data at the beginning of session, or at the end. However if you want to force the sending of any cached data, use the following command anywhere in your mobile app.

  [EmbeddedAgent sendCachedData];

If you want crash log information captured and send to the service, add the following handleUncaughException handler to your application delegate. This will capture any crash log information locally. The crash log information will then be uploaded the next time application is started.

void handleUncaughtException(NSException *exception) {
	EALogCrashException(exception, @"Application Crashed");
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // Override point for customization after application launch.
  [EmbeddedAgent configureAgent]; 
  NSSetUncaughtExceptionHandler(&handleUncaughtException);
  
  self.window.rootViewController = self.viewController;
  [self.window makeKeyAndVisible];
    return YES;
}

To capture all crash exceptions, use the InstallExceptionHandlers method to register default handlers for uncaught exceptions and signal handlers.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  // Override point for customization after application launch.
  [EmbeddedAgent configureAgent]; 
  [EmbeddedAgent InstallExceptionHandlers]; 
  
  self.window.rootViewController = self.viewController;
  [self.window makeKeyAndVisible];
    return YES;
}

Additional level logging can be added to your App to capture debug, info, warn, error and crash log information. Log information is recorded locally and then uploaded to the service the next time the application resumes the active state or is started. Examples of logging statements:

//
//  MyAppViewController.m
//  MyApp
//
//

#import "MyAppViewController.h"
#import "EmbeddedAgent.h"
@implementation MyAppViewController

- (void)dealloc
{
  [super dealloc];
}

- (void)didReceiveMemoryWarning
{
  // Warn level log statement 
  EALogWarn(@"Received memory warning");
  // Releases the view if it doesn't have a superview.
  [super didReceiveMemoryWarning];
  
  // Release any cached data, images, etc that aren't in use.
}

#pragma mark - View lifecycle

// Implement viewDidLoad to do additional setup after loading the view, typically from a nib.
- (void)viewDidLoad
{
  // List of tags can be added to log statements for additional 
  // search criteria in the web app.
  EALogInfoWithTags([NSArray arrayWithObject:@"MyTag"], @"View is being loaded");
  [super viewDidLoad];
}

- (void)viewDidUnload
{
  [super viewDidUnload===== Level 2 Headline =====
];
  // Release any retained subviews of the main view.
  // e.g. self.myOutlet = nil;
}

- (BOOL)shouldAutorotateToInterfaceOrientation:(UIInterfaceOrientation)interfaceOrientation
{
  // All log macros allow for standard string format replacements 
  // found in NSLog and stringWithFormat
  EALogDebug(@"View is being asked to rotate to interface orientation %d", interfaceOrientation);
  // Return YES for supported orientations
  return (interfaceOrientation == UIInterfaceOrientationPortrait);
}

@end

Timed events allow you to measure and record events in your application along with the duration of the event. Timed events are sent to the service immediately upon completion. If the agent is unable to send the event immediately, it is cached locally and then sent at the next App startup or activation. However, Timed Events are not written to disk. So if an application crashes, or is stopped, all cached time events are removed. A simple example of using timed events in your application would look like the following code:

- (void) performMyTransaction{
  NSString *eventID = [EmbeddedAgent startTimedEvent:@"Transaction"];
  // Perform some business logic to complete the transaction
  // …
  //
  [EmbeddedAgent endTimedEvent:eventID];
}

Timed events can be cleared before sending to the service using the clearTimedEvent: method or clear all events using the clearTimedEventsOlderThanTimeInterval: method.

- (void) performMyTransaction{
  BOOL successful = NO;
  NSString *eventID = [EmbeddedAgent startTimedEvent:@"Transaction"];
  // Perform some business logic to complete the transaction
  // …
  //
  if (successful)
    [EmbeddedAgent endTimedEvent:eventID];
  else
    [EmbeddedAgent clearTimedEvent:eventID];
}

… OR …

- (void) clearAllTimedEvents {
  [EmbeddedAgent clearTimedEventsOlderThanTimeInterval:0];
}

Generic Events are like Timed Events, but with no duration. Generic Events are sent to the service immediately upon request. If the agent is unable to send the event immediately, it is cached locally and then sent at the next App startup or activation. A simple example of using Generic Events in your application would look like the following code:

- (void) handleMyEvent{
  [EmbeddedAgent sendGenericEvent:@"myEventName"];
  // Perform some business logic to handle the event
  // …
  //

}

Configuration Groups allows you to set a collection of key value pairs through the main web interface that are then downloaded by the agent at initial startup, and then subsequently at a frequency set by the “configuration update frequency” parameter in the EmbeddedAgentSettings.plist file. Configuration items must be requested by group name and key name. A default value may be given to be used in the event that the configuration group does not contain an item with the requested key name. If a default value is not given, and the key does not exist in the group, the value nil is returned. Configuration groups can be assigned to agents based on app version, os version and platform.

A simple example of using Configuration Groups in your application would look like the following code:

(void) myMethod{

  NSString *serverURLString = [EmbeddedAgent configurationStringForKey:@"server url" 
                                                                 group:@”Server Info” 
                                                          defaultValue:@”http://myserver.abc.com/restapi”];

  // Use the serverURLString to perform additional work...
  // …
  //

}

The Embedded Agent will send notifications using NSNotificationCenter when new configuration settings are received from the service. The following messages are sent when the configuration change are received.

(void) updateViewFromConfigurationChange:(NSNotification *) notification{
	NSDictionary *userInfo = [notification userInfo];
  NSString *groupName = [[userInfo valueForKey:EmbeddedAgentAppConfigurationGroupNameKey]];
  //
  // Update view based on groupName
  // ...
}

(void) viewDidLoad{

  [[NSNotificationCenter defaultCenter] addObserver:self 
                                           selector:@selector(updateViewFromConfigurationChange:) 
                                               name:EmbeddedAgentAppConfigurationGroupDidUpdate 
                                             object:nil];

	[super viewDidLoad];

}

The Embedded Agent can be configured to send data at the beginning of session, or at the end. However if you want to force the sending of any cached data, use the following command anywhere in your mobile app.

  [EmbeddedAgent sendCachedData];

• Fixed issue with sending events right away.

• Added “capture crashes” option to configuration parameter.

• Removed SBJson from project, it is no longer required.

• Removed support for arvm6 and added arvm7s, arvm7 is still included.
• Added “sendCachedData” command which will force the sending of cached data.

• Extended the time out for all requests.
• Added retries when fetching configuration groups to address issues with spotty connections.

• Fixed bug with empty configuration groups as it was causing a crash.

• Fixed bug with security policy, if the network is disabled, the security policy wasn't being applied. Bug fixed.
• Fixed bug when clearing timed events.

• Added the ability to configure agent settings (as in EmbeddedAgentSettings.plist) programatically.

• Fixed an issue uploading crash logs to server.
• Fixed an issue on the Upload on exit feature.

• Enabled the agent to be reconfigured on the fly without a restart.

• Added new method to agent to retrieve all the keys and values for a configuration group in one call, see EmbeddedAgent.h file for more information on method configurationGroupAsDictionary:.

• Fixed issue with configuration parameter configuration update frequency; the calculation was not correct.

• Updated agent version number, 1.7.2 as it was reporting as version 1.7.1.

• Updated Google Toolkit files to work nicely with iOS 6, please update ALL files contained in the Google Toolbox directory.
• Updated the behavior of the version enforcement feature to only work on the device, not while running in the simulator.

• Fixed agent logging messages to only appear when running in the simulator.

• Added app version management feature that enforces the user to run the active version. This is configured at the server level.
• Added “upload on exit” feature that uploads session, log, and event data when the app is backgrounded.

• Fixed encoding issue with API server when sending XML documents as part of a log message.

• Timed events were not being sent with the option send events immediately was set to NO. Fixed.

• Print out agent version number if logging level is agent set to debug.
• Added configuration parameter to support sending generic and timed events either immediately, as they have always been, or batched up and sent along with log and session data. The default behavior is to send the event data immediately.

• Improved duration calculation.
• Fixed memory leak reported by Instruments 4.3.1 that had not been seen before.

• Added defensive coding for real time endpoints, if none are returned by the configuration endpoint, or the agent hasn't registered yet. The agent will first try the configuration endpoint.

• Added defensive coding around key methods in the agent to ensure any failures do not crash the app.
• Added new parameter in configuration to control the agent logging level. This will only send log messages to the console when running in the simulator.
• Separated the libraries for enterprise and non enterprise builds. Non enterprise builds no longer have the call to obtain the UDID [[UIDevice currentDevice] deviceIdentifier] which has been deprecated and will eventually not be allowed through iTunes review process.

• Added internal logging capability for the Agent. Instead of the agent logging to the console, it will send any agent errors or issues to the App47 service for diagnostics.
• Updated the default production endpoint to use the app47 domain.
• Changed the duration calculation for timed events to use the phone's relative time for start and end instead of the adjusted time for the event. This was causing negative durations due to the offset getting changed between the start of the event and the end.

• Added [EmbeddedAgent InstallUncaughtExceptionHandler], which registers crash and signal handlers for your app and sends crash logs if any signals are received.
• Added the ability to clear out timed events by either ID, or NSTimeInterval.

• Added Armv6 library back into the build for all *.a files.
• Fixed issue for configuration items not updating when the file changes, but the name does not.