Configuring Analytics with Omniture

Pugpig can support using Omniture Analytics. You can use this feature to track multiple metrics of your app and it's usage, the online tools offer a huge array of ways to customise and interpret the data. Omniture is part of the Adobe Digital Marketing Suite and uses Adobe SiteCatalyst.

Integrating the Omniture SDK

The SDK is comprised of the following files:

  • ADMS_MBoxFactory.h
  • ADMS_Measurement.h
  • ADMS_MediaMeasurement.h
  • admsAppLibrary.a
  • Examples/
    • TrackingHelper.h
    • TrackingHelper.m

The Omniture SDK is not included by default in the Pugpig templates. To install it, first open Xcode. In Xcode, got to the ‘File’ menu and select ‘Add Files to “YourAppName”…’.

You’ll be prompted to navigate to the files to add, select them all and ensure you have the ‘Copy items into destination group’s folder’ selected, ‘Create groups for any added folders’ selected and the target iOS application ticked.

Lastly, click on the Project in the left hand pane and choose Build Phases in the main window. Drop down the list of Link Binary with Libraries and ensure that the admsAppLibrary.a file is listed and set to ‘required’.

Best practice for configuration

The SDK provides the TrackingHelper class files to simplify the setup of Omniture Analytics and abstract the instantiation of the service and the definition of events from your code. The following instructions presume this method is employed. Refer to the Omniture/Adobe SiteCatalyst documentation for alternatives (registration required).

Firstly, you need to import the TrackingHelper.h file into the header of the YourAppNameAppDelegate class. You can do this in two ways: directly in the YourAppNameAppDelegate.m file, in which case you'll need to remember to also import it into the header of any other class that you want to send tracking events, or you can import it into the precompiled header file, which will ensure it is available in any class file in the app. I would recommend the latter.

In the Files and Groups pane of Xcode, look in the Supporting Files group for YourAppName-Prefix.pch and add this line.

#import TrackingHelper.h

To start the Omniture Analytics service, include the following code in the application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions method on YourAppNameAppDelegate.m

[TrackingHelper configureAppMeasurement];

Omniture requires an ID to identify your app and a server address to send the analytics to. These are required. In the TrackerHelper.m file, look for the following lines and enter the data provided with your account.

#define TRACKING_RSID @"xxxxxxxxxx"

Now to enable the standard live tracking, in the same TrackerHelper.m file, uncomment the following line:

[measurement setAutoTrackingOptions:ADMS_AutoTrackOptionsLifecycle | ADMS_AutoTrackOptionsNavigation];	//LifeCycle and Navigation auto tracking enabled

If you would like tracking information sent to standard output for debugging, uncomment this line:

measurement.debugLogging = YES;

If the connection requires SSL (consult your account support for details), uncomment and modify this line:

measurement.ssl = YES;

Lastly, in each ViewController you wish to track page views for, enter the following in the viewDidLoad method:

self.title = @"NAME_OF_YOUR_CHOICE";

For further configuration options consult the documentation (registration required).

What's tracked as standard?

With this basic configuration in place, Omniture will track:

  • Installation - Triggered on first run after installation (or re-installation).
  • Upgrade - Triggered on first run after upgrade (anytime the version number changes).
  • Daily User - Triggers an event when the application is used on a particular day.
  • Monthly User - Triggers an event when the application is used during a particular month.
  • Launch - Triggered on any run that is not an install or an upgrade. This also triggers when the application is brought out of the background.
  • Crash - Triggered when the application does not exit gracefully. Event is sent on application start after crash.

Each of these events includes the following context data:

  • Install Date
  • AppID
  • Launch Number
  • Days since first launch
  • Days since last launch
  • Hour launched
  • Day launched
  • iOS Version
  • Days since last upgrade
  • Launches since last upgrade
  • Total Days used
  • Device Name
  • OS Environment
  • Carrier name

Implementing custom events


iOS client configuration

You can define both custom events and custom context data to accompany it. NOTE: to use this custom data you will be required to configure data collection on the backend using the SiteCatalyst website.

To define a custom event, you need to add a class method to TrackingHelper.m and declare it in TrackingHelper.h. There is a template inTrackingHelper.m, which you can use as a guide. Below is an example that tracks the default font size:

+ (void)trackFontSizeChange:(NSString *)fontSize {
  NSMutableDictionary *contextData = [NSMutableDictionary dictionary];
  [contextData setObject:fontSize forKey:@"com.xxxxxxx.newFontSize"];
  [[ADMS_Measurement sharedInstance] trackEvents:@"eventXX" withContextData:contextData];

Remember to declare it in the TrackingHelper.h file”

+ (void) trackFontSizeChange:(NSString *)fontSize;

To call the method in your code you would use:

NSNumber *sizeToLog = [NSNumber numberWithFloat:pageControl.fontSize];
[TrackingHelper trackFontSizeChange:[sizeToLog stringValue]];

Server-side configuration

The SiteCatalyst website is where you make changes to the server-side. Omniture works on the concept of Report Suites, with each reporting system (website, app etc…) having it's own Report Suite. Within a Report Suite you can define up to 50 rules (called Processing Rules) that determine how to manipulate the incoming analytic data. Each of these rules can contain up to 30 conditions that can change, concatenate and make conditional decisions based on the received data.

The principle task that Processing Rules perform is to pair the context data you defined in your custom event to an eVar that the Report Suite has available to store the data in. To apply this to the example in the previous section, recall that we defined a piece of context data that sent an NSString containing the value of the screen font size, and sent it each time we detected a change to that font size. The context data was set with this line:

[contextData setObject:fontSize forKey:@“com.xxxxxxx.newFontSize”];

Note the format for the key is similar to that used in plists in iOS, this is the recommended format for the key.

In order to track this context data, you will need to setup a Processing Rule that pairs this key to one of the available eVars. You can then take the data received and add further clauses to the rule that help you build the reporting functions required for your app.

Full details on how to build and manage Processing Rules are available in the SiteCatalyst documentation.

Data usage and offline tracking options

The default operation for Omniture is to send live tracking data whenever the iOS device is online.

Offline tracking is available, and active by default, so if the iOS device cannot connect to the internet then the analytics will be timestamped and cached to local persistent storage and transmission reattempted at regular intervals. The settings for the cache size, retransmission period and the queue size are configurable at the point of initialisation and during runtime. Consult the Omniture documentation for more information.

The default setup of live tracking can result in depletion of the users cellular data allowance. The settings allow for the programatic disabling of live tracking in response to a switch in the method of connection. For instance you can live track when the device is connected to a Wireless 802.11a/b/g/n network and disable it when on a 3G or 4G cellular connection. Consult the Omniture documentation for details.

Further options and instructions

The Omniture SDK also provides tools for measuring and tracking metrics on video playback, consult the documentation for the SDK for more details.

The tracking data is dependant on correct configuration of the backend SiteCatalyst services provided by Adobe Digital Marketing Suite. Refer to the included documentation for SiteCatalyst for further details.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk