Inherits from NSObject
Declared in EQATECAnalyticsMonitor.h

Overview

The main interface for the analytics monitor which can be obtained with a call to monitorWithProductId:version: or monitorWithSettings:. The monitor will not collect data before a call to start has been performed.

For more on the features of the Analytics service please refer to the Analytics website.

DocSet documentation is available at these URLs: http://api.eqatec.com/analytics/ios/docset/EQATECAnalyticsMonitoriOS.atom http://api.eqatec.com/analytics/macos/docset/EQATECAnalyticsMonitorMacOS.atom

Properties

status

Access the current status for the monitor.

@property (readonly) EQATECAnalyticsMonitorStatus *status

Declared In

EQATECAnalyticsMonitor.h

Class Methods

monitorWithProductId:version:

Create an EQATECAnalyticsMonitor instance using the default settings.

+ (EQATECAnalyticsMonitor *)monitorWithProductId:(NSString *)productId version:(NSString *)version

Parameters

productId

the product ID in Guid-form, eg “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”

version

the product version in numeric form, eg “3.4” or “2.7.332.3451”

Return Value

an instance of the EQATECAnalyticsMonitor, or nil if productId or version is invalid

Discussion

This sample shows how to start the Analytics monitor.

 // Create EQATECAnalyticsMonitor
 EQATECAnalyticsMonitor *mon = [EQATECAnalyticsMonitor monitorWithProductId:@"YOUR_PRODUCT_KEY_HERE" version:@"1.2.3.4"];

 // Your program here....//

 // Stop monitor
 [mon stop];

Declared In

EQATECAnalyticsMonitor.h

monitorWithSettings:

Create an EQATECAnalyticsMonitor instance using the customized settings in the EQATECAnalyticsMonitorSettings instance.

+ (EQATECAnalyticsMonitor *)monitorWithSettings:(EQATECAnalyticsMonitorSettings *)settings

Parameters

settings

the settings to use for constructing the monitor

Return Value

an instance of the EQATECAnalyticsMonitor, or nil if settings is nil or invalid

Discussion

This sample shows how to start the Analytics monitor.

 // Create EQATECAnalyticsMonitor from settings
 settings = [EQATECAnalyticsMonitorSettings settingsWithProductId:@"YOUR_PRODUCT_KEY_HERE" version:@"1.2.3.4"];
 mon = [EQATECAnalyticsMonitor monitorWithSettings:settings];

 // Your program here....//

 // Stop monitor
 [mon stop];

Declared In

EQATECAnalyticsMonitor.h

Instance Methods

forceSync

Explicitly force a synchonization of the current information with the analytics server. This call is not expected to be used in a standard setup but may be helpful in occasionally connected scenarios. If you created the monitor instance by explicitly setting [EQATECAnalyticsMonitorSettings synchronizeAutomatically] to NO this is how you can force the monitor to synchronize.

- (void)forceSync

Declared In

EQATECAnalyticsMonitor.h

setInstallationInfo:

Associate an installation ID with the current usage session, and with no associated installation properties.

- (void)setInstallationInfo:(NSString *)installationId

Parameters

installationId

The installation ID to associate with the current session

Declared In

EQATECAnalyticsMonitor.h

setInstallationInfo:properties:

Associate an installation ID and a dictionary of installation properties with the current usage session.

- (void)setInstallationInfo:(NSString *)installationId properties:(NSDictionary *)propertyDictionary

Parameters

installationId

The installation ID to associate with the current session

propertyDictionary

The dictionary containing the key-value pairs for the installation properties of the current session

Declared In

EQATECAnalyticsMonitor.h

start

Call to start the monitor. When started the monitor will begin collecting data from the calls and send them asynchronously to the Analytics servers on background threads. The start method is non-blocking.

- (void)start

Declared In

EQATECAnalyticsMonitor.h

stop

Call to stop the monitor. Call will attempt to save any pending state to the storage and send the final tracking data to the servers.

- (void)stop

Discussion

This call will attempt to send the final tracking data to the servers on a background thread and by wait for completion of this monitor processing for up to 2 seconds. If you do not want to wait for up to 2 seconds for the completion of this operation, please consider using the overload to this function, stop:.

Declared In

EQATECAnalyticsMonitor.h

stopWithTimeout:

Call to stop the monitor. The monitor will attempt to save any pending state to the storage and send the final tracking data to the servers. The waitForCompletion can be specified to allow for the thread to wait for completion of data persistence and transmission. If the monitor cannot complete before the specified time the call will return.

- (void)stopWithTimeout:(NSTimeInterval)waitForCompletion

Parameters

waitForCompletion

The time to wait for the stop to complete successfully. Use 0 to avoid waiting for completion.

Discussion

This call will attempt to send the final tracking data to the servers on a background thread and by providing a waitForCompletion timeout you increase the chance that the monitor is able to completion the transmission while the runtime and threadpools are still operational. If no timeout is specified the monitor’s background threads and network connections may be removed as part of the process termination and thereby leaving data in the cache to be delivered on the next startup.

Declared In

EQATECAnalyticsMonitor.h

trackException:

Call to track an exception that occured in the application.

- (void)trackException:(NSException *)exception

Parameters

exception

The exception to be tracked

Declared In

EQATECAnalyticsMonitor.h

trackException:message:

Call to track an exception that occured in the application.

- (void)trackException:(NSException *)exception message:(NSString *)contextMessage

Parameters

exception

The exception to be tracked

contextMessage

Information about the action being performed when the exception occurred in addition to time stamp and exception message, type and stack trace which are logged automatically

Declared In

EQATECAnalyticsMonitor.h

trackException:withFormat:

Call to track an exception that occured in the application.

- (void)trackException:(NSException *)exception withFormat:(NSString *)format, ...

Parameters

exception

The exception to be tracked

format

A formatting string containing the information about the action being performed when the exception occurred in addition to time stamp and exception message, type and stack trace which are logged automatically

...

Arguments matching the specified format, in printf-style

Declared In

EQATECAnalyticsMonitor.h

trackException:withFormat:arguments:

Call to track an exception that occured in the application.

- (void)trackException:(NSException *)exception withFormat:(NSString *)format arguments:(va_list)varg

Parameters

exception

The exception to be tracked

format

A formatting string containing the information about the action being performed when the exception occurred in addition to time stamp and exception message, type and stack trace which are logged automatically

varg

va_list containing zero or more objects to format

Declared In

EQATECAnalyticsMonitor.h

trackExceptionRawMessage:reason:stacktrace:message:

Call to imitate that an NSException has occured in the application. This method is only made available to satisfy certain integration scenarios where the monitor is being used in a context where there are no native NSException objects available and the user needs to imitate a real NSException. For instance, when the monitor library is used by a hybrid mobile application written in Javascript, any exceptions that occur in that mobile application will be Javascript-objects and not NSException, and this method can then be used to log the information present in the Javascript-exception-object as if it came from a real NSException object.

- (void)trackExceptionRawMessage:(NSString *)type reason:(NSString *)reason stacktrace:(NSString *)stacktrace message:(NSString *)contextMessage

Parameters

type

a made-up name for the “type” of exception, e.g. “InvalidArgumentException”

reason

a textual description of the reason for the exception, e.g. “unrecognized key in dictionary”

stacktrace

the location of the error in whatever format makes sense to you, e.g. “MyFunc” or “Main SomeFunc SomeOtherFunc”

contextMessage

Information about the action being performed when the exception occurred, e.g. “while looking up user X”

Declared In

EQATECAnalyticsMonitor.h

trackFeature:

Register a feature usage. Features can be structured in a hieracy using dot-notation. For example use “export” to track all export operations as one, or use “export.html” and “export.pdf” to track exports to html and pdf seperately such that they can be compared.

- (void)trackFeature:(NSString *)featureName

Parameters

featureName

The name of the feature. If it is null or empty the request is ignored.

Discussion

Do not, however, use freeform text, such as the name of file being exported to, as the featureName.

Declared In

EQATECAnalyticsMonitor.h

trackFeatureCancel:

Stops an ongoing timing of a feature from any previous call to trackFeatureStart with similar featureName without registering the time spent. Use this call if the feature being tracked did not complete as expected, e.g. was interupted by an exception. The call can safely be made even if no trackFeatureStart has been made.

- (void)trackFeatureCancel:(NSString *)featureName

Parameters

featureName

The name of the feature. If it is null and empty the request is ignored.

Declared In

EQATECAnalyticsMonitor.h

trackFeatureStart:

Register the start of a feature usage. Use this with TrackFeatureStop to track how long a feature is used.

- (void)trackFeatureStart:(NSString *)featureName

Parameters

featureName

The name of the feature. If it is null and empty the request is ignored.

Discussion

Features can be structured in a hieracy using dot-notation. For example use “export” to track all export operations as one, or use “export.html” and “export.pdf” to track exports to html and pdf seperately such that they can be compared.

Do not, however, use freeform text, such as the name of file being exported to, as the featureName.

Declared In

EQATECAnalyticsMonitor.h

trackFeatureStop:

Stops an ongoing timing of a feature from any previous call to trackFeatureStart without registering a timing. Use this call if the feature being tracked did not complete as expected, e.g. was interupted by an exception. The call can safely be made even if no trackFeatureStart has been made.

- (NSTimeInterval)trackFeatureStop:(NSString *)featureName

Parameters

featureName

The name of the feature. If it is null and empty the request is ignored.

Return Value

total time tracked for this feature or 0 if timing was not tracked

Declared In

EQATECAnalyticsMonitor.h

trackFeatureValue:value:

Register a value on a specific feature.

- (void)trackFeatureValue:(NSString *)featureName value:(long)trackedValue

Parameters

featureName

The name of the feature. If it is null and empty the request is ignored.

trackedValue

The value to track

Declared In

EQATECAnalyticsMonitor.h