How can we help you?

Implement the Library- iOS

The implementation foriOS applications, iOS extensions, tvOS applications and watchOS applicationsinvolves the following steps:

1. Include the comScore library in the application project.

2. Update application project configuration as needed for the library to provide all its functionality.

3. Add code statements to configure and start the library.

4. If you are tagging atoday-extensioniOS extension, then add code statements to tag the application life cycle (i.e., foreground and background transitions).

5. Add code statements to tag a user experience as needed (i.e., video and/or audio content playback).

As you work with the library you might see classes, methods and properties which do not appear in this documentation. Those elements are typically exposed because that is necessary for the library to work in the way it is intended to or to support customized implementations for which you would receive separate instructions from your comScore account team or comScore Tag Support. The use of those elements without instructions from comScore could severely impact the behavior of the comScore library, the quality of the collected data or reporting capabilities.

If you have any questions or concerns about the instructions in this document or about any classes, methods or properties which you find in the comScore library then please contact your comScore account team or comScore Tag Support.

Include the Library in Your Application Project

The library is delivered as three frameworks: one for iOS targets, one for tvOS targets and another one for watchOS targets. To begin, the appropriateComScore.frameworklibrary must be included in your application project. A typical way to achieve this is by including the comScore library viaCocoaPods. Using CocoaPods also makes updating the comScore library to a newer version much easier compared to manually including the library in your application project.

If you are already using CocoaPods then you can include the comScore library in your project by adding the following line in your Podfile:

If you are not yet using CocoaPods and would like to start using it for managing third party library dependencies, then please follow the instructions on the CocoaPods website (

For Projects Using Objective-C

Xcode will likely suggest to import headers when you address the library in your code. Please make sure to import the header file <ComScore/ComScore.h>in any locations where you need to access the library:

For Projects Using Swift To import the library in a project using Swift you need a bridging header to expose the classes in the library in your Swift code. If you have other Objective-C code in your Swift project then you will already have a bridging header file. Otherwise you will need to create it according to Apple’s instructions for adding Objective-C code to the Swift version used in your project.

When created, the bridging header file will typically be named after your project - or module - with the suffix-bridging-header.h. Please make sure to include the following statement in the bridging header file, to have the comScore library classes exposed in your Swift project:

AddAdSupport.frameworkto Your Project Target(s)

It is advised to addAdSupport.frameworkto your project target(s) even if the application does not contain advertisements because this will improve the collected data. However, the comScore library does not requireAdSupport.frameworkto function correctly (i.e., adding this framework is optional).

Configure and Start the comScore Library

It is strongly advised to configure and start the comScore library from within the application didFinishLaunchingWithOptionsmethod in an application project using Objective-C, or the equivalent location in a project using Swift.

If you are tagging an iOS watchapp extension then please configure and start the library inside either the awakeWithContext method orinitmethod of your extension’s main ViewController.

If you are tagging any other kind of iOS extension then please configure and start the library inside viewDidLoadof your extension’s mainViewController.

The library is configured by providing publisher configuration settings, prior to starting the library.

Available Publisher Configuration Settings

The configuration settings which can be freely used to configure the comScore library are explained below. Please do not use any other configuration settings without instructions from your comScore account team or comScore Tag Support.

Provide your Publisher ID value. The Publisher ID is often also referred to as theClient IDorc2 value.

Provide a string with your Publisher Secret value.

By default the comScore library retrieves the application name from your application’s Info.plist application bundle name as returned byCFBundleName. Should you want to override the automatically retrieved value then you can provide a string with your preferred application name.

This setting controls if the comScore library will update usage times at a regular interval. The available modes on the enum are:

Update usage times only when the application is in the foreground. This is the default mode.

Update usage times when the application is in the foreground and when the application is in the backgroundwhile providing a user experience. If your application can provide a user experience in the background then the mode should be changed to this mode for the best possible measurement of application usage time. Please refer to the Application User Experienceon for more details about user experiences.

SCORUsagePropertiesAutoUpdateModeDisabled SCORUsagePropertiesAutoUpdateModeDisabled  Do not update usage times. It is not advised to configure the library to use this mode.

The interval in seconds at which the comScore library automatically updates usage times if the auto-update is enabled. The default value is 60, which is also the minimum value.

Apply Publisher Configuration Settings The appropriate values for your configuration settings are assigned on a SCORPublisherConfigurationobject using the Builderpattern, after which the SCORPublisherConfigurationobject is provided to the configuration on the SCORAnalyticssingleton object:

Start the comScore Library

To start the library add this code statement after the configuration is provided:

For Projects using Objective-C

For Projects using Swift

Tag the Application User Experience

If your application or extension can provide a user experience – like the playback of music or video –while the application is in the background, then it is particularly important to implement calls to the user experience notification methods on the comScore library API for the correct measurement of usage time during background activity.

For example, to notify the library of the start of playback of audiovisual content:

For Projects using Objective-C

For Projects using Swift

Tag Application Section Changes

Please note that the instructions in this section are entirely optional. You only need to follow these instructions if you want metrics to be reportable per section of your application.

To have metrics reported per section of your application, you can notify the comScore library when the user changes sections by calling the application event notification method notifyViewEvent. ThenotifyViewEventcan be supplied with a Dictionaryargument, of which the key/value pairs specify theEvent-specific Labels.

Labelsare name/value pairs used to collect data. For this application event notification the name of the section the user has changed to should be provided with aLabelcalledns_category. You should work with your comScore account team to establish what the ns_categorylabel values should be, based on your desired dictionary goals.

Please make sure to always call the application event notification method and provide the label ns_categorywith a suitable value whenever your application changes toanothersection. When the user changes to general sections of your application — such as a home screen or a startup splash screen — then please use an empty string as the value of label ns_category.

Please use section names which are suitable for your application. The following example uses a section name value "news" for labelns_category:

For Projects using Objective-C

For Projects using Swift

 Next: Test your Implementation







Was this article helpful?
0 out of 0 found this helpful



Article is closed for comments.