Application Tag IOS Digital Analytix US
Application Tag IOS Digital Analytix US
Application Tag IOS Digital Analytix US
Application Tag
Implementation Guide for iOS
Digital Analytix
Contents
Implementation Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tagging
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Tag
4
4
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Intended Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Initialization Settings
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
. . . . . . . . . . . . . . . . . . . . . . . 8
. . . . . . . . . . . . . . . . . . . . . . . . . . . 10
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Hidden Event
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Aggregate Event
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
PAGE 2 OF 20
Digital Analytix
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
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
3. Create the comScore.plist file in the Supporting-Files folder of your project and supply the following parameters
(see
5. Set the application context by including the following call inside application
didFinishLaunchingWithOptions (see
[CSComScore setAppContext];
6. Implement calls to [CSComScore onUxActive] and [CSComScore onUxInactive] for measurement of
application activity (see
Setting Labels on
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
PAGE 3 OF 20
Digital Analytix
Introduction
Tagging
A 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 comScores data collection
servers.
Application Tag
The 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 Use
These instructions and the SDK library are intended to be used with media players that run inside 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 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.
PAGE 4 OF 20
Digital Analytix
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 Offline Measurement 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 Offline Measurement 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 comScore 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 applications users.
Your Digital Analytix account manager or Digital Analytix consultant can provide you with the Publisher
Secret.
Make sure your project includes SystemConfiguration.framework, Security.framework and
AdSupport.framework(4).
If you are targeting versions of iOS older than iOS 6.0, mark AdSupport.framework as Optional in your
projects 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 library.
(4) By using the Ad Support framework, provided by Apple with the introduction of the iOS 6 SDK, comScore can use the Advertising ID to respect an
end users decision to opt-out of measurement/tracking and protect their privacy. The Ad Support framework is the instrument of choice (according to
Apple) for generating statistics and tracking use of the app, even in the cases where an app does not contain advertising. Usage of the Ad Support
framework does not heavily influence the size of the application.
PAGE 5 OF 20
Digital Analytix
Initialization Settings
You must create an initial settings file comScore.plist in the Supporting-Files folder of your project. That file should
contain parameters CustomerC2 and PublisherSecret.
PAGE 6 OF 20
Digital Analytix
All code examples in this document use a sample Client ID value 1000001 and sample Publisher
Secret YourPublisherSecretString. Please make sure you always use the Client ID and
Publisher Secret you have been provided with when copying code from this document.
[CSComScore setCustomerC2:@"1000001"];
(5) ADID is an acronym for Anonymous Device Identifier which is generated by the comScore library.
PAGE 7 OF 20
Digital Analytix
[CSComScore setPublisherSecret:@"YourPublisherSecretString"];
[CSComScore setAppName:@"SampleProject"];
Mode
Tranmission?
CSDEFAULTMODE
CSWIFIONLYMODE
CSNEVERMODE
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).
If you are adding this setting in the comScore.plist settings file, please use values DEFAULT,
WIFIONLY and NEVER, respectively. The values in the settings file are consistent across
platforms.
As an alternative to using the comScore.plist settings file you can also set the LiveTransmissionMode parameter
by using the comScore library API:
[CSComScore allowLiveTransmission:CSDEFAULTMODE];
(6) When using code completion in your project you might notice additional values. The additional values are not supported for this parameter.
PAGE 8 OF 20
Digital Analytix
The offline cache and offline cache flushes require the Offline Measurement module to be
enabled on your Digital Analytix account.
Without the Offline Measurement 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
CSWIFIONLYMODE
Enabled
CSNEVERMODE
Enabled
Never(7)
CSDISABLEDMODE
Disabled(8)
Never
If you are adding this setting in the comScore.plist settings file, please use values DEFAULT,
WIFIONLY, NEVER and DISABLED, respectively. The values in the settings file are consistent
across platforms.
As an alternative to using the comScore.plist settings file you can also set the OfflineTransmissionMode
parameter by using the comScore library API:
[CSComScore allowOfflineTransmission:CSDEFAULTMODE];
You can manually flush the offline cache at any time by using the comScore library API method flushCache:
[CSComScore flushCache];
Please check for connectivity before manually flushing the offline cache.
If you have set OfflineTransmissionMode to CSNEVERMODE 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.
PAGE 9 OF 20
Digital Analytix
[CSComScore setKeepAliveEnabled:NO];
#import "CSComScore.h"
If you are upgrading from a previous comScore SDK implementation then you might have to
change the import statement. Please verify this in your project codes import statements.
Previous versions required the framework to be imported, instead of only the headers.
[CSComScore setAppContext];
If you want to include statements to change any of the initialization settings instead of using the comScore.plist
settings file then please include those statements immediately after setting the application context.
PAGE 10 OF 20
Digital Analytix
[CSComScore onUxActive];
Setting Labels
The 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 comScore library. They will contain
their last known value. You could consider these labels to be application-wide.
Event-specific labels
Event-specific labels will be included to the measurement that is sent for the tagged event. These should be used
for collecting information which only applies to a single event. These labels are not automatically included in any
following measurements. For example, if you add labels to a tagged View event then the labels will only appear in
the corresponding view measurement. Labels that are specified as event-specific will override values for the same
label 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
more details.
PAGE 11 OF 20
Digital Analytix
setLabels
To set one or more persistent labels with a single statement.
Some examples:
Dispatching Application Events on this page for more details on tagging events as well as examples
PAGE 12 OF 20
Digital Analytix
If you think you need to call this method manually then please discuss your situation with your Digital
Analytix account consultant first.
View Event
You may report a View event whenever the application screen changes. In reporting this will correspond with a
measured page impression or page view.
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 comScore library of a View event and provide the page name:
If you want to report a View event without providing any labels then you can simply omit the labels:
[CSComScore view];
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 comScore library of a hidden 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 content
change of fifty percent or more directly caused by user interaction.
PAGE 13 OF 20
Digital Analytix
If you want to report a Hidden event without providing any labels then you can simply omit the labels:
[CSComScore hidden];
Aggregate Event
Aggregate events are somewhat special: they do not generate a measurement (or network request). Instead, any
label(12) you send with this event will be stored in memory instead of being transmitted immediately.
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 comScore library API of an Aggregate event using method aggregateWithLabels. For
example:
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 labels 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
PAGE 14 OF 20
Digital Analytix
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
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 commaseparated 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
PAGE 15 OF 20
Digital Analytix
on page 10. Please also remove any remaining comScore frameworks from your project.
[CSComScore Start];
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
12 for instructions.
From version 2.1306.20 onwards the Start API method no longer needs to be called. The comScore library will
automatically detect the application start. The Start API method has also been renamed to start to comply with
platform coding conventions.
PAGE 16 OF 20
Digital Analytix
Convenience Method
Replacement Code
[CSComScore
StartWithPageName:@"pageName"];
[CSComScore
ViewWithPageName:@"pageName"];
[CSComScore
HiddenWithPageName:@"pageName"];
[CSComScore
StartWithPageName:@"pageName"
andLabels:labelDict];
[CSComScore
ViewWithPageName:@"pageName"
andLabels:labelDict];
[CSComScore
HiddenWithPageName:@"pageName"
andLabels:labelDict];
Old Name
New Name
DEFAULT
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.
PAGE 17 OF 20
Digital Analytix
PAGE 18 OF 20
Digital Analytix
Wireshark Instructions
First, download and install Wireshark from http://www.wireshark.org/download.html and setup Wireshark to sniff
network traffic on your system. The Wireshark installation and setup is described in the Wireshark documentation (the
Wireshark Users Guide) which is also available on the Wireshark download web page(14).
1. Allow Wireshark to sniff network traffic.
2. Share your computers wireless network.
Connect to the internet using an Ethernet cable.
Click on the Airport icon at the top right of the screen, select Create Network; remember the name you give
this network.
Go to System Preferences, open the Sharing pane, highlight (but dont check) Internet Sharing.
Share connection from Ethernet, share computers using AirPort.
Click AirPort Options, and enter the network name you chose above.
Check the Internet Sharing box.
Click Start.
3. Connect your test device to the network you just created.
4. Launch Wireshark.
5. Configure Wireshark to look at the HTTP traffic from your wireless card.
In the menu bar, navigate to Capture > Options.
Interface en1 (which is most likely your wireless card).
Click Capture filter.
Set the filter string to host b.scorecardresearch.com.
Click Start.
If you see HTTP requests matching the above pattern, data is being measured correctly.
Once you have verified the SDK is correctly implemented you must resubmit your application to the iTunes
App Store for approval.
(13) These instructions serve as an example and use OS X. Please refer to Wiresharks online instructions for other environments.
(14) These instructions serve as a short guide. Please refer to Wiresharks online instructions for more details.
PAGE 19 OF 20
Digital Analytix
Will adding the comScore SDK library slow down the application?
No. The comScore code is extremely lightweight and will not affect the performance of your application.
Will comScore receive measurements if my application user is currently roaming?
If an application launches where your user may incur roaming charges, a warning will appear on their screen. When
the application is active and the user has internet connectivity we will receive the measurements.
PAGE 20 OF 20