Documente Academic
Documente Profesional
Documente Cultură
Digital Analytix
Contents
Implementation Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tagging
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Tag
4
4
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Intended Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
. . . . . . . . . . . . . . . . . . . . . . . 9
. . . . . . . . . . . . . . . . . . . . . . . . . . . 10
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Hidden Event
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Aggregate Event
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
PAGE 2 OF 22
Digital Analytix
Include the
Checklist on
page 5).
3. Import the CSComScore.h headers in your code (see
4. Set the application context by including the following call inside application
didFinishLaunchingWithOptions (see
[CSComScore setAppContext];
5. Set library configuration parameters by calling the following API methods immediately after setting the application
context (see
needed.
6. Please set label ns_site and any other persistent labels right after setting the application context and the
configuration parameters (see
8. Enable the auto-update feature to improve measurement of usage times by calling the enableAutoUpdate
method (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 22
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 comScore's 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 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.
PAGE 4 OF 22
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 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.
PAGE 5 OF 22
Digital Analytix
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
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.
PAGE 6 OF 22
Digital Analytix
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.
PAGE 7 OF 22
Digital Analytix
Please include the call to the setAppContext as well as any statements with Application Tag library
configuration parameter settings inside application didFinishLaunchingWithOptions
didFinishLaunchingWithOptions. The
configuration parameters are discussed in
(4) The examples in this document use Client ID value 1000001 which is an example value. Please make sure you use your assigned comScore
Client ID instead.
(5) ADID is an acronym for Anonymous Device Identifier which is generated by the Application Tag library.
PAGE 8 OF 22
Digital Analytix
Mode
Transmission?
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).
You can set the LiveTransmissionMode parameter as follows:
[CSComScore
CSComScore allowLiveTransmission:CSDEFAULTMODE];
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
CSWIFIONLYMODE
Enabled
CSNEVERMODE
Enabled
Never(7)
CSDISABLEDMODE
Disabled(8)
Never
(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).
PAGE 9 OF 22
Digital Analytix
[CSComScore
CSComScore allowOfflineTransmission:CSDEFAULTMODE];
You can manually flush the offline cache at any time by using the flushCache API method:
[CSComScore
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 10 OF 22
Digital Analytix
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
page 10). Similarly, when you call onUxInactive the auto-update feature will automatically deactivate while the
application is in the background.
[CSComScore
CSComScore enableAutoUpdate:120 foregroundOnly:NO]; // Interval at 2 minutes during fore- and background.
[CSComScore
CSComScore enableAutoUpdate:300 foregroundOnly:YES]; // Interval at 5 minutes, only during foreground.
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 Application Tag library. They will
contain their last known value. You could consider these labels to be application-wide.
PAGE 11 OF 22
Digital Analytix
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
Dispatching Application Events on page 13 for more details on tagging events as well as examples
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:
setAutoStartLabel
To set a single event-specific label for the automatically generated Application Start event.
PAGE 12 OF 22
Digital Analytix
setAutoStartLabels
To set one or more event-specific labels for the automatically generated Application Start event with a single
statement.
Any labels set via these methods will only be included in the automatically generated Application Start event as
event-specific labels.
Some examples:
41.
42.
43.
44.
45.
46.
47.
48.
49.
dictionaryWithObjectsAndKeys:
@"labelName1",
@"labelName2",
@"labelName3",
PAGE 13 OF 22
Digital Analytix
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
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.
52.
53.
54.
[CSComScore
CSComScore startWithLabels:[NSDictionary
NSDictionary dictionaryWithObjectsAndKeys:
@"start", @"name",
@"my sample value", @"mycustom",
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 content
change of fifty percent or more directly caused by user interaction.
PAGE 14 OF 22
Digital Analytix
[CSComScore
CSComScore viewWithLabels:[NSDictionary
NSDictionary 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:
[CSComScore
CSComScore view];
(12) According to the iOS Programming Guide an application is considered active when the application is running in the foreground and is receiving
events, which is the normal mode for foreground applications. Please refer to the
(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 programming
conventions and decide on which additional labels you want to include in the reported View event.
PAGE 15 OF 22
Digital Analytix
111.
112.
113.
114.
115.
116.
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
131.
132.
133.
134.
- (void
void) viewDidAppear:(BOOL)animated {
[super
super viewDidAppear:animated];
[self
self sendView];
[[NSNotificationCenter
NSNotificationCenter defaultCenter] addObserver:self
self
selector:@selector(sendView)
name:UIApplicationDidBecomeActiveNotification
UIApplicationDidBecomeActiveNotification
object
object:nil
nil];
}
- (void
void) viewDidDisappear:(BOOL)animated {
[super
super viewDidDisappear:animated];
[[NSNotificationCenter
NSNotificationCenter defaultCenter] removeObserver:self
self
name:UIApplicationDidBecomeActiveNotification
UIApplicationDidBecomeActiveNotification
object
object:nil
nil];
}
- (void
void) sendView {
[CSComScore
CSComScore viewWithLabels:[NSDictionary
NSDictionary dictionaryWithObjectsAndKeys:
@"my.view.name", @"name",
nil
nil]];
}
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:
[CSComScore
CSComScore hiddenWithLabels:[NSDictionary
NSDictionary 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:
[CSComScore
CSComScore 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.
PAGE 16 OF 22
Digital Analytix
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:
[CSComScore
CSComScore aggregateWithLabels:[NSDictionary
NSDictionary 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
PAGE 17 OF 22
Digital Analytix
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 18 OF 22
Digital Analytix
on page 7. Please also remove any remaining comScore frameworks from your project.
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
13 for instructions.
PAGE 19 OF 22
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 20 OF 22
Digital Analytix
(15) A cold start is defined as starting the application while the application was not running in the foreground or background.
PAGE 21 OF 22
Digital Analytix
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
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
PAGE 22 OF 22