iOS Agent Version 2.X

This page supports the iOS agent prior to version 4.0. If you are still using this version, please upgrade as soon as possible. This version is no longer updated.

Introduction

iOS Agent Version 2

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

Note: If you are using a version prior to 2.0, please consult the legacy page for additional information. Please upgrade at your earliest convenience to the latest iOS agent.

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

• Add EmbeddedAgentSettings.plist file to set additional configuration parameters
• Sending Cached Data
• Add Crash Log Management
• Add logging statements to capture both debug and error conditions
• Adding timed events to your App (to capture performance data)
• Adding generic events to your App (to capture user behavior)
• Using configuration groups

All of the above steps are explained in the corresponding subsections below.

Embedded Agent Performance

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

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. Select the App47 directory and click Add.

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.
• libEmbeddedAgentWithNoCoreLocation.a - Use this if you are going through iTunes and do NOT want GEO data.

Include either the GoogleToolbox directory OR the libGMStackTrace.a file, but not both.

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.

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 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];

There are three ways to capture crash log information for your iOS application, please choose one of the methods below, do not implement multiple methods within the sam application.

If you want crash log information captured and send to the App47 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. This will use the Google Toolkit Method of capturing crash logs.

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. This is the same as setting “GTM” as the “capture crash format” in the EmbeddedAgentSettings.plist file.

- (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;
}

To capture the crash log in the iOS crash log format, and have it symbolicated by the service. Configure the EmbeddedAgentSettings.plist file with the setting “capture crash format” ⇒ “symbolicate”.

This will use the PL Crash Reporter Library to capture the crash locally on the device. The crash log will be uploaded to the server the next time the application is started. It does not prompt the user to upload the crash log.

If your crash log is not fully symbolicated, please see our iOS symbolication trouble shooting guide.

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];

}

• Fixed bug MAM-128 to remove white spaces from the EmbeddedAgentSettings.plist file before using any values.

• Added iOS crash log symbolication capability

• Fixed bug when the agent was reporting app version number. Please upgrade as soon as possible if you are using 2.1 or 2.2.

• Changed the way devices are unique identified to comply with Apple APIs, now the same library works for both Enterprise and B2C customers without any issues.