The implementation for Android applications involves the following steps:
- Include the comScore library in the application project.
- Update application project configuration as needed for the library to provide all its functionality.
- Add code statements to configure and start the library.
- If your application is targeted to be used on devices with Android versions below 4.0.0 (i.e., API level 13 or lower), then add code statements to tag the application life-cycle (i.e., foreground and background transitions).
- 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.
The library should be implemented in the application in such a way that it can capture application starts and usage data. If your application uses multiple processes or contains background services, then your implementation might require special attention.
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
To begin, the comscore.aar library file must be included in your application project. A typical way to achieve this is by including the comScore library from comScore's Maven repository. Using the Maven repository also makes updating the comScore library to a newer version much easier compared to manually including the library in your application project. How you include libraries from the Maven repository depends on the development environment you are using, like Android Studio IDE.
With Android Studio IDE you can configure Gradle to include the comScore library from the Maven repository by adding the following to the gradle.build file of your application project:
- The URL of the Maven repository containing the comScore library, which is https://comscore.bintray.com/Analytics.
- A dependency to compile a module for the comScore library as part of the application, using com.comscore:androidanalytics:5.+ as the identifier.
The following example shows what the relevant parts of your gradle.build file could look like:
Configure and Start the comScore Library
It is strongly advised to configure and start the comScore library from within the Application.onCreate() method(4). The application lifecycle tagging involves the use of notification methods on the library API, which could be executed when the application comes to foreground or goes to background. Those actions can happen at any time, even as the application is being started.
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 the Client ID or c2 value.
Provide a string with your Publisher Secret value.
By default the comScore library retrieves the application name from your application’s label, as returned by the android.content.pm.PackageManager.getApplicationLabel() method. 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:
UsagePropertiesAutoUpdateMode.FOREGROUND_ONLY
Update usage times only when the application is in the foreground. This is the default mode.
UsagePropertiesAutoUpdateMode.FOREGROUND_AND_BACKGROUND
Update usage times when the application is in the foreground and when the application is in the background while 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 Tag the Application User Experience for more details about user experiences.
UsagePropertiesAutoUpdateMode.DISABLED
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 PublisherConfiguration object using the Builder pattern, after which the PublisherConfiguration object is provided to the configuration on the Analytics singleton object:
Start the comScore Library
To start the comScore library it is required to provide a reference to the current Context. After the configuration is provided add this code statement:
Tag the Application Life Cycle
To collect analytics data about application usage on devices with Android versions below 4.0.0 (i.e., API level 13 or lower), the comScore library needs to be notified when the application goes to foreground and background by calling the application life cycle notification methods.
This is an example of how calls to the application life cycle API methods can be implemented inside the Activity classes in your application:
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. The notifyViewEvent can be supplied with a HashMap argument, of which the key/value pairs specify the Event-specific Labels.
Labels are 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 a Label called ns_category. You should work with your comScore account team to establish what the ns_category label 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_category with a suitable value whenever your application changes to another section. 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 label ns_category:
Next: Test your Implementation
0 Comments