application tag ios digital analytix us
DESCRIPTION
ios tag analytux comscoreTRANSCRIPT
-
DIGITAL ANALYTIX
Application Tag for iOSImplementation GuideDocument version: 3.0.2 (released January 22, 2015)
FOR FURTHER INFORMATION, PLEASE CONTACT:comScore, Inc.
Digital Analytix Customer Support+1 866 276 [email protected]
DOCUMENT VERSION 3.0.2
-
Contents
Implementation Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Tagging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Application Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Intended Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Implementing the Application Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Include the Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Import the Library in Your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Set the Application Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Set Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
The CustomerC2 Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
The PublisherSecret Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
The AppName Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
The LiveTransmissionMode Parameter . . . . . . . . . . . . . . . . . . . . . . . . . 9
The OfflineTransmissionMode Parameter . . . . . . . . . . . . . . . . . . . . . . . 9
The KeepAliveEnabled Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
User Experience Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Auto-Update of Usage Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Setting Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Adding Persistent Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Adding Event-specific Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Dispatching Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Application Start Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
View Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Hidden Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Aggregate Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Updating an Existing Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Testing the Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Configuring Your Test Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 2 OF 22
-
Implementation Quick Start
This section contains abridged implementation instructions for advanced users.
1. Include the comScore folder which contains the file libcomScore.a and folder headers in your project as a
group and include libcomScore.a in the Link Binary with Libraries list in your project settings (see Include the
Library on page 6).
2. Make sure your project includes SystemConfiguration.framework and Security.framework (see Checklist on
page 5).
3. Import the CSComScore.h headers in your code (see Import the Library in Your Project on page 7).
4. Set the application context by including the following call inside application
didFinishLaunchingWithOptions (see Set the Application Context on page 7):
[CSComScore setAppContext];
5. Set library configuration parameters by calling the following API methods immediately after setting the application
context (see Set Configuration Parameters on page 8).
Configure your assigned comScore Client ID:
[CSComScore setCustomerC2:@"your_client_ID"];
Configure your assigned comScore Publisher Secret:
[CSComScore setPublisherSecret:@"your_publishersecret_string"];
Set any of the optional configuration parameters mentioned in Set Configuration Parameters on page 8 as
needed.
6. Please set label ns_site and any other persistent labels right after setting the application context and the
configuration parameters (see Adding Persistent Labels on page 12):
[CSComScore setLabel: "ns_site" value: "name_of_your_site"];
7. Implement calls to [CSComScore onUxActive] and [CSComScore onUxInactive] for measurement of
application usage time measurement (see User Experience Measurement on page 10).
8. Enable the auto-update feature to improve measurement of usage times by calling the enableAutoUpdate
method (see Auto-Update of Usage Time on page 11).
9. Implement calls to [CSComScore view], [CSComScore hidden] and [CSComScore aggregate] to
dispatch events with appropriate labels as required per your implementation scheme (see Setting Labels on
page 11 and Dispatching Application Events on page 13).
After successfully following these steps you will have implemented the comScore Application Tag. Your application
should now send measurements whenever it is active. Please refer to Testing the Implementation on page 21 for
instructions on testing the implementation.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 3 OF 22
-
Introduction
TaggingA tag is a piece of scripting or markup that is placed on a website or another web based content asset. Tags are
sometimes referred to as tracking pixels or beacons. They are used to measure the consumption of digital content by
an end-user. Tagging is the process of adding a comScore tag also called measurement code or SDK(1) to your
digital content. Each time a tagged piece of content e.g., a web page, a video stream or an application view in a
(mobile) application is used by an end-user, the tag sends data via an HTTP request to comScore's data collection
servers.
Application TagThe comScore Application Tag provides an application measurement solution that is designed to provide complete
usage reporting about the application lifecycle. For applications on mobile devices that includes usage reporting even
when the device does not have any available data connection.
Intended UseThese instructions and the SDK library are intended to be used with iOS applications that are developed in native
Objective C code and compiled with Apple Xcode.
If your application is developed in another programming language then please inform your Digital Analytix account
manager or consultant or contact Digital Analytix Customer Support (contact details can be found on the front page of
this document). Your account manager or consultant and Digital Analytix Customer Support can confirm whether or
not the comScore Application Tag SDK can be used with your development environment.
This document is written on the assumption that the reader is familiar with tagging
content for measurement by Digital Analytix(2). Please refer to the Digital Analytix Content
Tagging Guidelines document for guidelines on tagging your content for measurement by Digital
Analytix.
(1) SDK is an acronym for Software Development Kit which is typically a set of tools and documentation for the creation of software.(2) For example; it is assumed that the reader understands the meaning of page names and measurement domains and has experience with the use
of measurement URLs, events and labels.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 4 OF 22
-
Checklist
Before adding the comScore Application Tag SDK to your project, please complete the following checklist:
Familiarize yourself with the contents of this document.
If you want to use the offline cache then please make sure the Event Ingest module is enabled on your Digital
Analytix account.
Your Digital Analytix account manager or Digital Analytix consultant can provide you with more information about
the Event Ingest module.
Make sure you have your comScore Client ID.
The Client ID is also known as the C2 value. This is a number of at least 7 digits, provided by comScore.
Your Digital Analytix account manager or Digital Analytix consultant can provide you with your Client ID.
Make sure you have a Publisher Secret, which is supplied by comScore.
The Publisher Secret is a text string used to obfuscate the ADID(3) when measurements are sent to comScore
servers. The ADID is an anonymous unique value that is generated by the Application Tag library and is
persistent only between applications of the same publisher.
It is the same for all of your applications, but unique to you.
This is required for security, and to protect the privacy of your application's users.
Your Digital Analytix account manager or Digital Analytix consultant can provide you with the Publisher Secret.
Make sure your project includes SystemConfiguration.framework and Security.framework.
If you are targeting versions of iOS older than iOS 6.0, mark AdSupport.framework as "Optional" in your
project's target options (Build Phases > Link Binary With Libraries).
Make sure your project includes the comScore folder which contains the file libcomScore.a and headers folder..
This folder is included in the comScore Application Tag SDK.
Your Digital Analytix account manager or Digital Analytix consultant will have sent the comScore Application Tag
SDK to you.
Make sure you have an implementation scheme that defines page names, link names and additional labels for
each link that will be tagged.
Please contact your Digital Analytix account manager, consultant or Customer Support with any questions (contact
details can be found on the front page of this document).
(3) ADID is an acronym for Anonymous Device Identifier which is generated by the comScore Application Tag library.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 5 OF 22
-
Implementing the Application Tag
Please implement the comScore Application Tag library according to the instructions
given in this document.
Please do not implement the Application Tag library on a separate thread or with a delay. Please
call the library's API methods and assign any event handlers as instructed.
The library needs to be able to register application lifecycle events before those events are triggered for correct
measurement of application start, foreground to background transitions and application usage times. The provided
implementation instructions facilitate this.
If you have doubts or concerns regarding these instructions then please contact your Digital Analytix account manager
or consultant or contact Digital Analytix Customer Support to discuss your doubts and/or concerns.
If you are updating an existing implementation from comScore Application Tag for iOS version 2.1305.08 or lower
then you likely have to address the items mentioned in Updating an Existing Implementation on page 19.
Include the LibraryTo begin, the comScore library must be available in your project.
1. Drag and drop the comScore folder which contains the file libcomScore.a and folder headers into your project.
2. Add the library for linking:
1. Go to the Build Phases panel of your project's target options.
2. Expand Link Binary with Libraries to reveal the list of frameworks and libraries that will be linked when building
a binary.
3. Drag and drop libcomScore.a from the Project Navigator into the list of frameworks and libraries beneath Link
Binary with Libraries. This will also automatically cause the comScore folder to be added to the Library Search
Paths in the Build Settings panel of your project's target options.
3. Add the native SystemConfiguration.framework and Security.framework.
Previous versions of this document included instruction to add the native AdSupport.framework in your project. If
your application does not contain advertisements and your project does not need the AdSupport.framework for
other reasons, then you can safely remove the AdSupport.framework. The comScore library does not require the
AdSupport.framework.
The image below shows an example of what the Xcode Project Navigator bar could look like after performing these
steps.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 6 OF 22
-
Import the Library in Your ProjectInclude the comScore library headers with a statement like:
#import "CSComScore.h"
If you are upgrading from a previous Application Tag SDK implementation then you might have to change the
import statement. Please verify this in your project code's import statements. Previous versions required the
framework to be imported, instead of only the headers.
Set the Application ContextYou must inform the comScore library of the Application Context by using the setAppContext method of the
Application Tag library API. This has to be done before calling any of the other comScore library API methods,
including those that define configuration parameter settings for the Application Tag library.
Please add the following statement inside application didFinishLaunchingWithOptions:
[CSComScoreCSComScore setAppContext];
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 7 OF 22
-
Please include the call to the setAppContextsetAppContext as well as any statements with Application Tag library
configuration parameter settings inside application didFinishLaunchingWithOptionsapplication didFinishLaunchingWithOptions. The
configuration parameters are discussed in Set Configuration Parameters on this page. Please also do not
implement these initialization calls on a separate thread or with a delay.
The Application Tag library relies on application lifecycle events. If you do not follow these instructions then the
Application Tag library will not be able to register application lifecycle events before those events are triggered for
correct measurement of application starts and usage times.
Set Configuration ParametersPlease use the API methods described in this section to set the configuration parameters of the Application Tag libary.
Please make sure to call these API methods immediately after setting the application context.
Previous versions of the library also supported the use of a settings file named comScore.plist for settting
configuration parameters. Support for this functionality has been deprecated in favor of the library API methods.
The CustomerC2CustomerC2 Parameter
The Customer C2 is your comScore Client ID. It is a number with at least 7 digits. You can set the CustomerC2
parameter as follows(4):
[CSComScoreCSComScore setCustomerC2:@"1000001"];
The PublisherSecretPublisherSecret Parameter
The Publisher Secret is a comScore-supplied string used to obfuscate the ADID(5) when measurements are sent to
comScore servers. It is the same for all of your applications, but unique to you, and is required to protect the privacy of
your application's users. You can set the PublisherSecret parameter as follows:
[CSComScoreCSComScore setPublisherSecret:@"your_publishersecret_string"];
The AppNameAppName Parameter
By default the library sets the reported application name from your app's Info.plist application bundle name
(CFBundleName).
The App Name is used to override the application name that is detected by the library in case the detected value
should not be used for reporting. You can set the AppName parameter as follows:
[CSComScoreCSComScore setAppName:@"My Application Name"];
(4) The examples in this document use Client ID value 1000001 which is an example value. Please make sure you use your assigned comScoreClient ID instead.
(5) ADID is an acronym for Anonymous Device Identifier which is generated by the Application Tag library.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 8 OF 22
-
The LiveTransmissionModeLiveTransmissionMode Parameter
The Live Transmission Mode controls the transmission of HTTP GET measurements by the Application Tag library
while the device has connectivity.
There are three modes available as constant values in enum CSTransmissionMode(6):
Mode Transmission?CSDEFAULTMODE Enabled whenever the device has connectivity.
CSWIFIONLYMODE Only when the device has WIFI connectivity.
CSNEVERMODE Disabled even if the device has connectivity.
If the LiveTransmissionMode parameter value disables transmission then the events will not be sent. Whether or
not events are cached as offline events and transmitted when the offline events cache is flushed depends on the
OfflineTransmissionMode parameter value (see below).
You can set the LiveTransmissionMode parameter as follows:
[CSComScoreCSComScore allowLiveTransmission:CSDEFAULTMODE];
The OfflineTransmissionModeOfflineTransmissionMode Parameter
The Offline Transmission Mode controls the availability of the offline cache and offline cache flushes. Offline cache
flushes are HTTP POST transmissions when the device resumes connectivity. The offline cache flush sends the
measurement data that was collected while the device did not have connectivity.
The offline cache and offline cache flushes require the Event Ingest module to be enabled on your Digital
Analytix account.
Without the Event Ingest module any measurement data that was collected while the device did not have
connectivity will not be available in Digital Analytix.
There are four modes available (these modes are available as constant values in enum CSTransmissionMode):
Mode Offline cache? Automatic flush?CSDEFAULTMODE Enabled Only when connectivity is restored on the device.
CSWIFIONLYMODE Enabled Only when the device has WIFI connectivity.
CSNEVERMODE Enabled Never(7)
CSDISABLEDMODE Disabled(8) Never
You can set the OfflineTransmissionMode parameter as follows:
(6) When using code completion in your project you might notice additional values. The additional values are not supported for this parameter.(7) This means the cache must be flushed manually.(8) This means no events will be cached (which implies manual flushing is not needed).
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 9 OF 22
-
[CSComScoreCSComScore allowOfflineTransmission:CSDEFAULTMODE];
You can manually flush the offline cache at any time by using the flushCache API method:
[CSComScoreCSComScore flushCache];
Please check for connectivity before manually flushing the offline cache.
If you have set OfflineTransmissionModeOfflineTransmissionMode to CSNEVERMODECSNEVERMODE then the offline cache will
not be flushed automatically.
In that case you will have to manually flush the offline cache in order to send any measurement
data that has been collected while the device did not have connectivity.
The KeepAliveEnabledKeepAliveEnabled Parameter
The Keep Alive Enabled parameter determines if the Application Tag library will transmit a keep-alive event(9) once
every 24 hours if during that period the application was active and no other events were transmitted.
The default paramater value is YES which means this functionality is enabled by default. You can turn this feature off
by setting the parameter to value NO(10).
You can set the KeepAliveEnabled parameter as follows:
[CSComScoreCSComScore setKeepAliveEnabled:NO];
User Experience MeasurementIf your application provides a user experience like the playback of music or video then please implement calls to
the following Application Tag library API methods:
onUxActiveonUxActive
This API method needs to be called whenever your application starts providing the user experience (i.e., audioand/or video).
onUxInactiveonUxInactive
This API method needs to be called whenever your application stops providing the user experience.
For the correct measurement of usage time during background activity this is particularly important. For example, to
notify the Application Tag library that playback of audiovisual content has started:
[CSComScoreCSComScore onUxActive];
(9) This keep-alive event is reported in Digital Analytix as a hidden event.(10) You do not have to specify/modify the KeepAliveEnabled parameter unless you want to turn the setting off.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 10 OF 22
-
Auto-Update of Usage TimeThe Application Tag library contains an auto-update feature that will update the application usage times on regular
intervals. This feature is turned off by default.
To get the best possible measurement of application usage time please enable the auto-update feature and
implement calls to the onUxActiveonUxActive and onUxInactiveonUxInactive methods.
You can enable the auto-update feature by including a call to the enableAutoUpdate method as part of the
initialization settings. The method accepts two parameters:
intervalinterval
An integer interval value in seconds. This parameter has a default value of 60, which is also the minimum value. Ifyou provide a value lower than 60 for the interval then the library will use the default value.
foregroundOnlyforegroundOnly
A boolean flag which will allow auto-update to be active while the application is in the background. The defaultvalue of the parameter is YES which means the auto-update feature is only active while the application is in theforeground.
If your application is capable of delivering a user experience while the application is in the background then please
make sure you allow auto-update to be active while the application is in the background by setting the
foregroundOnly flag to NO.
Please note the following when you enable the auto-update feature and allow it to be active while the application is
in the background:
The auto-update feature will only activate in the background if the Application Tag library determines your
application is active too. This relies on calls to the onUxActive method (see User Experience Measurement on
page 10). Similarly, when you call onUxInactive the auto-update feature will automatically deactivate while the
application is in the background.
Some examples of activating auto-update:
21. [CSComScoreCSComScore enableAutoUpdate:120 foregroundOnly:NO]; // Interval at 2 minutes during fore- and background.22. [CSComScoreCSComScore enableAutoUpdate:300 foregroundOnly:YES]; // Interval at 5 minutes, only during foreground.
Setting LabelsThe Application Tag allows you to specify (custom) labels. You can either specify persistent labels or event-specific
labels.
Persistent labels
Persistent labels will be included in every measurement that is sent by the Application Tag library. They willcontain their last known value. You could consider these labels to be application-wide.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 11 OF 22
-
Event-specific labels
Event-specific labels will be included to the measurement that is sent for the tagged event. These should be usedfor collecting information which only applies to a single event. These labels are not automatically included in anyfollowing measurements. For example, if you add labels to a tagged View event then the labels will only appear inthe corresponding view measurement. Labels that are specified as event-specific will override values for the samelabel at persistent-level.
Please set label ns_site as a persistent label. Label ns_site is used by Digital Analytix to identify the site in
which measurement data should be stored.
Please set label ns_site in the application didFinishLaunchingWithOptions method, after setting the
application context . Please refer to Set the Application Context on page 7 for more details.
Adding Persistent Labels
There are two methods you can use to set persistent labels:
setLabelsetLabel
To set a single persistent label.
setLabelssetLabels
To set one or more persistent labels with a single statement.
Some examples:
31. // Set a single label32. [CSComScoreCSComScore setLabel:@"labelName1" value:@"myValue1"];33.34. // Set any number of labels35. [CSComScoreCSComScore setLabels:[NSDictionaryNSDictionary dictionaryWithObjectsAndKeys:36. @"myValue1", @"labelName1",37. @"myValue2", @"labelName2",38. @"myValue3", @"labelName3",39. nil]];
Adding Event-specific Labels
You can include event-specific labels in the Application Tag library API methods that are used to tag the application
events. Event-specific labels are provided as a dictionary of key and value pairs.
Please refer to Dispatching Application Events on page 13 for more details on tagging events as well as examples
for adding event-specific labels.
The Application Tag library will automatically detect the application has been started and send an Application Start
event accordingly (please refer to Application Start Event on page 13 for more information about this event). To
provide a way for you to include event-specific labels in this automatically generated Application Start event the
Application Tag library API provides the following two methods:
setAutoStartLabelsetAutoStartLabel
To set a single event-specific label for the automatically generated Application Start event.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 12 OF 22
-
setAutoStartLabelssetAutoStartLabels
To set one or more event-specific labels for the automatically generated Application Start event with a singlestatement.
Any labels set via these methods will only be included in the automatically generated Application Start event as
event-specific labels.
Some examples:
41. // Set a single label42. [CSComScoreCSComScore setAutoStartLabel:@"labelName1" value:@"myValue1"];43.44. // Set any number of labels45. [CSComScoreCSComScore setAutoStartLabels:[NSDictionaryNSDictionary dictionaryWithObjectsAndKeys:46. @"myValue1", @"labelName1",47. @"myValue2", @"labelName2",48. @"myValue3", @"labelName3",49. nil]];
Dispatching Application EventsYou can use the Application Tag library API to tag the following events:
Application Start
View
Hidden
Aggregate
Please make sure all configuration parameter settings for the Application Tag library are defined before
sending any events.
Application Start Event
The Application Tag library will automatically detect the application has been started and will automatically send an
Application Start event when the application enters foreground. The application start event collects information about
the current application including the version, the last time it was executed and the last version used if there was an
update of the application.
The Application Start event coincides with the application transitioning to foreground and the appearance of a screen
of the application. Accordingly, the Application Start event is interpreted in reporting as a screen impression or screen
view (the equivalent of the page impression or page view used in web analytics). It is a special screen impression too;
the first in the application's current life cycle.
The Application Tag library provides the start and startWithLabels methods for use in advanced implementation
scenarios. The majority of Application Tag implementations will not have a need to call this method and should rely on
the Application Tag library to automatically detect the application start.
If you think you need to call the startstart methods manually then please discuss your situation with your Digital
Analytix account consultant first.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 13 OF 22
-
If there indeed is a need to manually tag the application start then you should inform the Application Tag library of the
application start as soon as you are notified of a successful application launch. Usually, this would be in the
application didFinishLaunchingWithOptions method, after setting the application context (see Set the
Application Context on page 7) .
Please note the following three things:
1. Please call method setAutoStartEnabled and provide NO as its value. This disables the automatic detection of
the application start.
2. Please make sure you define any configuration parameter settings for the Application Tag library and persistent
labels you want to use before sending an Application Start event.
3. Please be aware any labels set via the setAutoStartLabel and setAutoStartLabels methods will not be
used in the manual start. You can provide these as event-specific labels when you manually notify the Application
Tag library of the application start.
To manually inform the Application Tag library of the application start, call the start method on the library API:
[CSComScoreCSComScore start];
You can also specify event-specific labels. The following example adds two labels:
Standard label name with sample application view or screen name start.
Custom label mycustom with a sample value my sample value.
51. [CSComScoreCSComScore startWithLabels:[NSDictionaryNSDictionary dictionaryWithObjectsAndKeys:52. @"start", @"name",53. @"my sample value", @"mycustom",54. nil]];
View Event
You may report a View event whenever the application screen changes. This screen impression or screen view is the
equivalent of the page impression or page view used in web analytics.
The View event is intended to be used in the following cases:
When the application changes the current screen.
When the contents of the current screen are changed significantly(11) even though the application does not change
the current application screen.
When the application transitions to foreground.
Page impressions have a page name to identify the application view or screen. You can specify the page name with
label name. To inform the Application Tag library of a View event and provide the page name:
(11) There is no standard of what is 'significant' for application analytics. Currently the comScore-defined interpretation of 'significant' is a contentchange of fifty percent or more directly caused by user interaction.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 14 OF 22
-
[CSComScoreCSComScore viewWithLabels:[NSDictionaryNSDictionary dictionaryWithObjectsAndKeys:@"my.view.name", @"name",nil]];
If you want to report a View event without providing any labels then you can simply omit the labels:
[CSComScoreCSComScore view];
Reporting a View Event When a UIViewController Appears
If you want to report a View event every time a UIViewController appears including when the application transitions to
foreground then please consider the following advice.
Report the View event when your UIViewController appears. You can do that from within your UIViewController's
viewDidAppear method. Also add an observer for UIApplicationDidBecomeActiveNotification in your
UIViewController's viewDidAppear method.
Besides that make sure you remove that observer in your UIViewController's viewDidDisappear method. It is
important to remove the observer of UIApplicationDidBecomeActiveNotificationUIApplicationDidBecomeActiveNotification when the view
disappears to avoid unwanted behavior and potentially crashes.
This approach will ensure the View event is reported when a view becomes active. When applied to all your
UIViewControllers it will also make sure the current view reports a View event when the application becomes
active(12).
The example code shown below contains an implementation of this advice. It also includes a method sendView(13)
which reports a view event. The same sendView method is also utilized when the observer for
UIApplicationDidBecomeActiveNotification is notified.
(12) According to the iOS Programming Guide an application is considered active when the application is running in the foreground and is receivingevents, which is the normal mode for foreground applications. Please refer to the iOS programming guide for more information.
(13) The name and specific contents of the sendView method are just an example. You should choose a name that fits in with your own programmingconventions and decide on which additional labels you want to include in the reported View event.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 15 OF 22
-
111. - (voidvoid) viewDidAppear:(BOOL)animated {112.113. [supersuper viewDidAppear:animated];114. [selfself sendView];115. [[NSNotificationCenterNSNotificationCenter defaultCenter] addObserver:selfself116. selector:@selector(sendView)117. name:UIApplicationDidBecomeActiveNotificationUIApplicationDidBecomeActiveNotification118. objectobject:nilnil];119. }120.121. - (voidvoid) viewDidDisappear:(BOOL)animated {122.123. [supersuper viewDidDisappear:animated];124. [[NSNotificationCenterNSNotificationCenter defaultCenter] removeObserver:selfself125. name:UIApplicationDidBecomeActiveNotificationUIApplicationDidBecomeActiveNotification126. objectobject:nilnil];127. }128.129. - (voidvoid) sendView {130.131. [CSComScoreCSComScore viewWithLabels:[NSDictionaryNSDictionary dictionaryWithObjectsAndKeys:132. @"my.view.name", @"name",133. nilnil]];134. }
You will likely already have other code in the viewDidAppear and viewDidDisAppear methods. Please report the
View event and add the observer as soon as possible when your UIViewController's viewDidAppear is called to
allow the observer to be able to be notified when the application becomes active after transitioning to foreground.
Hidden Event
Any application event or user action that does not categorize as a View event can be reported as a Hidden event. Like
View events, Hidden events also have a page name that is used in reporting to identify the application view or screen
where the application event or user action took place.
Hidden events are intended to be used for measuring user or application activity that does not necessarily result in a
change in the current application screen, similar to hidden events on web pages. Examples of cases where the
application event can or will be used:
A user taps or clicks on a button, for example to enable a feature in the application.
The application performs a certain (internal) activity, like sending data from a filled in feedback form.
To inform the Application Tag library of a hidden event and provide the page name:
[CSComScoreCSComScore hiddenWithLabels:[NSDictionaryNSDictionary dictionaryWithObjectsAndKeys:@"my.view.name", @"name",nil]];
If you want to report a Hidden event without providing any labels then you can simply omit the labels:
[CSComScoreCSComScore hidden];
Aggregate Event
Aggregate events are somewhat special: they do not generate a measurement (or network request). Instead, any
label(14) you send with this event will be stored in memory instead of being transmitted immediately.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 16 OF 22
-
When more than one Aggregate event is fired consecutively, the specified values are appended or added to those
previously stored using one of the aggregation patterns described below.
You can inform the Application Tag library API of an Aggregate event using method aggregateWithLabels. For
example:
[CSComScoreCSComScore aggregateWithLabels:[NSDictionaryNSDictionary dictionaryWithObjectsAndKeys:@"red,blue,green,", @"gems",nil]];
When the first non-aggregated event e.g. a Application Start, View or Hidden event occurs, the labels with
aggregated data will be included in the measurement that is generated by the event. The stored aggregated data is
cleared after it is sent.
Aggregation patterns
Label values are always of type String but their aggregation pattern may vary depending on their value format,
defined as:
Numbers
If a label's value can be casted to a number, then this label will be summed consecutively, reporting the total sum as
value.
Event 1 "gems=1"
Event 2 "gems=2"
Event 3 "gems=2"
Result: gems=5
This will appear in the next measurement URL as: gems=5
Lists
We define Lists as comma-separated lists of strings not containing spaces that ends with a comma if there is only
one item. Aggregation here will record the number of times each single value appeared, reporting a concatenation
with semicolons of each value plus a colon, plus the total number of times it was received.
Example:
Event 1 "gems=blue,"
Event 2 "gems=blue,red,green"
Event 3 "gems=blue,green"
Result: gems=blue:3;red:1;green:2
This will appear in the next measurement URL as: gems=blue%3A3%3Bred%3A1%3Bgreen%3A2
(14) Please refer to Setting Labels on page 11 for more details on the use of labels.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 17 OF 22
-
Strings
Disregarding the above types, strings will be defined as "any group of characters not containing commas, or
containing commas and spaces". The aggregation method will store each unique value received, reporting a comma-
separated list of values.
Example:
Event 1 "gems=blue"
Event 2 "gems=red"
Event 3 "gems=green"
Event 4 "gems=red"
Result: gems=blue,red,green
This will appear in the next measurement URL as: gems=blue%2Cred%2Cgreen
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 18 OF 22
-
Updating an Existing Implementation
If you are updating an existing implementation of comScore Application Tag for iOS version 2.1305.08 or lower then
you likely have to address the items in this section.
Change Import StatementsThe library is no longer distributed as a framework. As a result the import statements have slightly changed. Please
check the import statements in your project against the instructions mentioned in Import the Library in Your Project
on page 7. Please also remove any remaining comScore frameworks from your project.
Remove Settings FileThe use of the comScore.plist settings file has been deprecated in favor of using API methods to set the library
configuration. With the next major version update of the library any support for the settings file will be removed. If your
application project uses this settings file then please update your implementation to use the library API methods
instead.
Remove Calls to StartStart MethodFrom version 2.1306.20 the comScore Application Tag library will automatically detect the application start. The
Start API method has also been renamed to start to comply with platform coding conventions. If you are
upgrading an existing Application Tag implementation then your application could contain a statement containing a call
to the Start API method. For example:
[CSComScoreCSComScore StartStart];
You will likely find that statement in the application didFinishLaunchingWithOptions method. Please
remove that statement from your application.
If you have included statements containing a call to the Start API method in other locations, please change those
statements so they use the view API method instead. There no longer is a need to manually tag the application start.
If you want to manually tag the application start nonetheless then please refer to Application Start Event on page
13 for instructions.
Change Calls to Set Persistent LabelsThe API methods setCustomLabel and setCustomLabels have been renamed to setLabel and setLabels,
respectively for consistency across different comScore tags. The 'value' parameter is now specified using
value:@"my_value" instead of andValue:@"my_value". Please change any statements accordingly.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 19 OF 22
-
Change Calls to Notification MethodsThe API methods Start, View, Hidden and AggregateWithLabels have been renamed to start, view,
hidden and aggregateWithLabels, respectively to comply with platform coding conventions. Similarly, API
methods StartWithLabels, ViewWithLabels and HiddenWithLabels have been renamed to
startWithLabels, viewWithLabels and hiddenWithLabels, respectively.
If you have been using any of the convenience methods listed in the first column of the table found below then please
change those statements in your code to use the API methods mentioned in the second column.
Convenience Method Replacement Code
[CSComScoreStartWithPageName:@"pageName"];
Call [CSComScore startWithLabels:labelDict]; andprovide an NSDictionary containing label name with valuepageName as labelDict.
[CSComScoreViewWithPageName:@"pageName"];
Call [CSComScore viewWithLabels:labelDict]; and providean NSDictionary containing label name with value pageName aslabelDict.
[CSComScoreHiddenWithPageName:@"pageName"];
Call [CSComScore hiddenWithLabels:labelDict]; andprovide an NSDictionary containing label name with valuepageName as labelDict.
[CSComScoreStartWithPageName:@"pageName"andLabels:labelDict];
Add label name with value pageName to labelDict.
[CSComScoreViewWithPageName:@"pageName"andLabels:labelDict];
Add label name with value pageName to labelDict.
[CSComScoreHiddenWithPageName:@"pageName"andLabels:labelDict];
Add label name with value pageName to labelDict.
Change Names of Transmission ModesThe transmission modes in enum CSTransmissionMode have been changed to prevent conflicts with other enums.
The changes are shown below:
Old Name New NameDEFAULT CSDEFAULTMODE
WIFIONLY CSWIFIONLYMODE
NEVER CSNEVERMODE
DISABLED CSDISABLEDMODE
This only affects the API calls where these modes are used, i.e., allowLiveTransmission and
allowOfflineTransmission. Please change any statements accordingly.
Change Calls to FlushOfflineMeasurementsCacheFlushOfflineMeasurementsCacheThe FlushOfflineMeasurementsCache API method has been renamed to flushCache. Please change any
statements accordingly.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 20 OF 22
-
Testing the Implementation
As you test your comScore-tagged application internally, comScore servers will collect the measurements. For
immediate testing, you can use any tool you would normally use to look at HTTP traffic coming from your application.
As long as your chosen tool can show you the query string parameters it will be sufficient for testing your Application
Tag library implementation. Some often used tools are HTTP proxies like Charles Proxy and Fiddler.
Configuring Your Test EnvironmentThese instructions are generic and also apply to other tools commonly used to review HTTP traffic from (mobile)
devices.
1. Setup your tool of choice to be able to review HTTP traffic from your device.
2. Setup your device so its HTTP traffic can be reviewed by your chosen tool.
3. To make it easier to review the collected data, configure your chosen tool to filter HTTP traffic:
If you see an HTTP request going to this hostname when you cold start(15) the application this means the comScore
Application Tag SDK is sending measurement data.
To further check your implementation please confirm that all the items mentions in your implementation scheme are
covered, result in HTTP requests when needed and contain the appropriate values for any custom labels you
specified.
Once you have verified the SDK is correctly implemented you must resubmit your application to the iTunes
App Store for approval.
(15) A cold start is defined as starting the application while the application was not running in the foreground or background.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 21 OF 22
-
Frequently Asked Questions
How can I validate my application measurement is working as intended?
There are two ways to validate your application measurements. You could test the measurements yourself by
following the instructions on page 21.
In addition, you could start your application at least 10 times and review Digital Analytix reporting. If you do not see
your application measurements after half an hour, then please contact Digital Analytix Customer Support (contact
details can be found on the front page of this document) or your Digital Analytix account manager or consultant.
Please make sure you provide them with your implementation details i.e., your client ID or measurement URL and
your Publisher Secret so they can confirm whether or not your application measurements have been received.
Do I have to re-submit my app?
Yes. Once you have tested and confirmed your implementation of the comScore Application Tag library, resubmit your
application. If the changes you have made since your last application update are only related to the comScore
Application Tag library then your applications should pass review in a timely manner.
Will adding the comScore library slow down the application?
No. The code in the comScore Application Tag library is extremely lightweight and will not affect the performance of
your application.
How can I change my applications name that is reported to comScore?
The reported application name defaults to the value mentioned in section The AppName Parameter. Before you
call any of the comScore Application Tag library's notification methods, you can change your reported application
name by setting the AppName configuration parameter (see The AppName Parameter on page 8).
Will comScore receive measurements if my application user is currently roaming?
If an application launches where your user may incur roaming charges, the operating system of the device might
display a warning on the screen. When the application is active and the device has internet connectivity we will
receive the measurements.
Digital Analytix Application Tag for iOS - Implementation Guide
document version 3.0.2 - 2015 comScore, Inc. PAGE 22 OF 22
ContentsImplementation Quick StartIntroductionTaggingApplication TagIntended Use
ChecklistImplementing the Application TagInclude the LibraryImport the Library in Your ProjectSet the Application ContextSet Configuration ParametersThe CustomerC2 ParameterThe PublisherSecret ParameterThe AppName ParameterThe LiveTransmissionMode ParameterThe OfflineTransmissionMode ParameterThe KeepAliveEnabled Parameter
User Experience MeasurementAuto-Update of Usage TimeSetting LabelsAdding Persistent LabelsAdding Event-specific Labels
Dispatching Application EventsApplication Start EventView EventReporting a View Event When a UIViewController Appears
Hidden EventAggregate EventAggregation patternsNumbersListsStrings
Updating an Existing ImplementationChange Import StatementsRemove Settings FileRemove Calls to Start MethodChange Calls to Set Persistent LabelsChange Calls to Notification MethodsChange Names of Transmission ModesChange Calls to FlushOfflineMeasurementsCache
Testing the ImplementationConfiguring Your Test Environment
Frequently Asked Questions