Methods

This section contains a list of the methods provided by the Mac OS X library.

Shared Instance

Before making measurement calls, you must retrieve the singleton instance of the library for each method you call on the measurement library:

ADMS_Measurement *measure = [ADMS_Measurement sharedInstance];

Initial Configuration

This method configures the required variables and must be called before other methods.

Configuration Methods

Description

configureMeasurementWithReportSuiteIDs

This method is used to configure the two parameters required to start application measurement. You must set the reportSuiteIDs and trackingServer values on the measurement object using this method prior to sending any server calls.

Syntax:

- (void)configureMeasurementWithReportSuiteIDs:(NSString *)reportSuiteIDs 
trackingServer:(NSString *)trackingServer;

Examples:

[measure configureMeasurementWithReportSuiteIDs:TRACKING_RSID trackingServer:TRACKING_SERVER];

Auto Tracking Configuration

Configuration Methods

Description

setAutoTrackingOptions

By default, lifecycle events (launches, daily and monthly users, and so on) are tracked automatically.

- (void)setAutoTrackingOptions:(ADMS_AutoTrackOptions)options;

Set options using the following values:

ADMS_AutoTrackOptionsNone = 0, 			///< Disable all auto tracking
	ADMS_AutoTrackOptionsLifecycle = 1		///< Track application lifecycle
 

To enable automatic lifecycle event tracking:

[measure setAutoTrackingOptions:ADMS_AutoTrackOptionsLifecycle];

To disable all automatic event tracking:

[measure setAutoTrackingOptions:ADMS_AutoTrackOptionsNone];

Event and State Tracking

These are the primary methods used to track custom events and app states.

Method

Description

trackAppState

This is the recommended way to track application states (for example, pages) in your application. The value provided in appState appears as the page name variable of the server call. The appState string must be provided for each call since it isn't carried over to the next call.

Context data sent with this call is appended to any values in persistentContextData and sent with the call. Only values set in persistentContextData remain for the next call.

If you are using auto track, this method is called automatically each time a new view controller loads. To pass additional data with these auto track calls, you must set persistentContextData on the measurement object in the viewDidLoad method of your UIViewController instance.

Syntax:

- (void)trackAppState:(NSString *)appState;
- (void)trackAppState:(NSString *)appState 
    withContextData:(NSDictionary *)contextData;

Examples:

[measure trackAppState:@"state name"];
NSMutableDictionary *contextData = [NSMutableDictionary dictionary];
[contextData setObject:@"value" forKey:@"custom key"];
//add additional key:value pairs to this dictionary...

[measure trackAppState:@"state name" withContextData:contextData];

trackEvents

This is the recommended way to track events in your application. trackEvents is similar to trackAppState, but sends events instead of page names. Events are provided as a comma delimited string. The events string must be provided for each call since it isn't carried over to the next call.

This method make an underlying call to trackLinkURL where linkURL is set to nil, linkType is set to "o", and the linkName is populated with the application ID.

This means that your linkTrackVars and linkTrackEvents apply for calls to trackEvents.

Context data sent with this call is appended to any values in persistentContextData and sent with the call. Only values set in persistentContextData remain for the next call.

Syntax:

- (void)trackAppState:(NSString *)eventNames;
- (void)trackAppState:(NSString *)eventNames 
 withContextData:(NSDictionary *)contextData;

Examples:

NSMutableDictionary *contextData = [NSMutableDictionary dictionary];
[contextData setObject:@"value" forKey:@"custom key"];  
//add additional key:value pairs to this dictionary...

[measure trackEvents:@"event1, event2" withContextData:contextData];

Import note if you are using the trackLink method

trackEvents makes an underlying call to trackLinkURL, where linkURL is set to nil, linkType is set to "o", and the linkName is populated with the application ID. This is done to prevent the page view (state view) count from being incremented each time you track events.

If you are calling trackLinkURL directly and setting values for linkTrackVars and linkTrackEvents, these variable and event restrictions apply to TrackEvents. This means that only variables and events defined on these lists are sent with TrackEvents. You should set linkTrackVars and linkTrackEvents to nil unless you want those restrictions applied to trackEvents.

Advanced Tracking (track and trackLink)

These methods provide additional tracking options, allowing you to populate props, eVars, and other SiteCatalyst variables directly. These should be used by customers with an existing implementation or customers who are very familiar with other SiteCatalyst implementations.

track and trackLink are the core measurement methods that are implemented in all versions of the Adobe Measurement Libraries across multiple platforms. In most circumstances when tracking mobile applications, it is easier to use trackAppState, trackEvents methods rather than calling track and trackLink directly.

Page view tracking (track) and link tracking (trackLink) sends all persistent variables that have values (non-nil, non-empty, non-zero). You should reset or empty all variables, as needed, before calling track or trackLink.

Note: Due to the multi-threaded nature of modern applications, setting persistent variable values to send with a future tracking call is not recommended (using setEvar, setProp, setHier, setListVar, and the persistentContextData variable) . For example, if a variable value is set in multiple threads, the value might be in an inconsistent state when the tracking call is made. To avoid this, we recommend passing context data with each tracking call and setting the variable value in Processing Rules.

Method

Description

track

trackWithContextData

Sends a standard page view, along with any additional variables that are set on the measurement object, to the collection server.

Each call to track sends all persistent data defined on the measurement object (these are listed in the description for clearVars), plus any contextData or variables you provide for that call only. If you send a variable that is defined, any value in the corresponding persistent variable is overwritten.

Syntax:

- (void)track;
- (void)trackWithContextData:(NSDictionary *)contextData;
- (void)trackWithContextData:(NSDictionary *)contextData 
				   variables:(NSDictionary *)variables;

Examples:

[measure track];
//set an eVar
[measure setEvar:1 toValue:@"evar1value"]; 
//contextData
NSMutableDictionary *contextData = [NSMutableDictionary dictionary]; 
[contextData setObject:@"value" forKey:@"custom key"]; 
[measure trackWithContextData:contextData];
//variable overrides 
NSMutableDictionary *variableOverrides = [NSMutableDictionary dictionary]; 
[variableOverrides setObject:@"evar2Value" forKey:@"eVar2"];
[measure trackWithContextData:contextData variables:variableOverrides];

trackLinkURL

Sends custom, download or exit link data to Adobe data collection servers, along with any track config variables that have values.

Use trackLink to track all activity that should not capture a page view.

Syntax:

- (void)trackAppStatetrackLinkURL:(NSString *)linkURL 
	    	withLinkType:(NSString *)linkType
	       		linkName:(NSString *)linkName
	      contextData:(NSDictionary *)contextData 
		       variables:(NSDictionary *)variables;

linkURL: Identifies the clicked URL. If no URL is specified, the name is used. Use this only when linking to a Web page from within your Mac OS X application. Otherwise, pass in nil for this parameter.

linkType: Identifies the link report that will display the URL or name. Supported values include:

  • “o” (Custom Links)
  • “d” (File Downloads)
  • “e” (Exit Links)

linkName: The name that appears in the link report. If no name is specified, the report uses the URL.

To collect data, you must specify either the linkURL, or linkName parameter. When not using one of these parameters, context data, or additional variables, pass in nil as the value.

NSMutableDictionary *contextData = [NSMutableDictionary dictionary];
[contextData setObject:@"value" forKey:@"custom key"];
       
NSMutableDictionary *variables = [NSMutableDictionary dictionary];
[variables setObject:@"eVar1Value" forKey:@"eVar1"];
[variables setObject:@"prop50Value" forKey:@"prop50"];

[measure trackLinkURL:@"linkURL" withLinkType:@"o" linkName:@"linkName" contextData:contextData variables:variables];

setEvar

Sets the specified eVar to the provided value. The eVar is sent with the next tracking call.

Syntax:

- (void)setEvar:(NSUInteger)evarNum toValue:(NSString *)value;

Examples:

ADMS_Measurement *measure = [ADMS_Measurement getInstance];
[measure setEvar:1 toValue:@"value"];

setProp

Sets the specified prop to the provided value. The prop is sent with next tracking call.

Syntax:

- (void)setProp:(NSUInteger)propNum toValue:(NSString *)value;

Examples:

ADMS_Measurement *measure = [ADMS_Measurement getInstance];
[measure setProp:1 toValue:@"value"];

setHier

Sets the specified hier variable to the provided value. The variable is sent with next tracking call.

Syntax:

- (void)setHier:(NSUInteger)hierNum toValue:(NSString *)value;

Examples:

ADMS_Measurement *measure = [ADMS_Measurement getInstance];
[measure setHeir:1 toValue:@"value"];

setListVar

Sets the specified listvar to the provided value. The listvar is sent with next tracking call.

Syntax:

- (void)setListVar:(NSUInteger)listNum toValue:(NSString *)value;

Examples:

ADMS_Measurement *measure = [ADMS_Measurement getInstance];
[measure setListVar:1 toValue:@"value"];

setPersistentContextData

Values placed in Persistent Context Data are sent with each server call. To send context data for a single call, send a contextData hashtable as a parameter to the tracking call (trackAppState, trackEvents, and so on).

Hashtable contextData = new Hashtable<String, Object>();
contextData.put("key", "value"); 
       
measure.setPersistentContextData(contextData);
      

See Context Data.

clearVars

Removes values from the following variables on the object:

evars
props
listvars
hiers
events
purchaseID
transactionID
appState
channel
appSection
campaign
products
persistentContextData
geoState
geoZip
linkTrackVars
linkTrackEvents

Syntax:

- (void)clearVars;

Examples:

[measure clearVars];

Offline Tracking Reference

Note: To enable offline AppMeasurement, your report suite must be timestamp-enabled.

The following variables let you store measurement calls when the application is offline. After you enable offline tracking, all hits must be time-stamped or they are dropped. If you are currently reporting AppMeasurement data to a report suite that also collects data from JavaScript, you might need to set up a separate report suite for Offline AppMeasurement to avoid data loss.

When enabled, Offline AppMeasurement behaves in the following way:

  • The application sends a server call, but the data transmission fails.
  • AppMeasurement generates a timestamp for the current hit.
  • AppMeasurement buffers the hit data, and backs up buffered hit data to persistent storage to prevent data loss.

At each subsequent hit, or at the interval defined by offlineThrottleDelay, AppMeasurement attempts to send the buffered hit data, maintaining the original hit order. If the data transmission fails, it continues to buffer the hit data (This continues while the device is offline).

Property or Method Description

offlineTrackingEnabled

Default: NO

Enables or disables offline tracking for the measurement library.

Syntax:

BOOL offlineTrackingEnabled;

Examples:

measure.offlineTrackingEnabled = YES;

offlineHitLimit

Default: 1000

Maximum number of offline hits stored in the queue. If the hit limit is set over 5000, performance may suffer.

Syntax:

NSUInteger offlineHitLimit;

Examples:

 measure.offlineHitLimit = 2000;

trackingQueueSize

Returns the number of stored tracking calls in the offline queue.

Syntax:

- (NSUInteger)trackingQueueSize;

Examples:

[measure trackingQueueSize];

clearTrackingQueue

Removes all stored tracking calls from the offline queue.

Syntax:

- (void)clearTrackingQueue;

Examples:

[measure clearTrackingQueue];

Warning: use caution when clearing the queue manually as it cannot be reversed.

setOnline

setOffline

Manually set the online or offline state of the measurement object. The library automatically detects when the device is offline or online, so these methods are needed only if you want to force measurement offline. setOnline is used only to return to the online state after manually going offline.

When measurement is offline:

  • If offlineTrackingEnabled is true: hits are stored until measurement is online.
  • If offlineTrackingEnabled is false: hits are discarded.

Syntax:

- (void)setOnline;
(void)setOffline;

Examples:

[measure setOffline];
[measure setOnline];