Nielsen DCR Destination

Segment makes it easy to send your data to Nielsen DCR (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Nielsen DCR in the format they understand. Learn more about how to use Nielsen DCR with Segment.

Getting Started

Nielsen-DCR is supported on mobile apps and web browsers.

Digital Content Ratings (DCR) responds to the shifting, complex multi-platform, multi-device and multi-distribution landscape by providing comprehensive measurement of digital content consumption—including streaming video, static web pages and mobile apps—across all major devices and platforms.

In order to get started with Nielsen-DCR and retrieve an appid to configure this integration, you must sign a license agreement on the Nielsen engineering portal.

There will be an NDA to sign prior to accessing the download. Nielsen requires you fill out your company info and have a Nielsen representative before getting started.

You must also go through the pre-certification process as outlined here with your Nielsen representative before shipping this implementation to production.

Mobile

To get started with Nielsen-DCR and Segment, you’ll want to first integrate your mobile app with our iOS or Android sources.

Nielsen does not host their framework on a dependency management site such as Cocoapods nor Maven. You must manually add the framework after installing the Segment-Nielsen-DCR dependency. Navigate to Nielsen’s Engineering Site and download the Video framework.

iOS

  • Add Segment-Nielsen-DCR to your Podfile
  • Run pod install.
  • Click into Pods > Segment-Nielsen-DCR
  • Click show in Finder
  • Drag Integration files from Classes directory to project in Xcode
  • Select Groups
  • Be sure to select the correct Target Membership

The integration relies on the the Nielsen framework, which is not available on Cocoapods. You must manually include the framework in your project.

Nielsen also requires the following frameworks, which must be included into Link Binary with Libraries (within app target’s Build Phases)

  • AdSupport.framework
  • SystemConfiguration.framework
  • CoreLocation.framework (Not applicable for International (Germany))
  • libsqlite3

Android

  • Add compile 'com.segment.segment-integrations:analytics-android-integration-nielsen-dcr:+ to your gradle
  • Import the integration: import com.segment.analytics.android.integrations.nielsendcr.NielsenDCRIntegration;
  • Register it with the Segment SDK .use(NielsenDCRIntegration.FACTORY)

Nielsen’s SDK is not hosted through a dependency manager. You must manually download the framework and add it to your project.

Import the project: Import Project

Then navigate to the Project Structure, click on the framework and import the jar there: Project Structure

  1. Be sure to put the jar into the libs folder
  2. Right click it and hit ‘Add as library’
  3. Ensure that compile files('appsdk/appsdk.jar') is in your build.gradle file (or compile fileTree(dir: 'libs', include: '*.jar') if you are using many jar files)
  4. Do a clean build (you can probably do this fine in Android Studio, but to make sure navigate in a terminal to the root folder of your app and type ./gradlew clean (this command may be different for you).

Web

If you’d like to measure video on the web, all you have to do is add your App ID in your Segment settings and enable this destination for a JS source. We will load the Nielsen SDK onto your browser.

Screen / Page

Segment supports translating screen or page to Nielsen as a Static App Measurement event. We will translate the following properties to the expected Nielsen metadata:

Segment Property NameNielsenNielsen Description
typetypeRequired. Segment hardcodes 'static'
name *sectionRequired. Section of site
integration optionsegBRequired (optional for web). Segment A.
integration optionsegCRequired (optional for web). Segment B.
integration optioncrossId1Standard episode ID (mobile only)
  • NOTE: For web, we will use the following precedence: 1) [category] [name] 2) [name] 3) 'Loaded a Page'

Track

Segment only supports sending track events as outlined in our Video Spec. To get started tracking video content through Segment, make sure you are using a media player that has an API which allows you to detect the player state such as video or ad plays. For example, you would not be able to collect ad plays using YouTube since their YouTube SDK does not expose any hooks into player states during ad plays.

IMPORTANT: If you do not implement the Segment Video Spec properly with key lifecycle events, this integration will not behave properly.

Again, please also refer to our Video Spec and implement video tracking as outlined there. We will map the semantic events and properties to Nielsen’s relevant methods and metadata.

Heartbeats

Nielsen expects a heartbeat called with playheadPosition during session play every second until the stream is completed, paused or interrupted (due to ad breaks or buffering).The playhead position is the current location in seconds of the playhead from the beginning of the asset.

Segment will set a timer and to call this heartbeat event (–(void) playheadPosition: (long long) playheadPos), setTimeout (web)) every second in background. You do NOT have to call the Segment equivalent heartbeat event (Video Content/Ad Playing) each second. You should follow our spec and call the Segment heartbeat event every 10 seconds (recommended). While we will keep state of our own playhead position for these background hearbeats, when we do receive an explicit Segment heartbeat event, we will respect its properties.position and restart the background heartbeats from that position.

Playback Events

When you call Video Playback Started and Video Playback Resumed, Segment will call the Nielsen-DCR play method with the relevant channelInfo:

NSDictionary *channelInfo = @{
                                      // channelName is optional for DCR, if not present Nielsen asks to set default
                                      @"channelName" : options[@"channelName"] ?: @"defaultChannelName",
                                      // if mediaURL is not available, Nielsen expects an empty value
                                      @"mediaURL" : options[@"mediaUrl"] ?: @""
                                      };
(void) play: (id) channelInfo;

From there we will map to the relevant events on the instance as outlined below:

Nielsen-DCR SpecSegment Video Spec
–(void) stop and Heartbeat timer stoppedVideo Playback Paused
–(void) stop and Heartbeat timer stoppedVideo Playback Interrupted
Heartbeat timer stoppedVideo Playback Buffer Started
Heartbeat timer updatedVideo Playback Buffer Completed
Heartbeat timer stoppedVideo Playback Seek Started
Heartbeat timer updatedVideo Playback Seek Completed
-(void) end and Heartbeat timer stoppedVideo Playback Completed

Segment-Nielsen-DCR does not map any playback properties.

Content Events

Nielsen-DCR SpecSegment Video Spec
–(void)loadMetadata:(id)metadata;Video Content Started
Heartbeat timer updatedVideo Content Playing
–(void) end and -(void) stopVideo Content Completed

Content Properties (Labels)

Nielsen-DCR metadataSegment Property
assetidasset_id
programprogram
titletitle
segBoptions.segB
segCoptions.segC
airdateairdate
isfullepisodefull_episode
lengthtotal_length
pipmodeoptions.pipmode
type'content' (hardcoded)

Please take note that iOS and Android expect different casing. We expect snake_case for iOS and camelCase for Android.

Ad Events

The Segment-Nielsen-DCR integration has logic to check for type in case of a preroll ad. If the type is preroll, Segment calls Nielsen’s loadMetadata method with metadata values for content followed by loadMetadata with ad (preroll) metadata. Otherwise, Segment simply calls loadMetadata with the ad metadata.

Nielsen-DCR SpecSegment Video Spec
–(void)loadMetadata:(id)metadata; and Heartbeat timer startedVideo Ad Started
Heartbeat timer updatedVideo Ad Playing
–(void) stop and Heartbeat timer stoppedVideo Ad Completed
Nielsen-DCR Ad metadataSegment Property
assetidasset_id
typetype
titletitle
Nielsen-DCR Ad Content metadataSegment Property
assetidasset_id
adloadtypeoptions.ad_load_type
typecontent (hard coded)
titletitle
programprogram
segBoptions.segB
segCoptions.segC
airdateairdate
isfullepisodefull_episode
lengthtotal_length
pipmodeoptions.pipmode

Please take note that iOS and Android expect different casing. We expect snake_case for iOS and camelCase for Android.

Integration Specific Options

Example on passing destination specific option values through on iOS

options:@{
  @"integrations": @{
   @"nielsen-dcr" : @{
     @"pipmode" : @"2017-05-22",
     @"ad_load_type": @"c3 value",
     @"channel_name: @"c4 value",
     @"media_url" : @"c6 value",
     @"cross_id_1": @"cross id value"
    }
  }
}

Example for Android:

Map<String, Object> nielsenOptions = new LinkedHashMap<>();
nielsenOptions.put("pipmode", "c3 value");
nielsenOptions.put("adLoadType", "c4 value");
nielsenOptions.put("channelName", "c6 value");
nielsenOptions.put("mediaUrl", "c6 value");
nielsenOptions.put("crossId1", "cross id value");


Analytics.with(context).track("Video Playback Started", new Properties(), new Options().setIntegrationOptions("nielsen-dcr", nielsenOptions));

Pipmode

Current state of picture-in-picture (PIP) mode on device. Pass in true if the video measurement is displayed in PIP mode. Otherwise, Segment defaults to false if no value is present.

Ad load type

Type of ad load. Pass in dynamic to indicate Dynamic Ad Insertion (DAI). Otherwise, Segment defaults to linear.

Channel Name and Media URL

The SDK is started by calling the play API with the channelName and mediaURL parameters. If no value is passed in, Segment defaults to defaultChannelName for channelName and an empty String for mediaURL.

Cross Id 1

Standard episode ID.

Settings

AppID

Once the Segment source is integrated with your app, toggle Nielsen-DCR on in your Segment destinations catalog, and add your AppID, which you can retrieve from your Nielsen representative.

The AppID is the unique id for the application assigned by Nielsen. It is GUID data type. Be sure to use the test App ID during development, test, and certification processes. Use Production appid to submit app to App / Play store, after receiving Nielsen certification.

These new settings will take up to an hour to propagate to all of your existing users. For new users it’ll be instantaneous.

Instance Name

Enable Production Mode - SF code

Nielsen collection facility to which the SDK should connect. We default to a development environment, so you must explicitly turn this on once you have everything ready for production. You will also want to be sure to get approved by your Nielsen representative before shipping your app to production.

FAQ

How do you determine App Name?

Segment-Nielsen-DCR iOS retrieves the application name from your app’s Info.plist application bundle name as returned by CFBundleName .

For Android, we retrieve the name of the application package from the PackageManager).

How do you determine App Version?

Segment-Nielsen-DCR retrieves the application version from your app’s Info.plist application bundle name as returned by CFBundleVersion.

For Android, we retrieve the version of the application package from the PackageManager).

What are the Nielsen-DCR clientId and subbrand values?

The Parent Client ID and Sub-Brand (VCID) values are automatically populated through the AppID, which is Nielsen Supplied. By default, clientid and subbrand are setup in Nielsen backend configuration to capture brand and sub-brand information. The fields get populated from backend for a registered client appid.


Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

This destination requires a Device-based Connection Mode for Mobile data. Follow the steps above to ensure you have packaged the Nielsen DCR SDK with Segment’s.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

AppID

Enter your Nielsen DCR App ID.

Instance Name

You can optionally define the explicit name of the Nielsen instance we initialize its SDK with.

Enable Production Mode

Enabling this setting will disable debug mode. By default we will use production mode. Uncheck this setting if you are developing or testing this integration.


If you have any questions, or see anywhere we can improve our documentation, please let us know!