Engineering Client Portal - User contributions [en]

loadMetadata

2019-03-03T16:45:03Z

ShaneHartman: updated VCID key name to subbrand

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|iOS SDK API Reference}} {{CurrentBreadcrumb}}
[[Category:Digital]]
[[Category:iOS SDK API Reference]]
The application uses this API to send metadata to the SDK. App constructs a JSON dictionary and calls loadMetadata. The API that accepts the JSON string has been deprecated.

In case of a preroll ad, call loadMetadata with metadata values for content followed by loadMetadata with ad (preroll) metadata.

== Syntax ==
<syntaxhighlight lang="objective-c">
– (void)loadMetadata:(id)metadata;
</syntaxhighlight>

== Input Parameters ==
{| class="wikitable"
|-
! Parameter !! Description !! JSON Object
|-
| rowspan=10 | jsonMetaData
| '''DTVR'''
| <syntaxhighlight lang="objective-c">
NSDictionary *metadata = @
{
@"adModel": @"1"
};
</syntaxhighlight>
|-
|'''DAR'''
type should always be “ad” for DAR
|
<syntaxhighlight lang="objective-c">
NSDictionary *metadata = @
{
@"type": @"ad",
@"ocrtag": @"http://secure-gl.imrworldwide.com/cgi-bin/m?ci= ENTXX5&am=3&ep=1&at=view&rt=banner&st=image&ca=cmp97144&cr=1186239&pc=3739659&r=2011370876"
};
</syntaxhighlight>
|-
|'''Digital Audio'''
type should always be “radio”. See [[Digital Audio Metadata]].
| <syntaxhighlight lang="objective-c">
NSDictionary *metadata = @
{
@"dataSrc": @"cms",
@"type": @"radio",
@"assetid": @"WXYZ-FM",
@"stationType": @"3",
@"provider": @"MyRadioProvider"
};
</syntaxhighlight>
|-
|'''DCR'''
type should be “content”, “static”, “preroll”, “midroll” or “postroll”.
|
<syntaxhighlight lang="objective-c">
// Audio & Video Measurement:
NSDictionary *metadata = @
{
@"type": @"content",
@"assetid": @"vid345-67483",
@"program": @"ProgramName",
@"title": @"Program S3, EP1",
@"length": @"3600",
@"segB": @"CustomSegmentValueB",
@"segC": @"CustomSegmentValueC",
@"crossId1": @"Reference11",
@"crossId2": @"Reference22",
@"subbrand": @"cXX",
@"isfullepisode": @"y",
@"airdate": @"20161013 20:00:00",
@"adloadtype": @"2"
};
</syntaxhighlight>
<syntaxhighlight lang="objective-c">
// Static Measurement:
NSDictionary *metadata = @
{
@"type": @"static",
@"section": @"siteSection",
@"segA": @"segmentA",
@"segB": @"segmentB",
@"segC": @"segmentC",
@"crossId1": @"Reference11"
};
</syntaxhighlight>
<syntaxhighlight lang="objective-c">
// Ad Measurement:
NSDictionary *metadata = @
{
@"type": @"preroll",
@"assetid": @"AD361-84413",
@"title": @"MyAdName"
};
</syntaxhighlight>

|-
|'''DCR Germany'''
type should be "content", "static", "preroll", "midroll" or "postroll".
| <syntaxhighlight lang="objective-c">
NSURL *url = [NSURL URLWithString:@"http://nielsense-assets.s3.amazonaws.com/id3/001/prog_index.m3u8"];
NSDictionary *assetInfoDict = @
{
//SDK Metadata
@"type": @"content",
@"assetid": @"vid345-67483",
@"program": @"ProgramName",
@"title": @"Program S3, EP1",
@"length": @"3600",
@"segB": @"CustomSegmentValueB",
@"segC": @"CustomSegmentValueC",
@"crossId1": @"Reference11",
@"crossId2": @"Reference22",
@"subbrand": @"cXX",
@"isfullepisode": @"y",
@"airdate": @"20161013 20:00:00"

//Custom Properties
@"nol_c{number}": @"p{Number},value"
};
[nielsenMeter loadMetadata:assetInfoDict];

//Ad Measurement:
//SDK Metadata
NSDictionary *assetInfoDict = @
{
@"type": @"preroll",
@"assetid": @"AD361-84413",
@"title": @"MyAdName"

//Custom Properties
@"nol_c{number}": @"p{Number},value"
};
[nielsenMeter loadMetadata:assetInfoDict];
</syntaxhighlight>
|}

== Output Parameters ==
{| class="wikitable"
|-
! Output Parameters (Return value) !! Description
|-
| Void ||
|}

setPlayheadPosition (Browser)

2019-01-10T18:37:02Z

ShaneHartman: updated input parameter to reflect spec for live playhead position

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Browser SDK API Reference}} {{CurrentBreadcrumb}}
[[Category:Digital]]
[[Category:Browser SDK API Reference]]
For situations where CMS data is used in conjunction with Nielsen’s SDK, the application needs to call <code>setPlayheadPosition</code> in the SDK every second. For proper reporting, the SDK should:
*Receive a playhead position update every second on the playback of content.
*Not receive playhead updates when the content playback is paused, is being buffered, or stopped.
'''When streaming VOD (Video On Demand)''', the playhead position is the current location of the player from the beginning of the asset in seconds (0, 1, 2, 3, …).
'''When streaming live content,''' the playhead position passed is the current Unix timestamp (seconds since Jan-1-1970 UTC).
'''For Digital Audio streaming Live or On Demand content,''' the playhead position passed is the current Unix timestamp (seconds since Jan-1-1970 UTC).

== Syntax ==
<syntaxhighlight lang="javascript">
ggPM('49', playheadposition); //For VA users only
</syntaxhighlight>

'''International (Germany) implementation'''
<syntaxhighlight lang="javascript">
ggPM("setPlayheadPosition", playheadposition); // Except VA users
</syntaxhighlight>

== Input Parameters ==
{| class="wikitable"
|-
! Parameter !! Description
|-
| event || setPlayheadPosition
|-
| playheadposition || An Integer value representing the time in content in seconds (VOD – Video On Demand) or the current Unix timestamp (seconds since Jan-1-1970 UTC) (live).
|}

== Notes ==
The playhead position must be passed as an integer in parameter 2. Send the progress event to SDK at an interval not greater than 10 seconds, when the content is playing. An interval of one second is recommended for most implementations. For accurate time tracking, it is important to send the whole range of playhead positions from the player.
*If playing starts at zero, pass the first value as zero (not ‘one’).
*When the player is paused or stopped, send <code>setPlayheadPosition</code> along with the respective [[stop (Browser)|stop]] / [[end (Browser)|end]] to the SDK.

=== Video On Demand Content ===
<syntaxhighlight lang="javascript">
ggPM(setPlayheadPosition, setPlayheadPosition);
</syntaxhighlight>

=== Live Content through JavaScript ===
<syntaxhighlight lang="javascript">
ggPM(setPlayheadPosition, (Date.now()/1000));
</syntaxhighlight>

=== Live Event through Flash ===
<syntaxhighlight lang="javascript">
ggCom.getInstance().PM('setPlayheadPosition',Math.floor((new Date()).getTime()/1000));
</syntaxhighlight>

playheadPosition

2019-01-10T18:35:33Z

ShaneHartman: updated input parameter to reflect spec for live playhead position

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|iOS SDK API Reference}} {{CurrentBreadcrumb}}
[[Category:Digital]]
[[Category:iOS SDK API Reference]]

For situations where CMS data is used in conjunction with Nielsen SDK the application needs to call the <code>playheadPosition</code> in the SDK every one second until a pause / stop. The playhead position is the current location in seconds of the playhead from the beginning of the asset.

== Syntax ==
<syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos
</syntaxhighlight>

== Sending playheadposition for content ==
<syntaxhighlight lang="objective-c">
AVPlayer *player;
CMTime curTime=[player currentTime];
int pos = CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

== Sending playheadposition for ad ==
<syntaxhighlight lang="objective-c">
CMTime curTime=[adplayer currentTime];
long pos=CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

<blockquote>'''Note:''' In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] & playhead position and through <code>playheadPosition</code>.</blockquote>

== Input Parameters ==
{| class="wikitable"
|-
! Parameter !! Description
|-
| playheadPos || An Integer value representing the time in content in seconds (VOD – Video On Demand) or the current Unix timestamp (seconds since Jan-1-1970 UTC) (live).
|}

== Output Parameters ==
{| class="wikitable"
|-
! Output Parameters (Return value) !! Description
|-
| Void ||
|}

== Notes ==
The player application must send the value of the playhead to the SDK every one second. The player application can schedule a timer with a one-second-period in a timer event and send the playhead position.

=== Buffering state ===
*Do not supply playhead position while the content is being buffered.
*If the content is in buffering state continuously for more than 30 seconds, call [[stop]] API.

=== Live Content ===
<syntaxhighlight lang="objective-c">
long long pos = [[NSDate date] timeIntervalSince1970];
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

=== On-demand Content ===
<syntaxhighlight lang="objective-c">
CMTime curTime=[player currentTime];
long pos=CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

=== Ad Content ===
<syntaxhighlight lang="objective-c">
CMTime curTime=[adplayer currentTime];
long pos=CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

<blockquote>'''Note:''' The playhead positions for ad and content should be maintained separately.</blockquote>
<blockquote>'''Note:''' If playhead is not available from audio / video measurement, allow the app to start a timer (1-5 seconds) and send playhead position to SDK based on the timer event. Once the actual playhead is available, let the app send the proper playhead position. This allows the SDK to calculate and provide a closer value for duration.</blockquote>

Digital Measurement Metadata

2018-06-05T20:18:10Z

ShaneHartman: Added decimal and trailing zero to length parameter

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

The metadata received for each asset is used for classification and reporting. There are reserved Nielsen keys for collecting the required metadata.

=== Reserved Keys ===
Content and Ad Metadata can be passed through key-values using the Nielsen reserved keys. The last column in the table below indicates metadata parameters that will be displayed in reporting.

==== Content Metadata ====
{| class="wikitable"
|-
! Key
! Description
! style="width: 14%;" | Values
! style="width: 12%;" | Required for Audio/Video?
! style="width: 12%;" | Required for Static (page)?
! Reported for
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| subbrand || VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| type ||
Type of measurement:
*audio / video – "content"
*page – "static"
*ad – "preroll", "midroll" or "postroll"
|| "content", "static" || Mandatory || Mandatory ||
|-
| assetid || ID assigned to content. Must be unique across all content at the episode level. || custom (no [[Special Characters]]) || Mandatory || Not Required ||
|-
| section || Section of site || custom || Not Required || Mandatory ||
|-
| isfullepisode || Full episode flag ||
*"y" or "lf" - full episode
*"n" or "sf" - short form
|| Mandatory || Not Required ||
|-
| program || Program name || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| title || Episode title || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| length || Length of content in seconds for VOD. 86400 may be used for Live content if the exact content length is not known. || custom || Mandatory || Not Required ||
|-
| segA || Segment A (this is not available for audio / video Measurement reporting as the episode title is reported) || custom || Not Required || Not Required || Static Measurement
|-
| segB || Segment B || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| segC || Segment C || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| crossId1 || Standard episode ID. Gracenote/TMS ID should be used when available. Must be unique per episode. || custom || Optional || Not Required ||
|-
| crossId2 || Content originator (required only for distributors) || custom || Optional || Not Required ||
|-
| airdate || Original (local) air date and time (Eastern Time for US) || YYYYMMDD HH24:MI:SS || Mandatory || Not Required ||
|-
| pipmode ||
Current state of picture-in-picture (PIP) mode on device.
*"true" if audio / video measurement is displayed in PIP mode
*"false" if audio / video measurement is displayed in regular mode
|| "true", "false" || Optional || Not Required || Audio / Video Measurement
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory || Not Required ||
|-
| progen || Genre (required only for non-TV originated content). See [[DCR OTT Genre List]] for acceptable values. || e.g. DD for Daytime Drama || Required for non-TV content || Not Required
|}

'''clientid & subbrand (vcid)'''
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. But if an app contains multiple brands and sub-brands and client is willing to give credit to another brand or sub-brand then :
*Client app developer can override the clientid and subbrand (brand and sub-brand info.) in [[loadMetadata]] call to get a proper measurement for a desired brand and sub-brand.
**If no clientid and subbrand are specified in CMS of a content and an ad, default values reported in the Configuration will be reported.
**If clientid and subbrand are specified in CMS of the content or ad, the most recent clientid and subbrand will be reported in subsequent pings. To report with a different clientid and subbrand, include the new values for the keys in their subsequent [[loadMetadata]] call.
'''Picture-in-picture (PIP) mode'''
Once the app detects PIP mode, call [[loadMetadata]] with the same set of assetids, values and with one additional parameter "pipmode": "true". Once PIP mode is disabled in the device, call [[loadMetadata]] again with "pipmode":"false".

==== Custom Variables Extension ====
Contact Nielsen Technical Account Manager (TAM) to configure any custom variables, as needed for implementing the application.

See [[Custom Variables Extension]] for more information.

==== Advertisement Metadata ====
{| class="wikitable"
|-
! Key !! Description !! Values !! Required for Audio / Video? !! Required for Static (page)
|-
| type || Type of ad || "preroll"
"midroll"
"postroll"
|| Mandatory || Not Required
|-
| assetid || An ID assigned to the advertisement. Can be an internal ID, an ID provided by the ad server, or a randomly generated ID. Must be unique across all ads || custom || Mandatory || Not Required
|-
| title || Title of the advertisement || "MyAdName" || Mandatory || Not Required
|}

=== Passing Metadata ===
The required metadata can be passed as key values through the loadMetadata method. The sample code below shows a metadata objects for various assets.
'''Audio / Video Measurement Asset'''
Type should be "content"
<syntaxhighlight lang="json"> {
"type": "content",
"assetName": "myassetName",
"length": "300.0",
"title": "myTitle",
"program": "myProgram",
"censuscategory": "myCensusCategory",
"assetid": "myAssetId",
"channelName": "myChannel",
"adloadtype": "2",
"segB": "segmentB",
"segC": "segmentC",
"isfullepisode":"y",
"crossId1": "Reference11",
"crossId2": "Reference22",
"airdate": "20161013 20:00:00"
}</syntaxhighlight>

'''Static (Page) Measurement Asset'''
Type should be "static"
<syntaxhighlight lang="json"> {
"type": "static",
"assetid": "static123",
"assetName": "Page-Asset",
"section": "siteSection",
"segA": "segmentA",
"segB": "segmentB",
"segC": "segmentC"
}</syntaxhighlight>

'''For any of the ad types'''
<syntaxhighlight lang="json"> {
"type": "midroll",
"length": "30.0",
"assetid": "myMidrollAssetId",
"adloadtype": "2",
"tv": "true",
"dataSrc": "cms"
}</syntaxhighlight>
<blockquote>'''Note''': In case the individual ad details are not available, send ad pod (presence) details through the <code>loadMetadata</code> and playhead position through <code>setPlayheadPosition</code>.</blockquote>

'''loadMetadata'''
The object can then be passed when calling [[loadMetadata]].
<syntaxhighlight lang="java"> loadMetadata(jsonMetadataObject);</syntaxhighlight>

Digital Measurement Metadata

2018-05-30T17:54:37Z

ShaneHartman: changed key for VCID to subbrand as this is the default name

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

The metadata received for each asset is used for classification and reporting. There are reserved Nielsen keys for collecting the required metadata.

=== Reserved Keys ===
Content and Ad Metadata can be passed through key-values using the Nielsen reserved keys. The last column in the table below indicates metadata parameters that will be displayed in reporting.

==== Content Metadata ====
{| class="wikitable"
|-
! Key
! Description
! style="width: 14%;" | Values
! style="width: 12%;" | Required for Audio/Video?
! style="width: 12%;" | Required for Static (page)?
! Reported for
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| subbrand || VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || custom || Optional || Optional || Audio / Video and Static Measurement
|-
| type ||
Type of measurement:
*audio / video – "content"
*page – "static"
*ad – "preroll", "midroll" or "postroll"
|| "content", "static" || Mandatory || Mandatory ||
|-
| assetid || ID assigned to content. Must be unique across all content at the episode level. || custom (no [[Special Characters]]) || Mandatory || Not Required ||
|-
| section || Section of site || custom || Not Required || Mandatory ||
|-
| isfullepisode || Full episode flag ||
*"y" or "lf" - full episode
*"n" or "sf" - short form
|| Mandatory || Not Required ||
|-
| program || Program name || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| title || Episode title || custom || Mandatory || Not Required || Audio / Video Measurement
|-
| length || Length of content in seconds for VOD. 86400 may be used for Live content if the exact content length is not known. || custom || Mandatory || Not Required ||
|-
| segA || Segment A (this is not available for audio / video Measurement reporting as the episode title is reported) || custom || Not Required || Not Required || Static Measurement
|-
| segB || Segment B || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| segC || Segment C || custom || Not Required || Not Required || Audio / Video and Static Measurement
|-
| crossId1 || Standard episode ID. Gracenote/TMS ID should be used when available. Must be unique per episode. || custom || Optional || Not Required ||
|-
| crossId2 || Content originator (required only for distributors) || custom || Optional || Not Required ||
|-
| airdate || Original (local) air date and time (Eastern Time for US) || YYYYMMDD HH24:MI:SS || Mandatory || Not Required ||
|-
| pipmode ||
Current state of picture-in-picture (PIP) mode on device.
*"true" if audio / video measurement is displayed in PIP mode
*"false" if audio / video measurement is displayed in regular mode
|| "true", "false" || Optional || Not Required || Audio / Video Measurement
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| "1" - Linear
"2" - Dynamic
|| Mandatory || Not Required ||
|-
| progen || Genre (required only for non-TV originated content). See [[DCR OTT Genre List]] for acceptable values. || e.g. DD for Daytime Drama || Required for non-TV content || Not Required
|}

'''clientid & subbrand (vcid)'''
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. But if an app contains multiple brands and sub-brands and client is willing to give credit to another brand or sub-brand then :
*Client app developer can override the clientid and subbrand (brand and sub-brand info.) in [[loadMetadata]] call to get a proper measurement for a desired brand and sub-brand.
**If no clientid and subbrand are specified in CMS of a content and an ad, default values reported in the Configuration will be reported.
**If clientid and subbrand are specified in CMS of the content or ad, the most recent clientid and subbrand will be reported in subsequent pings. To report with a different clientid and subbrand, include the new values for the keys in their subsequent [[loadMetadata]] call.
'''Picture-in-picture (PIP) mode'''
Once the app detects PIP mode, call [[loadMetadata]] with the same set of assetids, values and with one additional parameter "pipmode": "true". Once PIP mode is disabled in the device, call [[loadMetadata]] again with "pipmode":"false".

==== Custom Variables Extension ====
Contact Nielsen Technical Account Manager (TAM) to configure any custom variables, as needed for implementing the application.

See [[Custom Variables Extension]] for more information.

==== Advertisement Metadata ====
{| class="wikitable"
|-
! Key !! Description !! Values !! Required for Audio / Video? !! Required for Static (page)
|-
| type || Type of ad || "preroll"
"midroll"
"postroll"
|| Mandatory || Not Required
|-
| assetid || An ID assigned to the advertisement. Can be an internal ID, an ID provided by the ad server, or a randomly generated ID. Must be unique across all ads || custom || Mandatory || Not Required
|-
| title || Title of the advertisement || "MyAdName" || Mandatory || Not Required
|}

=== Passing Metadata ===
The required metadata can be passed as key values through the loadMetadata method. The sample code below shows a metadata objects for various assets.
'''Audio / Video Measurement Asset'''
Type should be "content"
<syntaxhighlight lang="json"> {
"type": "content",
"assetName": "myassetName",
"length": "300",
"title": "myTitle",
"program": "myProgram",
"censuscategory": "myCensusCategory",
"assetid": "myAssetId",
"channelName": "myChannel",
"adloadtype": "2",
"segB": "segmentB",
"segC": "segmentC",
"isfullepisode":"y",
"crossId1": "Reference11",
"crossId2": "Reference22",
"airdate": "20161013 20:00:00"
}</syntaxhighlight>

'''Static (Page) Measurement Asset'''
Type should be "static"
<syntaxhighlight lang="json"> {
"type": "static",
"assetid": "static123",
"assetName": "Page-Asset",
"section": "siteSection",
"segA": "segmentA",
"segB": "segmentB",
"segC": "segmentC"
}</syntaxhighlight>

'''For any of the ad types'''
<syntaxhighlight lang="json"> {
"type": "midroll",
"length": "30",
"assetid": "myMidrollAssetId",
"adloadtype": "2",
"tv": "true",
"dataSrc": "cms"
}</syntaxhighlight>
<blockquote>'''Note''': In case the individual ad details are not available, send ad pod (presence) details through the <code>loadMetadata</code> and playhead position through <code>setPlayheadPosition</code>.</blockquote>

'''loadMetadata'''
The object can then be passed when calling [[loadMetadata]].
<syntaxhighlight lang="java"> loadMetadata(jsonMetadataObject);</syntaxhighlight>

Digital Measurement Testing

2018-05-18T14:48:50Z

ShaneHartman: Moved user agent check out of header into numbered list

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Monitoring Tools ==
HTTP traffic-monitoring tool, such as Charles or Fiddler are required.
*'''Charles:''' http://www.charlesproxy.com
*'''Fiddler:''' http://www.telerik.com/fiddler

== Step 1: Filter traffic ==
Filter HTTP traffic with the string "imr" to capture traffic from the SDK as shown in the below figure. This will capture traffic going to Nielsen servers. Now set up the device to proxy to this traffic analyzer.
<blockquote>'''Note:''' Instructions may vary from device to device and are available online.</blockquote>
[[File:fiddler-web-debugger.png|link=]]

== Step 2: Verify User Agent ==
Verify that your user agent is not being flagged as bot traffic. 

'''Device Atlas User Agent Tester''' 
Copy your application's user agent string to your clipboard and input it into the [https://deviceatlas.com/device-data/user-agent-tester Device Atlas User Agent Tester]. If your user agent is designated as a bot, you will see a value of '''"''true''"''' associated with the '''''Is Robot''''' property in the user agent search results.

'''Configuring User Agent ''' 
You will need to override the default value set in the user agent header request field if it's flagged as a bot. Request traffic originating from some third party HTTP clients is designated as bot traffic. To change the user agent, change the value of the User Agent Request header as indicated below:
<syntaxhighlight lang="java"> Request request = new Request.Builder()
.url("[api endpoint request url string]")
.header("User-Agent", "Custom User Agent")
.build();</syntaxhighlight>

== Step 3: Check Opt-Out ==
If the opt-out function or app disable feature is previously tested, it has to be ensured that an opt-in is completed on the device before continuing. Terminate the app completely before starting.

== Step 4: Hello Ping ==
The first HTTPS traffic that should be seen is the SDK request for configuration information, called a '''hello ping'''. In order to see this ping, Charles / Fiddler has to be configured to capture HTTPS traffic.

<code><nowiki>https://secure-dcr.imrworldwide.com/cgi-bin/cfg?cfgv=100&longitude=-82.66&latitude=28.05&apid=&apv=3.84.043&apn=com.video.videop
layer&sdkv=aa .1.2.3&nuid=7B341CD-5109-B88-B77D-8ADE904717A7&osver=ANDROID.4.2.2&devtypid=LGE-Nexus-4&devid=FFA503E7-
7749-4448-9922-132492ED4E12&fmt=json&adf=&uoo=&sfcode=dcr&ccode=1&dma=&rnd=1527112029</nowiki></code>
<blockquote>'''Note:''' If this ping fails to fire, it is likely that the instance of the SDK failed to initialize. Please see Initialization ([[iOS SDK API Reference#Initialization|iOS SDK API Reference - Initialization]] and [[Android SDK API Reference#Initialization|Android SDK API Reference - Initialization]]) to see how to initialize the SDK.</blockquote>

== Step 5: The L Ping ==
When the app is started after installing for the first time, and app is measuring '''DCR Static''' content only, a DCR static app launch known as '''L''' ping firing to secure-dcr.imrworldwide.com server in the traffic-monitor should be seen. However, the '''L''' ping will be observed again if app goes into background and resumes back after 5 minutes.

<code><nowiki>http://secure-dcr.imrworldwide.com</nowiki>/cgi-bin/gn?prd=dcr&ci=APRP7&ch=APRP7_NA_defChnAsset&asn=defChnAsset&tl=&c6=vc,NA&c13=asid,XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&c32=segA,&c33=segB,&c34=segC,&c15=apn,MTVR-APT-QA&sup=0&segment2=539&segment1=usa&forward=1&ad=1&cr=L&c9=devid,a69983bc65ad94f9e57109fec68cc847bf59575ee03cadb76b187f4c24eaf793&enc=true&c1=nuid,142a40706f9c03bfea020f7297828534a1f14895d7a8c5303d9b8a19b3337c13&r=&at=launch&rt=text&c16=sdkv ,aa.4.0.0&c27=cln,473&crs=0&si=&lat=28.09&lon=-82.76&c29=plid,XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&c30=bldv,aa.4.0.0.3&st=dcr&c7=osgrp,DROID&c8=devgrp,TAB&c10=plt,MBL&c40=adbid,&c14=osver,ANDROID.4.4.4&c26=1&c35=&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,apt.4.0.0.3&h33=2&c51=adl,0&c52=noad,0&devtypid=asus-Nexus-7&rnd=1432529128693</code>

If the app is measuring '''DCR Video Content''' only, then the '''hello ping''' will fire but the '''L''' ping will not be observed upon app launch.

== Step 6: Static View Ping ==
For any sections that are tagged for static content, a '''DCR Static – view''' ping should be received. The first landing page should always be tagged. An example of this ping is:

<code><nowiki>http://secure-dcr.imrworldwide.com</nowiki>/cgi-bin/gn?prd=dcr&ci=APRP7&ch=APRP7_NA_defChnAsset&asn=defChnAsset&tl=&c6=vc,NA&c13=asid,XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&c32=segA,&c33=segB,&c34=segC,&c15=apn,MTVR-APT-QA&sup=0&segment2=539&segment1=usa&forward=1&ad=1&cr=V&c9=devid,a69983bc65ad94f9e57109fec68cc847bf59575ee03cadb76b187f4c24eaf793&enc=true&c1=nuid,142a40706f9c03bfea020f7297828534a1f14895d7a8c5303d9b8a19b3337c13&r=&at=view&rt=text&c16=sdkv,a a.4.0.0&c27=cln,0&crs=0&si=&lat=&lon=&c29=plid,XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&c30=bldv,aa.4.0.0.1&st=dcr&c7=osgrp,DROID&c8=devgrp,TAB&c10=plt,MBL&c40=adbid,&c14=osver,ANDROID.4.4.4&c26=1&c35=&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,apt.4.0.0.2&h33=2&c51=adl,0&c52=noad,0&devtypid=asus-Nexus-7&rnd=1432068181560</code>
{| class="wikitable"
|-
! Parameter !! Description !! Example
|-
| ci || Client ID – this value should be consistent throughout all of the pings that fire for the implementation. || us-123456
|-
| asn || Asset Name – this value should represent the asset’s name assigned in the metadata. || Page-Asset
|-
| at || Action Type || Start
|-
| rt || This value should be “text” and indicates that this is a DCR tag for static content. || text
|-
| c13 || This value should contain the appid of the application. || asid,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| c32 || Segment A – Client customized metadata || CustomSegmentValueA
|-
| c33 || Segment B – Client customized metadata || CustomSegmentValueB
|-
| c34 || Segment C – Client customized metadata || CustomSegmentValueC
|}

== Step 7: Video View Ping ==
Approximately 60 seconds into viewing of the stream, a '''DCR Video – view''' ping fire to secure-dcr.imrworldwide.com server indicated by the '''cr''' value containing a '''V''' in the format of 4_00_99_'''V'''1_00000 should be seen.

{| class="wikitable"
|-
! Parameter !! Description !! Example
|-
| ci || Client ID – this value should be consistent throughout all of the pings that fire for the implementation. || us-123456
|-
| asn || Asset Name – this value should represent asset’s name assigned in the metadata. || Video-Asset
|-
| tl || Episode Title || Episode Name – S2 – E1 – LF
|-
| c13 || This value should contain the appid of the application. || asid,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| cr || Crediting Ping Identifier || 4_00_99_V1_00000
|-
| rt || This Value should be “video” and indicates that this is a DCR tag for video content. || video
|-
| c10 || Platform Indicator || plt,DSK or plt,MBL
|}
<blockquote>'''Note:''' If this ping fails to fire, a common cause is improper metadata being passed to the SDK. Examples of the proper metadata to be passed in the </code>loadMetadata</code></blockquote>

== Step 8: Video Duration Ping ==
The first duration ping is fired after 5 minutes of content is viewed. A '''DCR Video''' – duration ping fire to secure-dcr.imrworldwide.com indicated by the '''cr''' value containing a '''D''' in the format of 4_00_99_'''D'''1_11111 should be seen. This D ping should fire approximately every 5 minutes after the initial duration ping has fired or when the content switches to an advertisement. The ad length (c51) is the total ad duration viewed in the previous session, and the ad count (c52) is the number of ads viewed in previous segment.
{| class="wikitable"
|-
! Parameter !! Description !! Example
|-
| ci || Client ID – this value should be consistent throughout all of the pings that fire for the implementation. || us-123456
|-
| asn || Asset Name – this value should represent asset’s name assigned in the metadata. || Video-Asset
|-
| tl || Episode Title || Episode Name – S2 – E1 – LF
|-
| cr || Crediting Ping Identifier || 4_00_99_V1_00000
|-
| rt || This Value should be “video” and indicates that this is a DCR tag for video content. || video
|-
| c10 || Platform Indicator || plt,DSK or plt,MBL
|-
| c13 || This value should contain the appid of the application. || asid,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| c51 || Ad Duration || adl,88
|-
| c52 || Ad Count || noad,1
|}
<blockquote>'''Note:''' If this ping fails to fire, it may be caused by not passing the setPlayheadPosition API call as expected. The instruction as well as examples can be found in the Developer’s Guide.</code></blockquote>

== Step 9: 5min Duration Ping ==
View all channels for 5 minutes to ensure all channels fire a '''duration''' ping.

== Step 10: Pending Duration Ping ==
Play a stream and move the app to the background. A pending '''duration''' ping should fire; crediting the appropriate number of minutes viewed from last ping (i.e. 4_00_99_D1_'''111'''00). No other pings should fire after it has been moved to the background. In case SDK does not get a chance to send out the ping while going to background, SDK will send the pending ping on next re-launch.

== Step 11: Pending Duration Pings cont. ==
The same action will occur with any interruption to the stream’s playback (e.g., alarm, incoming call, etc.).

== Step 12: Opt-Out Implementation ==
Test the Opt-Out implementation in four steps.
*Complete an opt-out in the app through the Nielsen opt-out webview.
*User opt-out, a '''goodbye ping''' is fired off to the Nielsen server. '''Example Goodbye Ping''':
<code><nowiki>http://secure-dcr.imrworldwide.com</nowiki>/cgi-bin/cfg?cfgv=200&longitude=&latitude=&apid=&apv=01.00.00&apn=Nielsen%2520sample&sdkv=aa.4.0.0&bldv=aa.4.0.0.4&nuid=00b5926fea1807638ebfe6f04af6a455c5d9b2a1ed3e39f550f44daa39d0886d&osver=ANDROID.4.4.4&devtypid=samsung-SAMSUNG-SM-N910A&devid=42ec6a26b000ccd34015ba8625ee29cd283190a8c00f1622f356e900bb5b2a23&enc=true&tz=-14400&fmt=json&adf=&uoo=true&sfcode=dcr&ccode=&dma=539&rnd=1434632964945</code>
*Watch any content (static or video) for at least three minutes. No pings will be rendered.
*Opt back in, a '''hello ping''' is fired off to the Nielsen server. ''Example Hello Ping'':
<code><nowiki>http://secure-dcr.imrworldwide.com</nowiki>/cgi-bin/cfg?cfgv=200&longitude=-82.65&latitude=28.05&apid=&apv=01.00.00&apn=Nielsen%2520sample&sdkv=aa.4.0.0&bldv=aa.4.0.0.4&nuid=00b5926fea1807638ebfe6f04af6a455c5d9b2a1ed3e39f550f44daa39d0886d&osver=ANDROID.4.4.4&devtypid=samsung-SAMSUNG-SM-N910A&devid=42ec6a26b000ccd34015ba8625ee29cd283190a8c00f1622f356e900bb5b2a23&enc=true&tz=-14400&fmt=json&adf=&uoo=false&sfcode=dcr&ccode=&dma=539&rnd=1434633027479</code>
*Watch any video content for at least three minutes and V/D pings – '''view''' and '''duration''' pings will be visible.

Digital Measurement Testing

2018-04-18T21:45:47Z

ShaneHartman: added instructions to verify user agent using Device Atlas Tool

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Monitoring Tools ==
HTTP traffic-monitoring tool, such as Charles or Fiddler are required.
*'''Charles:''' http://www.charlesproxy.com
*'''Fiddler:''' http://www.telerik.com/fiddler

== Verify User Agent ==
Verify that your user agent is not being flagged as bot traffic. 

'''Device Atlas User Agent Tester''' 
Copy your application's user agent string to your clipboard and input it into the [https://deviceatlas.com/device-data/user-agent-tester Device Atlas User Agent Tester]. If your user agent is designated as a bot, you will see a value of '''"''true''"''' associated with the '''''Is Robot''''' property in the user agent search results.

'''Configuring User Agent ''' 
You will need to override the default value set in the user agent header request field if it's flagged as a bot. Request traffic originating from some third party HTTP clients is designated as bot traffic. To change the user agent, change the value of the User Agent Request header as indicated below:
<syntaxhighlight lang="java"> Request request = new Request.Builder()
.url("[api endpoint request url string]")
.header("User-Agent", "Custom User Agent")
.build();</syntaxhighlight>

== Step 1: Filter traffic ==
Filter HTTP traffic with the string "imr" to capture traffic from the SDK as shown in the below figure. This will capture traffic going to Nielsen servers. Now set up the device to proxy to this traffic analyzer.
<blockquote>'''Note:''' Instructions may vary from device to device and are available online.</blockquote>
[[File:fiddler-web-debugger.png|link=]]

== Step 2: Check Opt-Out ==
If the opt-out function or app disable feature is previously tested, it has to be ensured that an opt-in is completed on the device before continuing. Terminate the app completely before starting.

== Step 3: Hello Ping ==
The first HTTPS traffic that should be seen is the SDK request for configuration information, called a '''hello ping'''. In order to see this ping, Charles / Fiddler has to be configured to capture HTTPS traffic.

<code><nowiki>https://secure-dcr.imrworldwide.com/cgi-bin/cfg?cfgv=100&longitude=-82.66&latitude=28.05&apid=&apv=3.84.043&apn=com.video.videop
layer&sdkv=aa .1.2.3&nuid=7B341CD-5109-B88-B77D-8ADE904717A7&osver=ANDROID.4.2.2&devtypid=LGE-Nexus-4&devid=FFA503E7-
7749-4448-9922-132492ED4E12&fmt=json&adf=&uoo=&sfcode=dcr&ccode=1&dma=&rnd=1527112029</nowiki></code>
<blockquote>'''Note:''' If this ping fails to fire, it is likely that the instance of the SDK failed to initialize. Please see Initialization ([[iOS SDK API Reference#Initialization|iOS SDK API Reference - Initialization]] and [[Android SDK API Reference#Initialization|Android SDK API Reference - Initialization]]) to see how to initialize the SDK.</blockquote>

== Step 4: The L Ping ==
When the app is started after installing for the first time, and app is measuring '''DCR Static''' content only, a DCR static app launch known as '''L''' ping firing to secure-dcr.imrworldwide.com server in the traffic-monitor should be seen. However, the '''L''' ping will be observed again if app goes into background and resumes back after 5 minutes.

<code><nowiki>http://secure-dcr.imrworldwide.com</nowiki>/cgi-bin/gn?prd=dcr&ci=APRP7&ch=APRP7_NA_defChnAsset&asn=defChnAsset&tl=&c6=vc,NA&c13=asid,XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&c32=segA,&c33=segB,&c34=segC,&c15=apn,MTVR-APT-QA&sup=0&segment2=539&segment1=usa&forward=1&ad=1&cr=L&c9=devid,a69983bc65ad94f9e57109fec68cc847bf59575ee03cadb76b187f4c24eaf793&enc=true&c1=nuid,142a40706f9c03bfea020f7297828534a1f14895d7a8c5303d9b8a19b3337c13&r=&at=launch&rt=text&c16=sdkv ,aa.4.0.0&c27=cln,473&crs=0&si=&lat=28.09&lon=-82.76&c29=plid,XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&c30=bldv,aa.4.0.0.3&st=dcr&c7=osgrp,DROID&c8=devgrp,TAB&c10=plt,MBL&c40=adbid,&c14=osver,ANDROID.4.4.4&c26=1&c35=&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,apt.4.0.0.3&h33=2&c51=adl,0&c52=noad,0&devtypid=asus-Nexus-7&rnd=1432529128693</code>

If the app is measuring '''DCR Video Content''' only, then the '''hello ping''' will fire but the '''L''' ping will not be observed upon app launch.

== Step 5: Static View Ping ==
For any sections that are tagged for static content, a '''DCR Static – view''' ping should be received. The first landing page should always be tagged. An example of this ping is:

<code><nowiki>http://secure-dcr.imrworldwide.com</nowiki>/cgi-bin/gn?prd=dcr&ci=APRP7&ch=APRP7_NA_defChnAsset&asn=defChnAsset&tl=&c6=vc,NA&c13=asid,XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&c32=segA,&c33=segB,&c34=segC,&c15=apn,MTVR-APT-QA&sup=0&segment2=539&segment1=usa&forward=1&ad=1&cr=V&c9=devid,a69983bc65ad94f9e57109fec68cc847bf59575ee03cadb76b187f4c24eaf793&enc=true&c1=nuid,142a40706f9c03bfea020f7297828534a1f14895d7a8c5303d9b8a19b3337c13&r=&at=view&rt=text&c16=sdkv,a a.4.0.0&c27=cln,0&crs=0&si=&lat=&lon=&c29=plid,XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&c30=bldv,aa.4.0.0.1&st=dcr&c7=osgrp,DROID&c8=devgrp,TAB&c10=plt,MBL&c40=adbid,&c14=osver,ANDROID.4.4.4&c26=1&c35=&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,apt.4.0.0.2&h33=2&c51=adl,0&c52=noad,0&devtypid=asus-Nexus-7&rnd=1432068181560</code>
{| class="wikitable"
|-
! Parameter !! Description !! Example
|-
| ci || Client ID – this value should be consistent throughout all of the pings that fire for the implementation. || us-123456
|-
| asn || Asset Name – this value should represent the asset’s name assigned in the metadata. || Page-Asset
|-
| at || Action Type || Start
|-
| rt || This value should be “text” and indicates that this is a DCR tag for static content. || text
|-
| c13 || This value should contain the appid of the application. || asid,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| c32 || Segment A – Client customized metadata || CustomSegmentValueA
|-
| c33 || Segment B – Client customized metadata || CustomSegmentValueB
|-
| c34 || Segment C – Client customized metadata || CustomSegmentValueC
|}

== Step 6: Video View Ping ==
Approximately 60 seconds into viewing of the stream, a '''DCR Video – view''' ping fire to secure-dcr.imrworldwide.com server indicated by the '''cr''' value containing a '''V''' in the format of 4_00_99_'''V'''1_00000 should be seen.

{| class="wikitable"
|-
! Parameter !! Description !! Example
|-
| ci || Client ID – this value should be consistent throughout all of the pings that fire for the implementation. || us-123456
|-
| asn || Asset Name – this value should represent asset’s name assigned in the metadata. || Video-Asset
|-
| tl || Episode Title || Episode Name – S2 – E1 – LF
|-
| c13 || This value should contain the appid of the application. || asid,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| cr || Crediting Ping Identifier || 4_00_99_V1_00000
|-
| rt || This Value should be “video” and indicates that this is a DCR tag for video content. || video
|-
| c10 || Platform Indicator || plt,DSK or plt,MBL
|}
<blockquote>'''Note:''' If this ping fails to fire, a common cause is improper metadata being passed to the SDK. Examples of the proper metadata to be passed in the </code>loadMetadata</code></blockquote>

== Step 7: Video Duration Ping ==
The first duration ping is fired after 5 minutes of content is viewed. A '''DCR Video''' – duration ping fire to secure-dcr.imrworldwide.com indicated by the '''cr''' value containing a '''D''' in the format of 4_00_99_'''D'''1_11111 should be seen. This D ping should fire approximately every 5 minutes after the initial duration ping has fired or when the content switches to an advertisement. The ad length (c51) is the total ad duration viewed in the previous session, and the ad count (c52) is the number of ads viewed in previous segment.
{| class="wikitable"
|-
! Parameter !! Description !! Example
|-
| ci || Client ID – this value should be consistent throughout all of the pings that fire for the implementation. || us-123456
|-
| asn || Asset Name – this value should represent asset’s name assigned in the metadata. || Video-Asset
|-
| tl || Episode Title || Episode Name – S2 – E1 – LF
|-
| cr || Crediting Ping Identifier || 4_00_99_V1_00000
|-
| rt || This Value should be “video” and indicates that this is a DCR tag for video content. || video
|-
| c10 || Platform Indicator || plt,DSK or plt,MBL
|-
| c13 || This value should contain the appid of the application. || asid,XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| c51 || Ad Duration || adl,88
|-
| c52 || Ad Count || noad,1
|}
<blockquote>'''Note:''' If this ping fails to fire, it may be caused by not passing the setPlayheadPosition API call as expected. The instruction as well as examples can be found in the Developer’s Guide.</code></blockquote>

== Step 8: 5min Duration Ping ==
View all channels for 5 minutes to ensure all channels fire a '''duration''' ping.

== Step 9: Pending Duration Ping ==
Play a stream and move the app to the background. A pending '''duration''' ping should fire; crediting the appropriate number of minutes viewed from last ping (i.e. 4_00_99_D1_'''111'''00). No other pings should fire after it has been moved to the background. In case SDK does not get a chance to send out the ping while going to background, SDK will send the pending ping on next re-launch.

== Step 10: Pending Duration Pings cont. ==
The same action will occur with any interruption to the stream’s playback (e.g., alarm, incoming call, etc.).

== Step 11: Opt-Out Implementation ==
Test the Opt-Out implementation in four steps.
*Complete an opt-out in the app through the Nielsen opt-out webview.
*User opt-out, a '''goodbye ping''' is fired off to the Nielsen server. '''Example Goodbye Ping''':
<code><nowiki>http://secure-dcr.imrworldwide.com</nowiki>/cgi-bin/cfg?cfgv=200&longitude=&latitude=&apid=&apv=01.00.00&apn=Nielsen%2520sample&sdkv=aa.4.0.0&bldv=aa.4.0.0.4&nuid=00b5926fea1807638ebfe6f04af6a455c5d9b2a1ed3e39f550f44daa39d0886d&osver=ANDROID.4.4.4&devtypid=samsung-SAMSUNG-SM-N910A&devid=42ec6a26b000ccd34015ba8625ee29cd283190a8c00f1622f356e900bb5b2a23&enc=true&tz=-14400&fmt=json&adf=&uoo=true&sfcode=dcr&ccode=&dma=539&rnd=1434632964945</code>
*Watch any content (static or video) for at least three minutes. No pings will be rendered.
*Opt back in, a '''hello ping''' is fired off to the Nielsen server. ''Example Hello Ping'':
<code><nowiki>http://secure-dcr.imrworldwide.com</nowiki>/cgi-bin/cfg?cfgv=200&longitude=-82.65&latitude=28.05&apid=&apv=01.00.00&apn=Nielsen%2520sample&sdkv=aa.4.0.0&bldv=aa.4.0.0.4&nuid=00b5926fea1807638ebfe6f04af6a455c5d9b2a1ed3e39f550f44daa39d0886d&osver=ANDROID.4.4.4&devtypid=samsung-SAMSUNG-SM-N910A&devid=42ec6a26b000ccd34015ba8625ee29cd283190a8c00f1622f356e900bb5b2a23&enc=true&tz=-14400&fmt=json&adf=&uoo=false&sfcode=dcr&ccode=&dma=539&rnd=1434633027479</code>
*Watch any video content for at least three minutes and V/D pings – '''view''' and '''duration''' pings will be visible.