Engineering Client Portal - User contributions [en]

Mobile DAR Attributes Requirements

2022-09-21T19:08:04Z

ColinBrown: /* Additional DAR Tag Parameters for Mobile App Audience Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=0&r=<timestamp> </code>

{| class="wikitable"
|- style="font-weight:bold; "
! style="vertical-align:middle;" | Additional DAR Tag Parameters for Mobile
! style="vertical-align:middle;" | Example
! style="vertical-align:middle;" | Description
! style="vertical-align:middle;" | Mandatory parameter for mDAR?
|-
| style="vertical-align:middle;" | &c7
| &c7=osgrp,IOS
| style="vertical-align:middle;" | OS Grouping
| style="vertical-align:middle;" |
|- style="background-color:#eff8ef;"
| &c8
| &c8=devgrp,PHN
| style="vertical-align:middle;" | Device Grouping
| ✔
|-
| style="vertical-align:middle;" | &c9
| &c9=devid,CB6E9220-EA64-440B-9456-33AD2294C658
| style="vertical-align:middle; " | Advertising ID
| ✔
|- style="background-color:#eff8ef;"
| &c10
| &c10=plt,MBL
| Platform
| ✔
|-
| &c12
| &c12=apv,1
| App Version
|
|- style="background-color:#eff8ef;"
| &c13
| c13=asid,DD8136-4F0B-470B-9ACA-231E818D95BC
| AppID (Nielsen assigned App ID)
| | ✔
|-
| &c14
| &c14=osver,15.1.3
| OS Version
|
|- style="background-color:#eff8ef;"
|&uoo
| &uoo=0
| Opt-out indicator
| ✔
|-
| | &hem_md5
| &hem_md5=53d8c474c1e871bdd34f14785dbcfd94
| | MD5 Hashed Email
|
|- style="background-color:#eff8ef;"
| &hem_sha1
|
| SHA1 Hashed Email
|
|-
|&hem_sha256
|
| SHA256 Hashed Email
|
|- style="background-color:#eff8ef;"
| &hem_unknown
|
| Unknown Hashed Algorithm Email
|
|}

<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>
 
{| class="wikitable"
|- style="background-color:#efefef;"
! colspan="2" | Below are the supported hash methods for the devid value:
|- style="vertical-align:bottom;"
| Clear Text
| c9=devid,CB6E9220-EA64-440B-9456-33AD2294C658
|- style="vertical-align:bottom;"
| sha256
| c9=devid,136844f58ab7f7e991ea4b5150ec767c9327e1391c839a3b3612d418ae875391
|- style="vertical-align:bottom;"
| Sha1
| c9=devid,a08039967f4817ada4a7f331369eea522ad415a7
|- style="vertical-align:bottom;"
| md5
| c9=devid,53d8c474c1e871bdd34f14785dbcfd94
|}

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>
== Additional Parameters ==
This section describes several important additional parameters that the DAR tag can support, specifically Hashed Email, and UID2 values. Please note that all parameters are case-sensitive.

Please work with your Nielsen Technical Account Manager to decide which of the following parameters to append to the standard DAR tag.
=== HEM Support (Hashed Email) ===
Please use the parameter that matches your hashing algorithm. For example, if you are using sha256 to encode the email address, then use hem_sha256={encrypted_value_here}
{| class="wikitable" style="font-weight:bold; background-color:#EAECF0;"
|-
! Name
! Description
! Available Tag Parameters
|- style="font-weight:normal; background-color:#F8F9FA;"
| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) to create a unique hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
| &hem_unknown &hem_sha256 &hem_md5 &hem_sha1
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#dae8fc; color:#002041;"
! Example
|- style="font-weight:normal;"
| hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
|}

=== Unified ID ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Unified ID 2.0
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.
| &uid2
|-
| Unified ID 2.0 Token
| Encrypted Unified ID 2.0
| &uid_token
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k= uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5 /xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
|}

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

Mobile DAR Attributes Requirements

2022-09-21T19:06:07Z

ColinBrown: /* Additional DAR Tag Parameters for Mobile App Audience Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=0&r=<timestamp> </code>

{| class="wikitable"
|- style="font-weight:bold; "
! style="vertical-align:middle;" | Additional DAR Tag Parameters for Mobile
! style="vertical-align:middle;" | Example
! style="vertical-align:middle;" | Description
! style="vertical-align:middle;" | Mandatory parameter for mDAR?
|-
| style="vertical-align:middle;" | &c7
| &c7=osgrp,IOS
| style="vertical-align:middle;" | OS Grouping
| style="vertical-align:middle;" |
|- style="background-color:#eff8ef;"
| &c8
| &c8=devgrp,PHN
| style="vertical-align:middle;" | Device Grouping
| ✔
|-
| style="vertical-align:middle;" | &c9
| &c9=devid,CB6E9220-EA64-440B-9456-33AD2294C658
| style="vertical-align:middle; " | Advertising ID
| ✔
|- style="background-color:#eff8ef;"
| &c10
| &c10=plt,MBL
| Platform
| ✔
|-
| &c12
| &c12=apv,1
| App Version
|
|- style="background-color:#eff8ef;"
| &c13
| c13=asid,DD8136-4F0B-470B-9ACA-231E818D95BC
| AppID (Nielsen assigned App ID)
| | ✔
|-
| &c14
| &c14=osver,15.1.3
| OS Version
|
|- style="background-color:#eff8ef;"
|&uoo
| &uoo=0
| Opt-out indicator
| ✔
|-
| | &hem_md5
| &hem_md5=53d8c474c1e871bdd34f14785dbcfd94
| | MD5 Hashed Email
| Only use 1 hash type |
|- style="background-color:#eff8ef;"
| &hem_sha1
|
| SHA1 Hashed Email
|
|-
|&hem_sha256
|
| SHA256 Hashed Email
|
|- style="background-color:#eff8ef;"
| &hem_unknown
|
| Unknown Hashed Algorithm Email
|
|}

<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>
 
{| class="wikitable"
|- style="background-color:#efefef;"
! colspan="2" | Below are the supported hash methods for the devid value:
|- style="vertical-align:bottom;"
| Clear Text
| c9=devid,CB6E9220-EA64-440B-9456-33AD2294C658
|- style="vertical-align:bottom;"
| sha256
| c9=devid,136844f58ab7f7e991ea4b5150ec767c9327e1391c839a3b3612d418ae875391
|- style="vertical-align:bottom;"
| Sha1
| c9=devid,a08039967f4817ada4a7f331369eea522ad415a7
|- style="vertical-align:bottom;"
| md5
| c9=devid,53d8c474c1e871bdd34f14785dbcfd94
|}

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>
== Additional Parameters ==
This section describes several important additional parameters that the DAR tag can support, specifically Hashed Email, and UID2 values. Please note that all parameters are case-sensitive.

Please work with your Nielsen Technical Account Manager to decide which of the following parameters to append to the standard DAR tag.
=== HEM Support (Hashed Email) ===
Please use the parameter that matches your hashing algorithm. For example, if you are using sha256 to encode the email address, then use hem_sha256={encrypted_value_here}
{| class="wikitable" style="font-weight:bold; background-color:#EAECF0;"
|-
! Name
! Description
! Available Tag Parameters
|- style="font-weight:normal; background-color:#F8F9FA;"
| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) to create a unique hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
| &hem_unknown &hem_sha256 &hem_md5 &hem_sha1
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#dae8fc; color:#002041;"
! Example
|- style="font-weight:normal;"
| hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
|}

=== Unified ID ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Unified ID 2.0
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.
| &uid2
|-
| Unified ID 2.0 Token
| Encrypted Unified ID 2.0
| &uid_token
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k= uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5 /xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
|}

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

Mobile DAR Attributes Requirements

2022-09-21T18:58:06Z

ColinBrown: /* C9 - Advertising ID (Mandatory) */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=0&r=<timestamp> </code>

{| class="wikitable"
|- style="font-weight:bold; "
! style="vertical-align:middle;" | Additional DAR Tag Parameters for Mobile
! style="vertical-align:middle;" | Example
! style="vertical-align:middle;" | Description
! style="vertical-align:middle;" | Mandatory parameter for mDAR?
|-
| style="vertical-align:middle;" | &c7
| &c7=osgrp,IOS
| style="vertical-align:middle;" | OS Grouping
| style="vertical-align:middle;" |
|- style="background-color:#eff8ef;"
| &c8
| &c8=devgrp,PHN
| style="vertical-align:middle;" | Device Grouping
| ✔
|-
| style="vertical-align:middle;" | &c9
| &c9=devid,CB6E9220-EA64-440B-9456-33AD2294C658
| style="vertical-align:middle; " | Advertising ID
| ✔
|- style="background-color:#eff8ef;"
| &c10
| &c10=plt,MBL
| Platform
| ✔
|-
| &c12
| &c12=apv,1
| App Version
|
|- style="background-color:#eff8ef;"
| &c13
| c13=asid,DD8136-4F0B-470B-9ACA-231E818D95BC
| AppID (Nielsen assigned App ID)
| | ✔
|-
| &c14
| &c14=osver,15.1.3
| OS Version
|
|- style="background-color:#eff8ef;"
|&uoo
| &uoo=0
| Opt-out indicator
| ✔
|-
| | &hem_md5
| &hem_md5=53d8c474c1e871bdd34f14785dbcfd94
| | MD5 Hashed Email
| |
|- style="background-color:#eff8ef;"
| &hem_sha1
|
| SHA1 Hashed Email
|
|-
|&hem_sha256
|
| SHA256 Hashed Email
|
|- style="background-color:#eff8ef;"
| &hem_unknown
|
| Unknown Hashed Algorithm Email
|
|}

<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>
 
{| class="wikitable"
|- style="background-color:#efefef;"
! colspan="2" | Below are the supported hash methods for the devid value:
|- style="vertical-align:bottom;"
| Clear Text
| c9=devid,CB6E9220-EA64-440B-9456-33AD2294C658
|- style="vertical-align:bottom;"
| sha256
| c9=devid,136844f58ab7f7e991ea4b5150ec767c9327e1391c839a3b3612d418ae875391
|- style="vertical-align:bottom;"
| Sha1
| c9=devid,a08039967f4817ada4a7f331369eea522ad415a7
|- style="vertical-align:bottom;"
| md5
| c9=devid,53d8c474c1e871bdd34f14785dbcfd94
|}

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>
== Additional Parameters ==
This section describes several important additional parameters that the DAR tag can support, specifically Hashed Email, and UID2 values. Please note that all parameters are case-sensitive.

Please work with your Nielsen Technical Account Manager to decide which of the following parameters to append to the standard DAR tag.
=== HEM Support (Hashed Email) ===
Please use the parameter that matches your hashing algorithm. For example, if you are using sha256 to encode the email address, then use hem_sha256={encrypted_value_here}
{| class="wikitable" style="font-weight:bold; background-color:#EAECF0;"
|-
! Name
! Description
! Available Tag Parameters
|- style="font-weight:normal; background-color:#F8F9FA;"
| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) to create a unique hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
| &hem_unknown &hem_sha256 &hem_md5 &hem_sha1
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#dae8fc; color:#002041;"
! Example
|- style="font-weight:normal;"
| hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
|}

=== Unified ID ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Unified ID 2.0
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.
| &uid2
|-
| Unified ID 2.0 Token
| Encrypted Unified ID 2.0
| &uid_token
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k= uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5 /xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
|}

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

Mobile DAR Attributes Requirements

2022-09-21T18:57:37Z

ColinBrown: /* Additional DAR Tag Parameters for Mobile App Audience Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=0&r=<timestamp> </code>

{| class="wikitable"
|- style="font-weight:bold; "
! style="vertical-align:middle;" | Additional DAR Tag Parameters for Mobile
! style="vertical-align:middle;" | Example
! style="vertical-align:middle;" | Description
! style="vertical-align:middle;" | Mandatory parameter for mDAR?
|-
| style="vertical-align:middle;" | &c7
| &c7=osgrp,IOS
| style="vertical-align:middle;" | OS Grouping
| style="vertical-align:middle;" |
|- style="background-color:#eff8ef;"
| &c8
| &c8=devgrp,PHN
| style="vertical-align:middle;" | Device Grouping
| ✔
|-
| style="vertical-align:middle;" | &c9
| &c9=devid,CB6E9220-EA64-440B-9456-33AD2294C658
| style="vertical-align:middle; " | Advertising ID
| ✔
|- style="background-color:#eff8ef;"
| &c10
| &c10=plt,MBL
| Platform
| ✔
|-
| &c12
| &c12=apv,1
| App Version
|
|- style="background-color:#eff8ef;"
| &c13
| c13=asid,DD8136-4F0B-470B-9ACA-231E818D95BC
| AppID (Nielsen assigned App ID)
| | ✔
|-
| &c14
| &c14=osver,15.1.3
| OS Version
|
|- style="background-color:#eff8ef;"
|&uoo
| &uoo=0
| Opt-out indicator
| ✔
|-
| | &hem_md5
| &hem_md5=53d8c474c1e871bdd34f14785dbcfd94
| | MD5 Hashed Email
| |
|- style="background-color:#eff8ef;"
| &hem_sha1
|
| SHA1 Hashed Email
|
|-
|&hem_sha256
|
| SHA256 Hashed Email
|
|- style="background-color:#eff8ef;"
| &hem_unknown
|
| Unknown Hashed Algorithm Email
|
|}

<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>
== Additional Parameters ==
This section describes several important additional parameters that the DAR tag can support, specifically Hashed Email, and UID2 values. Please note that all parameters are case-sensitive.

Please work with your Nielsen Technical Account Manager to decide which of the following parameters to append to the standard DAR tag.
=== HEM Support (Hashed Email) ===
Please use the parameter that matches your hashing algorithm. For example, if you are using sha256 to encode the email address, then use hem_sha256={encrypted_value_here}
{| class="wikitable" style="font-weight:bold; background-color:#EAECF0;"
|-
! Name
! Description
! Available Tag Parameters
|- style="font-weight:normal; background-color:#F8F9FA;"
| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) to create a unique hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
| &hem_unknown &hem_sha256 &hem_md5 &hem_sha1
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#dae8fc; color:#002041;"
! Example
|- style="font-weight:normal;"
| hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
|}

=== Unified ID ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Unified ID 2.0
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.
| &uid2
|-
| Unified ID 2.0 Token
| Encrypted Unified ID 2.0
| &uid_token
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k= uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5 /xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
|}

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

Mobile DAR Attributes Requirements

2022-09-20T23:53:22Z

ColinBrown: /* HEM Support (Hashed Email) */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=0&r=<timestamp> </code>

{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory parameter for mDAR?
|-
| &c7 || OS Grouping ||
|- style="background-color:#eff8ef;"
| &c8 || Device Grouping || <center>✔</center>
|-
| &c9 || Advertising ID || <center>✔</center>
|- style="background-color:#eff8ef;"
| &c10 || Platform || <center>✔</center>
|-
| &c12 || App Version ||
|- style="background-color:#eff8ef;"
| &c13 || AppID (Nielsen assigned App ID) || <center>✔</center>
|-
| &c14 || OS Version ||
|- style="background-color:#eff8ef;"
| &uoo || Opt-out indicator || <center>✔</center>
|}
<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>
== Additional Parameters ==
This section describes several important additional parameters that the DAR tag can support, specifically Hashed Email, and UID2 values. Please note that all parameters are case-sensitive.

Please work with your Nielsen Technical Account Manager to decide which of the following parameters to append to the standard DAR tag.
=== HEM Support (Hashed Email) ===
Please use the parameter that matches your hashing algorithm. For example, if you are using sha256 to encode the email address, then use hem_sha256={encrypted_value_here}
{| class="wikitable" style="font-weight:bold; background-color:#EAECF0;"
|-
! Name
! Description
! Available Tag Parameters
|- style="font-weight:normal; background-color:#F8F9FA;"
| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) to create a unique hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
| &hem_unknown &hem_sha256 &hem_md5 &hem_sha1
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#dae8fc; color:#002041;"
! Example
|- style="font-weight:normal;"
| hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
|}

=== Unified ID ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Unified ID 2.0
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.
| &uid2
|-
| Unified ID 2.0 Token
| Encrypted Unified ID 2.0
| &uid_token
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k= uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5 /xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
|}

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

DAR Tag Implementation Guide

2022-09-20T23:50:36Z

ColinBrown: /* HEM Support (Hashed Email) */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= Introduction =

This document provides an overview of the Nielsen Digital Ad Ratings (DAR) Tags and the steps necessary to implement them as part of your digital advertising campaigns.
=== What is DAR ===
DAR is a measurement platform for digital advertising campaigns. The platform provides a clear view of the true audience of a campaign, including Reach, Frequency, and GRP statistics by audience demographic group.
=== What we measure===
All DAR tags allow you to measure campaign impressions and the DAR JavaScript tags measure ad viewability, GIVT (General Invalid Traffic), and SIVT (Sophisticated Invalid Traffic) across platforms including web, mobile, and in-app.
=== How we measure it===
Nielsen’s DAR suite of JavaScript tags together with a pixel tag fallback will be present in your ad placements. We utilize industry-standard APIs to perform measurement cross-browser and cross-platform. In most cases, you will only need to add a simple URL through your ad management interface to fully utilize DAR measurement in your campaigns.
=== Prerequisites ===
For steps outlined in this document, you should have access to Nielsen’s Campaign Management Interface (CMI) and a Nielsen Technical Account Manager (TAM) will be working with you during the implementation phase.
__TOC__
= DAR Measurement Types =

== DAR Display==

The DAR Display JavaScript tag reports ad impressions as well as measures ad viewability and SIVT. In standard web placements, it will find the ad unit in the surrounding DOM container and will then report viewability as a time series with a 1-second resolution.

The DAR tag will report the MRC-required minimum of 1 second on screen and a continuous viewability time series for the lifetime of the ad session to enable additional viewability qualifiers.

The tag can utilize the IAB’s [https://iabtechlab.com/standards/open-measurement-sdk/ '''Open Measurement SDK'''] (OM SDK) including [https://iabtechlab.com/blog/open-measurement-for-web-video-arrives/ '''OM Web'''] integration if the OM Interface Definition (OMID) is available, or it will use industry-standard web APIs to measure viewability.

=== Requirements ===

The DAR Display tag requires a JavaScript-enabled browser for web environments or the OM SDK for in-app to operate and should be placed close to the corresponding measured ad unit. It should be on the same DOM level (e.g. directly under the same parent) or in a child node under the same parent node. The ad unit should be a content-bearing DOM element (e.g. img, canvas, SVG, iframe, div) with a minimum size of 30x30 pixels.

=== Parameters ===

The minimum required DAR parameters are '''ca, ci, cr, pc, ce''' and '''am'''. See the [[DAR_Tag_Implementation_Guide#Appendix|'''Appendix''']] for a full list of parameters.

=== Example Tag ===
<syntaxhighlight lang="javascript">
<script type="text/javascript"
src="https://dar.imrworldwide.com/js/dar.js?ca=nlsnXXXXXX&cr={AD.ID}&ce={PUBLISHER.ID}&ci=nlsnciXXXX&pc={PLACEMENT.ID}&am=3">
</script>
</syntaxhighlight>

=== Example OMID Display Placement ===

DAR can be enabled through the OM SDK by passing the required Nielsen OM inputs listed in the table below during setup:

{| class="wikitable"
|-
! style="width: 20%" | OM Parameter
! style="width: 40%" | Description
! style="width: 40%" | Nielsen Value
! style="width: 5%" |Required
|-
| Vendor Key
| ID for measurement provider
| nielsen.com-omid
| ✔
|-
| JavaScript Resource URL
| URL for measurement provider’s verification script
|<syntaxhighlight lang="html"> https://dar.imrworldwide.com/js/dar.js</syntaxhighlight>
| ✔
|-
| Verification Parameters
| Measurement provider’s verification tag parameters
| style="font-family:'Courier New', Courier, monospace !important; color:#222222;" |<syntaxhighlight lang="html">ca=nlsnXXXXXX&cr={AD.ID}&ce=publisherXXXX&ci=nlsnciXXXX&pc=placementID_XXXX1&am=3</syntaxhighlight>
| ✔
|-
| Verification Not Executed URL
| Error URL when the ad player denies measurement script execution
| style="font-family:'Courier New', Courier, monospace !important; color:#222222;" | <syntaxhighlight lang="html">https://events.imrworldwide.com/er?ercd=8800&erms=verificationNotExecuted-
{reason}&ca=nlsnXXXXXX&cr=ad_ID_XXXX&ce=publisherXXXX&
ci=nlsnciXXXX&pc=placementID_XXXX5&am=3
&c13={asid,app_id}</syntaxhighlight>
|

|}

<blockquote>
Note: The verificationNotExecuted Error URL is recommended for better troubleshooting during campaign setup. If your system can provide a macro for the reason of the interrupted measurement session, it can be added in place of the {reason} placeholder in the error URL. This can be an error code or a clear text error message.</blockquote>

=== Expected Display Ad Session Pings ===
{| class="wikitable"

! '''Description'''
! '''Timing'''
! '''Path'''
|-
| DAR Main Ping
| At initial load
| secure-gl.imrworldwide.com/cgi-bin/m
|-
| Nielsen Measure Ping
| Measurement start
| events.imrworldwide.com/nmp
|-
| Primary Standard Ping
| After 1 second of viewable duration (may not occur based on MRC rules)
| events.imrworldwide.com/psp
|-
| Timed Pings
| At 1, 5, 15 and 120 seconds of ad session time (may not occur based on ad session length)
| events.imrworldwide.com/1sp, 5sp, 15sp, 120sp
|-
| Final Ping
| At window/tab unloading event
| events.imrworldwide.com/fp
|-
| Error Ping
| Potential integration error - please contact your Nielsen representative
| events.imrworldwide.com/er
|}

=== Ping Flow ===

This flow illustrates the behavior of the DAR Display tag. 

[[File:Screenshot 2022-06-22 152646.png]]

{| class="wikitable"
|-
! colspan="2" | Ping Flow Legend
|-
| 1SP, 5SP, 15SP, 120SP
| Timed Measure Ping at 1, 5, 15 and 120 seconds
|-
| D0, D1, D2
| Dynamic SIVT Pings at 1, 15 & 30 seconds
|-
| FP
| Final Ping
|-
| IMPID
| Unique Impression ID
|-
| NMP
| Nielsen Main Measure Ping
|-
| PSP
| Primary Standard Ping
|-
| SIVT
| Sophisticated Invalid Traffic
|}

== DAR Video ==

The DAR Video tag will typically be trafficked as part of a Video Ad Serving Template (VAST) file. Nielsen provides its wrapped video tag (vWrap) to make this type of deployment easy and consistent across the various ad servers and trafficking options. Nielsen’s vWrap tag supports both automatic OMID and VPAID integration with existing VAST files. The two sections below, [[#Wrapped_Video_Tag_.28vWrap.29_Deployment|'''Wrapped Video Tag''']] and [[#Video_JS_Tag|'''Video JS Tag''']], describe these options and their expected outcomes.

In addition, Nielsen supports '''direct DAR Video tag deployments''' with manual integration in existing workflows. In this case, the section [[#video-js-tag|'''Video JS Tag''']] below describes the basic setup and expected results. In addition, it is recommended that you work closely with your Nielsen Technical Account Manager if you consider a manual tag integration with your campaigns.

=== Wrapped Video Tag (vWrap) Deployment ===

Nielsen’s wrapped DAR video tag, vWrap, is the preferred delivery method for VAST-controlled video ad placements.The vWrap tag is served by a Nielsen service that takes an original VAST with an inline ad (not a wrapper redirect) and dynamically adds the DAR Video tag with measurement solutions for VPAID and OMID. The '''apiframework''' parameter can be used to control which measurement solution will be inserted (see below).

=== Parameters ===

The minimum required DAR parameters are '''ca, ci, ce, cr, pc''', '''am, apiframework''' and '''vastURL'''. See the [[DAR_Tag_Implementation_Guide#Appendix|'''Appendix''']] for a full list of parameters.

The Open Real Time Bidding ([https://iabtechlab.com/wp-content/uploads/2022/04/OpenRTB-2-6_FINAL.pdf '''OpenRTB''']) API framework values for identifying the ad inventory type should be passed in the Nielsen '''apiframework''' parameter. The values should be either 1 or 2 (VPAID) or 7 or 8 (OMID). The available API framework values are listed in the IAB’s [https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list--api-frameworks- '''AdCOM specification 1.0''']. If the parameter is left blank or set to 0, Wrap will add the DAR Video tag as '''both''' an OMID verification client and VPAID wrapper. See more details in the [[DAR_Tag_Implementation_Guide#Appendix|'''Appendix''']].

The '''vastURL''' parameter must be the last parameter on the DAR tag with its value set as the full URL (including all original parameters) of the original VAST tag for the ad placement.

=== Example Wrapped Video Tag (vWrap) ===
{| class="wikitable" style="font-family:'Courier New', Courier, monospace !important;"
|-
! <syntaxhighlight lang="html"> https://vwrap.imrworldwide.com/v1/wrap?ca=nlsnXXXXXX&cr={AD.ID}&ce={PUBLISHER.ID}&pc={PLACEMENT.ID}&ci=nlsnciXXXX&am=4&
c9={devid,Advertising_ID}&c13=asid,app_id}&apiframework={APIFRAMEWORK}&vastURL={ORIGINAL_VAST_URL}</syntaxhighlight>
|}
<blockquote>
To observe how vWrap operates, we have provided some example VAST URLs which you can load directly in your browser.
</blockquote>
==== VAST ad Unit, no Impression/Viewability ====
First, here is a VAST ad unit with a single video file and no impression tracking or viewability measurement:
{| class="wikitable"
|-
! https://madimator.com/vast-examples/example_video_only_nielsen_15s.xml
|}
==== VAST ad Unit, Nielsen vWrap for OMID measurement ====
This is the same VAST file loaded via Nielsen’s vWrap tag for '''OMID measurement''' (apiframework is set to 7):
{| class="wikitable"
|-
! https://vwrap.imrworldwide.com/v1/wrap?ca=nlsn305255&cr=nielsenomidtest&ce=nielsen&pc=vastomid&ci=nlsntest&am=4&apiframework=7&vastURL=http://madimator.com/vast-examples/example_video_only_nielsen_15s.xml
|}

==== VAST ad Unit, Nielsen vWrap for VPAID measurement ====
And here is the same VAST with the vWrap tag configured for '''VPAID measurement''' (apiframework is set to 2):
{| class="wikitable"
|-
!https://vwrap.imrworldwide.com/v1/wrap?ca=nlsn305255&cr=nielsenomidtest&ce=nielsen&pc=vastvpaid&ci=nlsntest&am=4&apiframework=2&vastURL=http://madimator.com/vast-examples/example_video_only_nielsen_15s.xml
|}

=== Video JS Tag ===

The DAR Video tag supports both OM SDK and VPAID video ad measurement and provides viewability time series, audio volume time series, GIVT, and SIVT data. The time series contains playhead events with corresponding measurements at a 1-second resolution. In addition to the time series, a dedicated ping will report on the MRC-required minimum of 2 seconds on screen.

With OM SDK, the DAR Video tag supports the following ad types:

* Native mobile in-app ad placements
* Mobile web ads
* OM Web placements
* OMID-enabled streaming video players with ad SDKs (for instance DAI IMA SDK)

With VPAID, it supports the following operating modes:
* As VPAID wrapper for an existing VPAID ad unit in the VAST
* As VPAID ad unit in a VAST with video files and AdParameters node
* In Custom Integrations with VPAID host players

In most cases, the DAR Video tag should not be manually implemented as a wrapper, instead consider utilizing Nielsen’s vWrap tag.

==== Requirements ====

The DAR Video tag needs a JavaScript environment to operate. The video unit to be measured needs to have a size of at least 30x30 pixels. The DAR Video tag requires access to the VPAID ad unit or to an OM SDK API present in the JavaScript context.

==== Parameters ====

The minimum required DAR parameters are '''ca, ci, ce, cr, pc''' and '''am'''. For VPAID wrapper placements, '''vpaidURL''' is also required.

To comply with MRC guidelines, you will be required to append '''autop''' to indicate click-to-play vs auto-play.

If the DAR Video tag will act as the VPAID wrapper, '''vpaidURL''' has to be the tag’s last parameter and its value set to the full URL (including parameters) of the original VPAID ad unit.

See the [[DAR_Tag_Implementation_Guide#Appendix|'''Appendix''']] for a full list of parameters.

==== Expected Video Ad Session Pings ====

{| class="wikitable"
! '''Description'''
! '''Timing'''
! '''Path'''
|-
| DAR Main Ping
| At initial load
| secure-gl.imrworldwide.com/cgi-bin/m
|-
| Nielsen Measure Ping
| Measurement start
| events.imrworldwide.com/nmp
|-
| Primary Standard Ping
| After 2 seconds of viewable duration (may not occur based on MRC rules)
| events.imrworldwide.com/psp
|-
| Quarterly Ping
| At 25%, 50%, 75% and 100% of video progress
| events.imrworldwide.com/qp
|-
| Final Ping
| At video stop or window/tab unloading event
| events.imrworldwide.com/fp
|-
| Error Ping
| Potential integration error - please contact your Nielsen representative
| events.imrworldwide.com/er
|}

==== Ping Flow ====

This flow illustrates the behavior of the DAR Video tag if the impression pixel is part of the VAST to be sent by the ad player and the JS tag has '''&darsup=1'''. The parameter, <code>darsup=1</code>, is used to suppress the DAR Main Ping from being sent from the JS tag since the DAR main ping will be sent from the DAR impression pixel. This is the default setup if Nielsen’s vWrap tag is being used to set up the video campaign.

[[File:Screenshot 2022-06-22 2.png]]
{| class="wikitable"
|-
! colspan="2" | Ping Flow Legend
|-
| D0, D1, D2
| Dynamic SIVT Pings at 1, 15 & 30 seconds
|-
| FP
| Final Ping
|-
| IMPID
| Unique Impression ID
|-
| NMP
| Nielsen Main Measure Ping
|-
| PSP
| Primary Standard Ping
|-
| QP
|Quarterly Media Pings at 25%, 50%, 75% and 100%
|-
| SIVT
| Sophisticated Invalid Traffic
|}

==== Example OMID Video Placement ====

DAR can be enabled through the OM SDK by passing the required Nielsen OM inputs listed in the table in the VAST <adVerifications> node:

{| class="wikitable"
! '''OM Parameter'''
! '''Description'''
! '''Nielsen Value'''
! '''Required'''
|-
| Vendor Key
| ID for measurement provider
| nielsen.com-omid
| ✔
|-
| JavaScript Resource URL
| URL for measurement provider’s verification script
| <syntaxhighlight lang="html">https://dar.imrworldwide.com/js/darvideo.js</syntaxhighlight>
| ✔
|-
| Verification Parameters
| Measurement provider’s verification tag parameters
| style="font-family:'Courier New', Courier, monospace !important; color:#222222;" |<syntaxhighlight lang="html">ca=nlsnXXXXXX&cr={AD.ID}&ce=publisherXXXX&ci=nlsnciXXXX&
pc=placementID_XXXX1&am=3</syntaxhighlight>
| ✔
|-
| Verification Not Executed URL
| Error URL when the ad player denies measurement script execution
| style="font-family:'Courier New', Courier, monospace !important; color:#222222;" | <syntaxhighlight lang="html">https://events.imrworldwide.com/er?ercd=8800&erms=verificationNotExecuted-
{reason}&ca=nlsnXXXXXX&cr=ad_ID_XXXX&ce=publisherXXXX&
ci=nlsnciXXXX&pc=placementID_XXXX5&am=3&c9={devid,Advertising_ID}
&c13={asid,app_id}</syntaxhighlight>
|

|}
<blockquote>
Note: The verificationNotExecuted Error URL is recommended for better troubleshooting during campaign setup. If your system can provide a macro for the reason of the interrupted measurement session, it can be added in place of the {reason} placeholder in the error URL. This can be an error code or a clear text error message.
</blockquote>

==== Example VPAID Placement in VAST ====

A typical VAST placement with VPAID will contain an impression pixel, the DAR Video JS tag as MediaFile of type “VPAID”, and the video MediaFiles will be duplicated as AdParameters object. In the example below, there was no original VPAID ad unit (the original VAST only contained MP4 video files), so the &vpaidURL parameter on the DAR JS tag stays empty.

In this example, the DAR JavaScript tag will operate as the VPAID ad unit and will play an appropriate media file from the list contained in the AdParameters node.

<syntaxhighlight lang="json">
...
<Impression id="Nielsen Digital Ad Ratings">
<![CDATA[https://secure-enc.imrworldwide.com/cgi-bin/m?at=view&cy=2&rt=banner&src=njs&
st=image&tpv=vwrap&ca=nlsnXXXXXX&cr={AD.ID}&ce=publisherXXXX&ci=nlsnciXXXX&pc=placementID_XXXX1&am=3]]>
</Impression>
...
<MediaFiles>
<MediaFile apiFramework="VPAID" type="application/javascript">
<![CDATA[https://dar.imrworldwide.com/js/darvideo.js?darsup=1&ca=nlsnXXXXXX&cr={{AD.ID}}&
ce=publisherXXXX&ci=nlsnciXXXX&pc=placementID_XXXX1&am=3]]>
</MediaFile>
<MediaFile bitrate="720" delivery="progressive" height="480" id="XXXXXX"
maintainAspectRatio="true" scalable="true" type="video/mp4"
width="854"><![CDATA[https://XXXXX.net/XXXXXX.mp4]]>
</MediaFile>
</MediaFiles>
...
<AdParameters>
<![CDATA[{"mediaFiles":[{"bitrate":"720","uri":"https://XXXXX.net/XXXXXX.mp4","height":"480","scalable":"true",
"id":"XXXXXX","type":"video/mp4","maintainAspectRatio":"true","delivery":"progressive","width":"854"}]]>
</AdParameters>
</syntaxhighlight>

==== Server-Side Integration ====

If you are interested in implementing the DAR tags server-side, e.g. through SSAI, please contact your Nielsen TAM to provide you with the required guidelines.

==== Notes ====

Manual placement of the DAR Video tag is only recommended in situations where the DAR vWrap tag can not be utilized, like in certain mobile in-app ad placements or in scenarios where DAR Video needs to be configured as OMID viewability measurement solution.

== Pixel Tag==

The DAR Impression pixel provides basic campaign impression counts and allows to cover placements served in environments where the DAR JavaScript tag is not supported.

=== Environment ===

The DAR pixel tag should only be used in environments where the DAR JavaScript tag cannot be utilized such as restricted CTV environments, for SSAI Server-Side Beaconing, and other situations where an adequate JavaScript environment is not available.

=== Parameters ===

The minimum required DAR parameters are '''ca, ci, ce, cr, pc''', and '''am''' along with fixed valued params, '''at=view''', '''rt=banner''' and '''st=image''' . See the [[DAR_Tag_Implementation_Guide#Appendix|'''Appendix''']] for a full list of parameters.

=== Example Tag ===
<syntaxhighlight lang="html">
<img src="https://secure-gl.imrworldwide.com/cgi-bin/m?ca=nlsnXXXXXX&cr=crtve
&ce={PUBLISHER.ID}&pc=PLACEMENT.ID}&nlsnciXXXX&am=3&at=view&rt=banner&st=image
&cy=0&r=[timestamp]" style="display:none"/>
</syntaxhighlight>

= Tag Integration =
A successful tag integration will require you to go through the following 6 steps.
== Step 1: Determine Your Campaign Needs==
To receive optimal results from DAR measurement, it is good practice to consider the technical requirements of different sites and placements. Please share your media plan with your Technical Account Manager before launch.

Specifically, be on the lookout for placements that might span across web and mobile ad inventory and make sure if all of the in-app placements support OMID. Also, some placement types may need manual setup and cannot be automated or may need extra time for setup and testing.

Please reach out to your Nielsen Technical Account Manager (TAM) for advice if the technical requirements for your campaign are not clear.
== Step 2: Generate Tags==
Your Nielsen representative will walk you through the Campaign Management Interface (CMI) so that you can generate DAR tags for your campaigns at any time.

Nielsen supports macro-based tag generation for several major ad servers. Nielsen’s Technical Account Managers can assist you with any technical questions on tagging campaigns for DAR measurement.
== Step 3: Campaign Integration==
Your Nielsen tags created in CMI will need to be included when you traffic your ad campaigns. Please reach out to your Nielsen TAM for additional guidance and assistance.
== Step 4: Test the Tag Implementation==
Depending on the complexity of the integration, you may be working closely with a TAM at this point or are performing a self-guided tag implementation based on the CMI output.

If working with a TAM, they will coordinate a plan to test the tag implementation ahead of the campaign go-live date. Depending on your campaign needs, testing will involve either running a diagnostic campaign to validate tagging setup or reviewing test pages or apps.

In case of a self-guided tag implementation, we recommend to verify and compare the impression counts in the CMI with your planned campaign volume or ad server reports during the first hours of the campaign. If there are any unexpected impression counts, please reach out to your Nielsen TAM.
== Step 5: Share your Ad Server Report==

=== Why the Ad Server Report is Needed ===

Knowing the delivered impressions helps Nielsen run Discrepancy Checks ensuring overall quality and reduces errors in the tagging process.

Nielsen can provide the client with a template with the inputs required to complete the quality checks.

=== How to Share Your Delivered impressions ===

Set up an automated daily report from your ad server containing Site Name, Site ID, Placement Name, Placement ID, and data date.

A secondary method to share your media plan information is to grant Nielsen “Reporting access” to your campaign in the designated ad server (such as DCM). To do this, simply grant the login '''clientreporting@nielsen.com''' access. In doing so Nielsen can directly access your media plan information, which enables us to check for updates, and reconcile any discrepancies.

== Step 6: Monitoring Your Campaign==
Nielsen recommends all clients participate in Discrepancy Checks. Nielsen’s team will verify that the tags delivered have begun to receive data once the campaign goes live and will regularly (typically every 7-14 days) compare the Nielsen reporting to your 3rd party or publisher reporting to ensure we are capturing all data across all placements, as expected, and that the discrepancy gap between your reporting and the Nielsen reporting is kept to a minimum.

= Appendix =
== Tag Parameters==
All passthrough parameters will appear on the JavaScript-generated DAR impression ping.
{| class="wikitable" style="background-color:#FFF;"
|- style="font-weight:bold; background-color:#EAECF0; color:#222;"
! Query Parameter
! Description
! style="text-align:center;" | Required
! style="text-align:center;" | Pass-through
|- style="font-weight:bold; text-align:center; vertical-align:middle; background-color:#FFEBD3; color:#222;"
| colspan="4" | Group 1 - Required Parameters
|- style="vertical-align:middle; color:#222;"
| ca
| Campaign ID
| style="text-align:center;" | X
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| pc
| Placement ID
| style="text-align:center;" | X
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| ci
| Client ID
| style="text-align:center;" | X
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| am
| Ad server ID
| style="text-align:center;" | X
| style="text-align:center;" | X
|- style="color:#222;"
| ce
| Site ID
| style="text-align:center;" | X
| style="text-align:center;" | X
|- style="background-color:#F4F5F7; color:#222;"
| cr
| Creative ID
| style="text-align:center; background-color:#EFEFEF;" | X
| style="text-align:center;" | X
|- style="font-weight:bold; text-align:center; vertical-align:middle; background-color:#FFEBD3; color:#222;"
| colspan="4" | Group 2 - Use Case Specific Parameters
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| at
| Fixed Value "view" (Nielsen value, JS tags add this to DAR and NMP pings)
| style="text-align:center;" | Pixel only
|
|- style="vertical-align:middle; color:#222;"
| st
| Fixed Value "image" (Nielsen value, JS tags add this to DAR and NMP pings)
| style="text-align:center;" | Pixel only
|
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| rt
| Fixed Value "banner" (Nielsen value, JS tags add this to DAR and NMP pings)
| style="text-align:center;" | Pixel only
|
|- style="vertical-align:middle; color:#222;"
| r
| Cachebuster/Timestamp. It's required in the pixel tags with a hardcoded value as a default or a macro (r=timestamp/macro) .
| style="text-align:center;" | Pixel only
|
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| cy
| Creative type (1: display/2: video) JS tags add this to DAR and NMP pings for In-House Viewability. When parameter is not present or value is missing on pixel tags, there will be no creative type breakout. 
| style="text-align:center;" | Pixel only
|
|- style="vertical-align:middle; color:#222;"
| '''[[DAR_Tag_Implementation_Guide#vWrap_apiframework_Values|apiframework]]'''
| IAB-defined value designating the measurement method See vWrap apiframework values
| style="text-align:center;" | vWrap only
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| autof
| Video only: Auto refresh (1 for auto refresh, leave empty otherwise)
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| autop
| Video only: Autoplay (1 for auto-play, 2 for click-to-play, leave empty otherwise)
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| c7
| OS Grouping c7=osgrp,IOS c7=osgrp,DROID c7=osgrp,ANDROID
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| c8
| Device Grouping c8=devgrp,DSK (computers) c8=devgrp,PHN (mobile phone devices) c8=devgrp,TAB (mobile tablet devices) c8=devgrp,PMP (portable media player) c8=devgrp,UNWN (unknown mobile devices)
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| c9
| Mobile Advertising ID c9=devid,xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
| style="text-align:center;" | Mobile
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| c10
| Platform c10=plt,DSK (Computer) c10=plt,MBL (Mobile) c10=plt,OTT (Connected Device)
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| c12
| App Version c12=apv,xxx
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| c13
| Nielsen Assigned App ID Example: c13=asid,xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
| style="text-align:center;" | Mobile
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| c14
| OS Version c14=osver,xxx
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| c68
| Mobile App Bundle ID c68=bndlid,xxxxxxxxxxxxxx References: https://developer.apple.com/documentation/appstoreconnectapi/bundle_ids https://developer.android.com/studio/build/configure-app-module#set_the_application_id
| style="text-align:center;" | Mobile
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| C78
| Custom Integration Flag (please note: this is the only uppercase parameter name)
| style="text-align:center;" | some vendors
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| darsup
| If present suppress DAR main ping originating from JS tag (value can be 0 or 1, same effect)
|
|
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| forceid
| If present provides impid, can be overwritten by impid parameter
|
| style="text-align:center;" | X (as impid)
|- style="vertical-align:middle; color:#222;"
| impid
| Same as forceid, but higher priority in case both are present
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| frcd
| Video only: Forced duration (seconds/null)
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| frcf
| Video only: Forced ad flag (yes/no/null)
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| ptraf
| Video only: Purchased traffic
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| contplay
| Video only: Continuous play
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| gdpr
| GDPR flag to indicate whether GDPR is applicable: 0 - GDPR does not apply 1 - GDPR applies
| style="text-align:center;" | in some jurisdictions
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| gdpr_consent
| URL-safe base64-encoded Transparency & Consent (TC) string for identifying user's privacy preferences
| style="text-align:center;" | in some jurisdictions
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| hem_md5
| Hashed email
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| hem_sha1
| Hashed email
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| hem_sha256
| Hashed email
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| hem_unknown
| Hashed email
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| mode
| VPAID video only, optional: Custom Direct Access mode ("w" wrapper / "c" custom; defaults to wrapper)
|
|
|- style="vertical-align:middle; color:#222;"
| onload
| VPAID video only, optional: JS callback for Custom Direct Access VPAID integration
|
|
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| pub
| Publisher Name
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| pubid
| Publisher ID
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| si
| Site identifier. Canonical URL of the content where the Ad creative is served. The parameter value has to be encoded with encodeURIComponent() method or equivalent.
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| uid2
| Unified ID 2.0
|
| style="text-align:center;" | X
|- style="vertical-align:middle; background-color:#EFEFEF; color:#222;"
| uid2_token
| Unified ID 2.0 token
|
| style="text-align:center;" | X
|- style="vertical-align:middle; color:#222;"
| uoo
| User opt out
| style="text-align:center;" | Mobile
| style="text-align:center;" | X
|- style="font-weight:bold; text-align:center; vertical-align:middle; background-color:#FFEBD3; color:#222;"
| colspan="4" | Group 3 - Parameters With Required Position in URL
|- style="vertical-align:middle; background-color:#ffffff; color:#222;"
| vpaidURL
| VPAID Video only: Always the last parameter for video tags. Either VPAID ad unit URL to be wrapped or empty. If empty, DAR tag will use its own vpaidplayer.js
| style="text-align:center;" | VPAID video tag only
|
|- style="background-color:#f4f5f7;"
| style="vertical-align:middle; color:#222;" | vastURL
| style="vertical-align:middle; color:#222;" | vWrap Tag only: Always the last parameter for the vWrap tag. It must contain the URL of the original VAST for the placement.
| style="text-align:center; vertical-align:middle; color:#222;" | vWrap tag only
|
|}

== Additional Parameters ==
This section describes several important additional parameters that the DAR tag can support, specifically Hashed Email, UID2 values, along with Page URL and Bundle Identifier if available. Please note that all parameters are case-sensitive.

Please work with your Nielsen Technical Account Manager to decide which of the following parameters to append to the standard DAR tag.
=== HEM Support (Hashed Email) ===
Please use the parameter that matches your hashing algorithm. For example, if you are using sha256 to encode the email address, then use hem_sha256={encrypted_value_here}
{| class="wikitable" style="font-weight:bold; background-color:#EAECF0;"
|-
! Name
! Description
! Available Tag Parameters
|- style="font-weight:normal; background-color:#F8F9FA;"
| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) to create a unique hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
| &hem_unknown &hem_sha256 &hem_md5 &hem_sha1
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#dae8fc; color:#002041;"
! Example
|- style="font-weight:normal;"
| hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
|}

=== Unified ID ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Unified ID 2.0
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.
| &uid2
|-
| Unified ID 2.0 Token
| Encrypted Unified ID 2.0
| &uid_token
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k= uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5 /xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
|}
=== Page and Bundle ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Page URL
| Canonical URL of the content where the Ad creative is served. (e.g. https://example.com/news/tech/article.html) The parameter value has to be encoded with JavaScript’s encodeURIComponent() method or equivalent. Example: si=https%3A%2F%2Fexample.com%2Fnews%2Ftech%2Farticle.html
| &si
|-
| App Bundle ID
| The app’s unique bundle ID (e.g. com.example.myapp). The ID can be used to look up the App in Apple’s App Store or the Google Play Store. References: https://developer.android.com/studio/build/application-idhttps://developer.apple.com/documentation/appstoreconnectapi/bundle_ids
| &c68=bndlid
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| si=https%3A%2F%2Fexample.com%2Fnews%2Ftech%2Farticle.html c68=bndlid,com.tam.nielsen.com
|}

== vWrap apiframework Values==

Nielsen’s vWrap tag uses the existing definition of '''apiframework''' values defined in the IAB’s [https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list--api-frameworks- '''AdCOM Specification''' '''1.0''']. This means that existing macros for this parameter in your system should work out of the box with vWrap.

The vWrap tag supports the numerical values in bold below. In case of '''8''' (SIMID), the DAR Video tag will be inserted as a standard OMID verification client for viewability measurement and it will not interfere with any SIMID components in the ad.

If a '''0''' or an empty value is given, the resulting VAST will include both OMID and VPAID measurement solutions. This leaves the decision of the measurement method to the video player, which might be advantageous for mixed campaigns that span mobile and web environments.

{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#F4F5F7;"
! Value
! Definition
|-
| 1
| style="font-weight:normal;" | VPAID 1.0
|-
| 2
| style="font-weight:normal;" | VPAID 2.0
|- style="font-weight:normal; color:#666;"
| 3
| MRAID 1.0
|- style="font-weight:normal; color:#666;"
| 4
| ORMMA
|- style="font-weight:normal; color:#666;"
| 5
| MRAID 2.0
|- style="font-weight:normal; color:#666;"
| 6
| MRAID 3.0
|-
| 7
| style="font-weight:normal;" | OMID 1.0
|-
| 8
| style="font-weight:normal;" | SIMID 1.0
|}

== SERVER-SIDE TAG DISPATCH ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on mobile in-app or connected devices is for the publisher to trigger the tag upon ad exposure to the user (either directly or via the ad server). This can be described as a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the ad exposure event still be initiated and recorded from the client-side, even if the ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (eg. publisher log file or similar) from the MRC/IAB to substantiate that the user was exposed to the ad on their device.

In addition to the tag parameters covered in the prior sections, the following HTTP headers need to be modified in the DAR calls to support dispatch from a '''server-side''' publisher ad server:

{| class="wikitable"
|- style="text-align:center; background-color:#c0c0c0; color:#000000;"
! HTTP Headers
! Description of Modifications
|-
| User-Agent (UA)
| This is expected to be the originating client user-agent for the device where the user was exposed to the ad. The HTTP UA from the client device should be used to populate the HTTP UA in the server-side connection/ping. DAR leverages the type of device for platform derivation.
|-
| X-Forwarded-For (XFF) IP
| This is expected to be the originating client IP address for the device where the user was exposed to the ad. Note: When the tag is fired directly from the ad server, the X-Real-IP will be the ad server IP.
|}

=== Server Side Tag Notes ===

* The server-side tag collection only supports mobile in-app and connected device measurement and will not support cookie-based browser measurement.

* The client’s server-side setup to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed, then invalid traffic (IVT) filtration will be triggered upon receiving the 2nd and nth tag.

* The tag received by Nielsen must be TLS v1.2 compliant or greater.

== About Nielsen ==

Nielsen shapes the world’s media and content as a global leader in audience measurement, data and analytics. Through our understanding of people and their behaviors across all channels and platforms, we empower our clients with independent and actionable intelligence so they can connect and engage with their audiences—now and into the future.

An S&P 500 company, Nielsen (NYSE: NLSN) operates around the world in more than 55 countries. Learn more at [http://www.nielsen.com '''www.nielsen.com'''] or [http://www.nielsen.com/investors '''www.nielsen.com/investors'''] and connect with us on social media.

'''Audience Is Everything®'''

Mobile DAR Attributes Requirements

2022-09-20T23:43:45Z

ColinBrown: /* Additional Parameters */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=0&r=<timestamp> </code>

{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory parameter for mDAR?
|-
| &c7 || OS Grouping ||
|- style="background-color:#eff8ef;"
| &c8 || Device Grouping || <center>✔</center>
|-
| &c9 || Advertising ID || <center>✔</center>
|- style="background-color:#eff8ef;"
| &c10 || Platform || <center>✔</center>
|-
| &c12 || App Version ||
|- style="background-color:#eff8ef;"
| &c13 || AppID (Nielsen assigned App ID) || <center>✔</center>
|-
| &c14 || OS Version ||
|- style="background-color:#eff8ef;"
| &uoo || Opt-out indicator || <center>✔</center>
|}
<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>
== Additional Parameters ==
This section describes several important additional parameters that the DAR tag can support, specifically Hashed Email, and UID2 values. Please note that all parameters are case-sensitive.

Please work with your Nielsen Technical Account Manager to decide which of the following parameters to append to the standard DAR tag.
=== HEM Support (Hashed Email) ===
Please use the parameter that matches your hashing algorithm. For example, if you are using sha256 to encode the email address, then use hem_sha256={encrypted_value_here}
{| class="wikitable" style="font-weight:bold; background-color:#EAECF0;"
|-
! Name
! Description
! Available Tag Parameters
|- style="font-weight:normal; background-color:#F8F9FA;"
| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) to create a unique 32-character hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
| &hem_unknown &hem_sha256 &hem_md5 &hem_sha1
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#dae8fc; color:#002041;"
! Example
|- style="font-weight:normal;"
| hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
|}
=== Unified ID ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Unified ID 2.0
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.
| &uid2
|-
| Unified ID 2.0 Token
| Encrypted Unified ID 2.0
| &uid_token
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k= uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5 /xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
|}

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

Mobile DAR Attributes Requirements

2022-09-20T23:43:12Z

ColinBrown: /* UOO - Opt Out */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=0&r=<timestamp> </code>

{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory parameter for mDAR?
|-
| &c7 || OS Grouping ||
|- style="background-color:#eff8ef;"
| &c8 || Device Grouping || <center>✔</center>
|-
| &c9 || Advertising ID || <center>✔</center>
|- style="background-color:#eff8ef;"
| &c10 || Platform || <center>✔</center>
|-
| &c12 || App Version ||
|- style="background-color:#eff8ef;"
| &c13 || AppID (Nielsen assigned App ID) || <center>✔</center>
|-
| &c14 || OS Version ||
|- style="background-color:#eff8ef;"
| &uoo || Opt-out indicator || <center>✔</center>
|}
<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>
== Additional Parameters ==
This section describes several important additional parameters that the DAR tag can support, specifically Hashed Email, UID2 values, along with Page URL and Bundle Identifier if available. Please note that all parameters are case-sensitive.

Please work with your Nielsen Technical Account Manager to decide which of the following parameters to append to the standard DAR tag.
=== HEM Support (Hashed Email) ===
Please use the parameter that matches your hashing algorithm. For example, if you are using sha256 to encode the email address, then use hem_sha256={encrypted_value_here}
{| class="wikitable" style="font-weight:bold; background-color:#EAECF0;"
|-
! Name
! Description
! Available Tag Parameters
|- style="font-weight:normal; background-color:#F8F9FA;"
| Hashed Email
| User’s email address that has been run through a hashing algorithm (e.g. SHA256, MD5, SHA1) to create a unique 32-character hexadecimal string. If a client is unable to determine hashing type, they should pass using &hem_unknown parameter.
| &hem_unknown &hem_sha256 &hem_md5 &hem_sha1
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#dae8fc; color:#002041;"
! Example
|- style="font-weight:normal;"
| hem_sha256=tMmiiTI7IaAcPpQPFQ65uMVCWH8av9jw4cwf/F5HVRQ=
|}
=== Unified ID ===
{| class="wikitable" style="background-color:#F8F9FA;"
|- style="font-weight:bold; background-color:#EAECF0;"
! Name
! Description
! Available Tag Parameters
|-
| Unified ID 2.0
| An identifier based on a user’s verifiable PII (e.g. hashed email). UID2.0 was initially created by The Trade Desk (TTD) and is now managed by Prebid.
| &uid2
|-
| Unified ID 2.0 Token
| Encrypted Unified ID 2.0
| &uid_token
|}
{| class="wikitable" style="font-weight:bold;"
|- style="background-color:#32BBB9; color:#002041;"
! Example
|- style="font-weight:normal;"
| uid2=MTKVpUAzwYAPnHrtfE0wlINOMzhU7UUEjjVdCdRu63k= uid_token=AgAAAAPFR0zA5ogv/yaAPiUsAdZPsfqS8QlDSGxAB+rr8yekFs3AjLYVk5qqqiyV2XHbSuwzHmxSlLeQeKQI1mp015jsNnpX5 /xGgXldcgVz+gFnyh3T8/3agMwRmyrhCxG4oH2C7fc48AQk2eotE7FW0ZDEYM8fD9ZxDaxFUC/OV3OuZA&
|}

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

AGF Implementation Documentation

2022-08-19T20:34:15Z

ColinBrown:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|DCR.png|AGF Documentation & Downloads}}

__NOTOC__

<blockquote>The following guides are specific for AGF.</blockquote>

= Video Measurement =

{| class="wikitable"
|-
! style="width: 90px;" | AGF
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
!| Links
|-
| rowspan="5" | {{SmallIcon|DEFlagIcon.png}}
| rowspan="4" | {{SmallIcon|SDKIcon.png}}
| rowspan="5" | {{OSIcon|VideoIcon.png}}
|
|''' [https://nielsendownloads.digitalengsdk.com/digital/200608_AGF_Custom_Variables_and_Metadata_DCR_SDK_v1.7.pdf%20Metadata%20Document MetaData Documentation]'''
|-
| {{OSIcon|macOSIcon.png}}
| '''[[DCR Germany Video App SDK|AGF iOS Implementation Guide]]'''
| '''[https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-AGFNoId_latest.zip AGF iOS No ID (Preferred)]'''
|-
| {{OSIcon|AndroidIcon.png}}
| '''[[DCR_Germany_Video_App_SDK|AGF Android Implementation Guide]]'''
| '''[https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-Android-App-SDK_AgfNoId_latest.zip Android AGF No ID Download (Preferred)]'''
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR_Germany_Video_Browser_SDK|AGF Browser Implementation Guide]]'''
|
|-
| {{SmallIcon|CloudAPIIcon.png}}
| {{OSIcon|APIIcon.png}}
| '''[[DCR Germany Video Cloud API|AGF Video Cloud Implementation Guide]]'''
|
|}

= Static Measurement =

{| class="wikitable"
|-
| colspan="7" style="background-color:white;" |
|-
! style="width: 90px;" | AGF
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
!| Links
|-
| rowspan="4" | {{SmallIcon|DEFlagIcon.png}}
| rowspan="4" | {{SmallIcon|SDKIcon.png}}
| rowspan="5" | {{OSIcon|StaticIcon.png}}
| {{OSIcon|macOSIcon.png}}
| '''[[DCR_Germany_Static_App_SDK|DCR iOS Static App SDK]]'''
| rowspan="1" | '''[https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-AGFNoId_latest.zip AGF iOS No ID (Preferred)]'''
|-
| {{OSIcon|AndroidIcon.png}}
|'''[[DCR_Germany_Static_App_SDK|DCR Android Static App SDK]]'''
|'''[https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-Android-App-SDK_AgfNoId_latest.zip Android AGF No ID Download (Preferred)]'''
|-
| rowspan="2" |{{OSIcon|BrowserIcon.png}}
| '''[[DCR Germany Static Browser SDK]]'''
|
|-
| '''[[DCR Germany Static Google Tag Manager]]'''
|
|}

Digital Measurement iOS Swift Package Manager Guide

2022-08-17T18:34:13Z

ColinBrown:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Downloads}} {{Breadcrumb|Digital Measurement iOS Artifactory Guide}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__NOTOC__
The Nielsen AppSDK can either be downloaded directly or can be integrated within an application through the use of a CocoaPods, Carthage or Swift Package Manager.

= How to integrate Nielsen SDK in iOS/tvOS application using Swift Package Manager =
Initially the Swift Package Manager (SPM) was created as a tool for managing the distribution of Swift code. It’s integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies. However, starting from the Swift 5.3 it allows to add binary dependencies and to import proprietary, closed-source libraries into applications also.

== Swift Package Manager Installation ==
The Swift Package Manager is available as a part of the Xcode application for MacOS. We recommend to use the Xcode version 12.x with Swift 5.3 that is the minimum required version of Swift with binary dependencies support. Apple Xcode can be downloaded and installed using Mac App Store application or from the Apple web site (https://developer.apple.com/account) in the Downloads section.

== XCFramework package ==
Swift Package Manager only supports XCFramework type of package for binary distribution. This a new type of package supported by Apple. It has a number of benefits against the fat library packaged into a framework. First of all it allows to combine device and simulator slices into one package and it is not needed to write custom run scripts to exclude simulator slices from the embedded frameworks before deploying apps. Also XCFramework allows to combine binaries for different platforms, like iOS, tvOS, MacOS. Nielsen SDK added support for XCFramework packages and they are now available for SPM distribution.

== Repository Credentials ==
SDK framework packages are stored on a public Github repository.
To access that you do not need any credentials.

== SDK integration ==
Two approaches of the SDK integration are applicable for SPM:
# SDK integration using local SPM package
# SDK integration using the Xcode project settings

=== SDK integration using local package ===
Nielsen AppSDK can be integrated to an application by setup local SPM package with dependencies the remote Nielsen SDK package.
# In the Xcode from the menu go to: File -> New -> Package... - to create the new local package by specifying it's name and location.
# Close the Xcode instance with the just created package.
# In the Xcode with the application project from the menu go to: File -> Add Packages... -> Add local... - to add local package into the application project by specifying the package folder.
# In order to integrate the local package into your application open your application targets’ General settings tab. In the "Frameworks, Libraries, and Embedded Content" section tap: + -> Workspace -> <Package Name> -> <Package Name> -> Add.
# In the Xcode in the Project Navigator go to: <Project Name> -> Packages -> <Package Name> -> Package.swift - to open SPM package manifest file in Xcode editor.
# Update the package manifest with a minimal template below to use the remote Nielsen SDK package as a dependency: <syntaxhighlight lang=Swift>

// swift-tools-version:5.3
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
name: "<Package Name>",
products: [
// Products define the executables and libraries a package produces, and make them visible to other packages.
.library(
name: "<Package Name>",
targets: ["<Package Name>"])
],
dependencies: [
// Dependencies declare other packages that this package depends on.
// .package(url: /* package url */, from: "1.0.0"),
.package(url: "https://github.com/NielsenDigitalSDK/<REPO_NAME>",
from: "8.2.0")
],
targets: [
// Targets are the basic building blocks of a package. A target can define a module or a test suite.
// Targets can depend on other targets in this package, and on products in packages this package depends on.
.target(
name: "<Package Name>",
dependencies: [
.product(name: "NielsenAppApi",
package: "<REPO_NAME>")
]
)
]
)
</syntaxhighlight>
# In the package definition statement decide whether your project dependency accepts updates up to the next major version or up to the next minor version. To be more restrictive, select a specific version range or an exact version. <syntaxhighlight lang=Swift>
.package(url: "https://github.com/NielsenDigitalSDK/<REPO_NAME>",
from: "8.2.0")
</syntaxhighlight> For detailes please see: https://developer.apple.com/documentation/swift_packages/package/dependency
# Please specify the <REPO_NAME> parameter according to the product you need for the application, refer the Nielsen AppSDK Products section: e.g. nielsenappsdk-ios-dynamic-spm-global.
<syntaxhighlight lang=Swift>
dependencies: [
.product(name: "NielsenAppApi",
package: "nielsenappsdk-ios-dynamic-spm-global")
]
</syntaxhighlight>

For an additional technical details please refer to: https://developer.apple.com/documentation/xcode/creating_a_standalone_swift_package_with_xcode

=== SDK integration using the Xcode project settings ===
Nielsen AppSDK can be integrated to an application by setup the remote SDK package in the Xcode project settings explicitly.
# In the Xcode from the menu go to: File -> Swift Packages -> Add Package Dependency... - to setup the remote Nielsen SDK package.
# In the appeared popup please enter the repository address according to the product you need for the application: https://github.com/NielsenDigitalSDK/<REPO_NAME>. Example: https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-global
# On the next screen please define an SDK version for integration. There are options available for the selection. Decide whether your project accepts updates to a package dependency up to the next major version or up to the next minor version. To be more restrictive, select a specific version range or an exact version.
# On the next dialog please select NielsenAppApi product and add it(s) to the particular application build target(s).
 

Notes: 
1. We are aware about the Xcode 13.3 issue with SPM integration of the framework where its name does not match the target name: https://stackoverflow.com/questions/71539013/spm-artifact-not-found-for-target-aaa-xcode-13-3-only. 
In the release 8.2.0 we have addressed this issue. Please update to the release 8.2.0 if this is happening. 
2. In some scenarios after upgrading to the latest SDK release Xcode shows a number of compilation warning/error messages saying that duplicate symbols exist in the code. Please goto menu <File> -> <Packages> and press <Reset Package Caches> if this is happening. 

== Nielsen AppSDK Versions ==
iOS/tvOS AppSDK has 4 digits in the version numbers, but the SPM packages should conform to semantic versioning and contain only 3 digits in the version number. Please use only 3 first digits while specifying the exact version of the SDK:
<syntaxhighlight lang=Javascript>
8.0.0.0 -> 8.0.0
</syntaxhighlight>
Nielsen AppSDK is available for distribution through the Swift Package Manager starting from 8.0.0.0 version only.

== Nielsen AppSDK Products ==
Each specific version of the Nielsen AppSDK package created for the Swift Package Manager distribution has its own set of XCFramework builds. Each XCFramework is stored on its own repository: 

=== Global flavors ===
{| class="wikitable"
|- style="background-color:#efefef;"
! App Flavor !! Repository Name (REPO_NAME)!! Repository URL
|-
| Global || '''nielsenappsdk-ios-dynamic-spm-global''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-global
|-
| Global No Ad || '''nielsenappsdk-ios-dynamic-spm-globalnoad''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-globalnoad
|-
| Global No Id (for 'kids' apps) || '''nielsenappsdk-ios-dynamic-spm-globalnoid''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-globalnoid
|}

=== Regional flavors ===
{| class="wikitable"
|- style="background-color:#efefef;"
! App Flavor !! Repository Name (REPO_NAME)!! Repository URL
|-
| AGF || '''nielsenappsdk-ios-dynamic-spm-agf''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agf
|-
| AGF No Ad || '''nielsenappsdk-ios-dynamic-spm-agfnoad''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agfnoad
|-
| AGF No Id (for 'kids' apps) || '''nielsenappsdk-ios-dynamic-spm-agfnoid''' || https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-dynamic-spm-agfnoid
|}

Frameworks for tvOS platform do not have their specific repositories as they are distributed as part of the same XCFramework.
The following SDK versions are now available for distribution through SPM: 
8.0.0

More details about SPM integration can be found in the official Apple documentation: https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app 
Please note: Nielsen AppSDK is distributed through SPM as dynamic framework only. 

== Additional Resources for Swift Package Manager ==
For more information on [https://swift.org/package-manager/ Swift Package Manager] or How to integrate the package into an application [https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app here].

Template:iOS Prerequisites and Implementation Overview

2022-08-17T18:28:22Z

ColinBrown: /* How to obtain the NielsenAppApi.Framework */

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; ''See [[iOS SDK Release Notes]]'' || [[Special:Downloads|Download]]
|}

If need App ID(s) or our SDKs, feel free to reach out to us and we will be happy to help you get started.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

== Implementation ==
Version 8 of the Nielsen App SDK will come in three versions. One that is enabled to work with the App Tracking Transparency Framework, another version that does not use the Ad Framework, and a version for Kids Apps or where noID is required.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''iOS Ad Version'''
|* Opt-In and Opt-Out functionality managed by the [https://developer.apple.com/documentation/apptrackingtransparency AppTrackingTransparency framework] . '''(Preferred approach)''' * The Nielsen SDK will attempt to collect the IDFA (Id for Advertisers) on the device. * For iOS14+, if the value returned is <code>ATTrackingManager.AuthorizationStatus.authorized</code>. * If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested.
|-
| '''iOS No Ad Framework'''
|* Without the Ad Framework, the Nielsen SDK cannot read the IDFA, so it will attempt to retrieve the '''IDFV'''. * The [https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor ID for Vendors (IDFV)], may be used for analytics across apps from the same content provider. * The developer is required to present the User Choice Opt Out page which is described in the [[DCR_Video_iOS_SDK#User_Choice|Privacy Section]].
|-
| '''iOS SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * Please review the [https://engineeringportal.nielsen.com//docs/DCR_Video_Android_SDK#Special_Note_Regarding_Apps_in_the_Kids_Category Opt Out Requirement].
|}
=== How to obtain the NielsenAppApi.Framework ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|iOS Package Dependency Guides (CocoaPods, Carthage, Swift Package Manager)]]
* [[Special:Downloads|Select to Download Directly]]
* [[DCR_Video_iOS_SDK_xcframework|Using the XCFramework bundle]]

Template:iOS Prerequisites and Implementation Overview

2022-08-17T18:27:53Z

ColinBrown: /* How to obtain the NielsenAppApi.Framework */

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; ''See [[iOS SDK Release Notes]]'' || [[Special:Downloads|Download]]
|}

If need App ID(s) or our SDKs, feel free to reach out to us and we will be happy to help you get started.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

== Implementation ==
Version 8 of the Nielsen App SDK will come in three versions. One that is enabled to work with the App Tracking Transparency Framework, another version that does not use the Ad Framework, and a version for Kids Apps or where noID is required.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''iOS Ad Version'''
|* Opt-In and Opt-Out functionality managed by the [https://developer.apple.com/documentation/apptrackingtransparency AppTrackingTransparency framework] . '''(Preferred approach)''' * The Nielsen SDK will attempt to collect the IDFA (Id for Advertisers) on the device. * For iOS14+, if the value returned is <code>ATTrackingManager.AuthorizationStatus.authorized</code>. * If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested.
|-
| '''iOS No Ad Framework'''
|* Without the Ad Framework, the Nielsen SDK cannot read the IDFA, so it will attempt to retrieve the '''IDFV'''. * The [https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor ID for Vendors (IDFV)], may be used for analytics across apps from the same content provider. * The developer is required to present the User Choice Opt Out page which is described in the [[DCR_Video_iOS_SDK#User_Choice|Privacy Section]].
|-
| '''iOS SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * Please review the [https://engineeringportal.nielsen.com//docs/DCR_Video_Android_SDK#Special_Note_Regarding_Apps_in_the_Kids_Category Opt Out Requirement].
|}
=== How to obtain the NielsenAppApi.Framework ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|iOS Package Dependency Guides (cocoapods, carthage, Swift Package Manager)]]
* [[Special:Downloads|Select to Download Directly]]
* [[DCR_Video_iOS_SDK_xcframework|Using the XCFramework bundle]]

US DCR & DTVR

2022-08-09T20:08:02Z

ColinBrown: /* SDK - Static */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|DCR.png|US Digital Content Ratings (DCR) & Digital in TV Ratings (DTVR)}}

__NOTOC__

{| class="wikitable"
|-
! style="width: 90px;" |
! style="width: 42%;" | General Reference
!
|-
| rowspan="7" | {{SmallIcon|DigitalIcon.png}}
| '''[[Digital Measurement Onboarding]]'''
| '''[[Digital Measurement Metadata]]'''
|-
| '''[[Digital Measurement Testing]]'''
| '''[[Digital Measurement Interruption Scenarios]]'''
|-
| '''[[Digital Measurement FAQ]]'''
| '''[[iOS SDK App Privacy|App Privacy Details for App Store]]'''
|-
| '''[[Digital Pre-Certification Checklist App SDK]]'''
| '''[[Digital Pre-Certification Checklist Browser SDK]]'''
|}

== SDK - Video ==
{| class="wikitable"
| colspan="6" | Maintaining an existing ''DCR'' or ''DTVR'' App integration? Continue to reference the API you're already using with the guides below.
|-
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
! style="width: 30%;" | DCR Implementation Guide
! style="width: 25%;" | DTVR Implementation Guide
!| SDK Documentation
|-
| rowspan="7" | {{SmallIcon|SDKIcon.png|alt=SDK}}
|-
| rowspan="3" | {{OSIcon|VideoIcon.png|alt=Video}}
| {{OSIcon|macOSIcon.png|alt=iOS}}
| '''[[DCR Video iOS SDK]]'''
| '''[[DTVR iOS SDK]]'''
| [[iOS SDK API Reference]]
|-
| {{OSIcon|AndroidIcon.png|alt=Android}}
| '''[[DCR Video Android SDK]]'''
| '''[[DTVR Android SDK]]'''
| [[Android SDK API Reference]]
|-
| {{OSIcon|BrowserIcon.png|alt=Browser}}
| '''[[DCR Video Browser SDK]]'''
| '''[[DTVR Browser SDK]]'''
| [[Browser SDK API Reference]]
|}

== SDK - Static ==
{| class="wikitable"
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
! style="width: 55%;" | DCR Implementation Guide
!| SDK Documentation
|-
| rowspan="8" | {{SmallIcon|SDKIcon.png|alt=SDK}}
| rowspan="8" | {{OSIcon|StaticIcon.png|alt=Static Content}}
| {{OSIcon|macOSIcon.png|alt=iOS}}
| '''[[DCR Static iOS SDK]]'''
| [[iOS SDK API Reference]]
|-
| {{OSIcon|AndroidIcon.png|alt=Android}}
| '''[[DCR Static Android SDK]]'''
| [[Android SDK API Reference]]
|-
| rowspan="2" | {{OSIcon|BrowserIcon.png|alt=Browser}}
| '''[[DCR Static Browser SDK]]'''
| rowspan="5" | [[Browser SDK API Reference]]
|-
| '''[[DCR Static Lite Browser SDK]]'''
|-
| {{OSIcon|GoogleTagManagerIcon.png|alt=Google Tag Manager}}
| '''[[DCR Static Google Tag Manager]]'''
|-
| {{OSIcon|FacebookIcon.png|alt=Facebook Instant Articles}}
| '''[[DCR Static Facebook Instant Articles Browser SDK]]'''
|-
| {{OSIcon|Tealium_Icon.png|alt=Tealium}}
| '''[[DCR Static Tealium]]'''
|-
| {{OSIcon|AMPIcon.png|alt=Google AMP}}
| '''[[DCR Static Google AMP Cloud API]]'''
|
|}

== Xamarin ==
{| class="wikitable"
| colspan="6" | Xamarin Integration Guides (Xamarin support is part of [[Special:Downloads|Nielsen's AppSDK V8]] and above.)
|-
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Implementation Guide
|-
| rowspan="8" | {{SmallIcon|SDKIcon.png|alt=SDK}}
|-
| {{OSIcon|VideoIcon.png|alt=Video}}
| {{OSIcon|macOSIcon.png|alt=iOS}}
| colspan="2" | '''[[DCR_%26_DTVR_Xamarin_Integration|DCR & DTVR Xamarin Integration]]'''
|}

== Cloud API ==
{| class="wikitable"
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
!| DCR Implementation Guide
|-
| rowspan="3" | {{SmallIcon|CloudAPIIcon.png|alt=Cloud API}}
| rowspan="3" |
{{OSIcon|VideoIcon.png|alt=Video}}
 
{{OSIcon|StaticIcon.png|alt=Static Content}}
| {{OSIcon|APIIcon.png|alt=Cloud API}}
| '''[[DCR Video & Static Cloud API ]]'''
|-
| {{OSIcon|APIIcon.png|alt=Cloud API}}
| '''[[DCR Video & Static Mobile Cloud API ]]'''
|-
| {{OSIcon|RokuIcon.png|alt=Roku}}
| '''[[DCR Video & Static Roku Cloud API]]'''
|}

== Adobe Launch Extensions ==
{| class="wikitable"
| colspan="6" | Leverage Launch by Adobe? The guides below describe how to integrate DCR and DTVR with Nielsen's Adobe Launch extension
|-
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Implementation Guide
|-
| rowspan="8" | {{SmallIcon|SDKIcon.png|alt=SDK}}
|-
|
|
| colspan="2" | '''[[Digital Measurement Onboarding Adobe ]]'''
|-
| rowspan="3" | {{OSIcon|VideoIcon.png|alt=Video}}
| {{OSIcon|macOSIcon.png|alt=iOS}}
| '''[[DCR & DTVR iOS Adobe Launch Extension]]'''
|-
| {{OSIcon|AndroidIcon.png|alt=Android}}
| '''[[DCR & DTVR Android Adobe Launch Extension]]'''
|-
| {{OSIcon|BrowserIcon.png|alt=Browser}}
| '''[[DCR & DTVR Browser Adobe Launch Extension]]'''
|}

DTVR Browser SDK

2022-08-09T20:07:36Z

ColinBrown: /* Prerequisites */

2022-07-15T23:39:38Z

ColinBrown: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}} Category:Digital == Overview == The Nielsen SDK is one of multiple framewor..."

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The Browser SDK is the framework for browsers developers to integrate Nielsen Measurement into their media player pages. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings ([[DCR & DTVR]]).

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|}

== Configure SDK ==
There are two steps required for configuring the SDK:
*Add Static Queue Snippet
*Create SDK Instance

=== Static Queue Snippet ===
Add the following script tag to the website:
<syntaxhighlight lang="javascript">
<script>

/* NLSQUEUE build v*/
!function(e,n){
function t(e){
return"object"==typeof e?JSON.parse(JSON.stringify(e)):e
}
e[n]=e[n]||
{
nlsQ:function(o,r,c){
var s=e.document,
a=s.createElement("script");
a.async=1,
a.src=("http:"===e.location.protocol?"http:":"https:")+"//cdn-gl.nmrodam.com/conf/"+o+".js#name="+r+"&ns="+n;
var i=s.getElementsByTagName("script")[0];
return i.parentNode.insertBefore(a,i),
e[n][r]=e[n][r]||{g:c||{},
ggPM:function(o,c,s,a,i){e[n][r].q=e[n][r].q||[];try{var l=t([o,c,s,a,i]);e[n][r].q.push(l)}catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}},
trackEvent:function(o){e[n][r].te=e[n][r].te||[];try{var c=t(o);e[n][r].te.push(c)}catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}}},
e[n][r]
}
}
}(window,"NOLBUNDLE");

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");

</script>
</syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

===Create SDK Instance===
To initialize the SDK, create an SDK instance by making the initialization call:

==== Initialization API Call ====
<syntaxhighlight lang="javascript">
NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})
</syntaxhighlight>

When creating an instance, pass the following three values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || 'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
|instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing (not in production) || "{nol_sdkDebug: "debug"})"
|}

==== Example SDK Initialization ====
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</syntaxhighlight>

When the initialization call is made, a unique static configuration file, <apid>.js, will be downloaded based on the apid and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK600.eu.bundle.min.js”.

=== Example SDK Configuration ===
The configuration should include the Static Queue Snippet and an SDK Instance for an unique AppID as shown in the example:
<syntaxhighlight lang="javascript">
<script type="text/javascript">
// Add Static Queue Snippet
!function(e,n){
function t(e){
return"object"==typeof e?JSON.parse(JSON.stringify(e)):e
}
e[n]=e[n]||
{
nlsQ:function(o,r,c){
var s=e.document,
a=s.createElement("script");
a.async=1,
a.src=("http:"===e.location.protocol?"http:":"https:")+"//cdn-gl.nmrodam.com/conf/"+o+".js#name="+r+"&ns="+n;
var i=s.getElementsByTagName("script")[0];
return i.parentNode.insertBefore(a,i),
e[n][r]=e[n][r]||{g:c||{},
ggPM:function(o,c,s,a,i){e[n][r].q=e[n][r].q||[];try{var l=t([o,c,s,a,i]);e[n][r].q.push(l)}catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}},
trackEvent:function(o){e[n][r].te=e[n][r].te||[];try{var c=t(o);e[n][r].te.push(c)}catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}}},
e[n][r]
}
}
}(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", {nol_sdkDebug: "DEBUG"});
</script>
</syntaxhighlight>

=== Create Metadata Objects ===
Before starting any measurement of an asset(Content or Ad) with the created SDK Instance, you need to create an asset metadata object in order to identify the asset. There are two types of asset metadata:

content: identify a video
ad: identify each ad
The metadata received for each asset is used for classification and reporting.

Metadata are passed through key-values using the Nielsen reserved keys. You will need to set up content and ad objects with the required Nielsen keys as shown in the sample code below.

==== Content Metadata ====
Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| type || Type of asset || "content" || Yes
|-
| assetid || Unique ID assigned to content (32 character limit) || custom (no [[Special Characters]])|| Yes
|-
| program || Name of program (100 characters limit) || custom || Yes
|-
| title || Episode title (100 characters limit) || custom || Yes
|-
| length || Length of content in seconds for VOD (Video on demand). The value for live stream content is 0. ||
*"seconds"– VOD
*"0"– Live Stream
||
Yes
|-
| airdate || The airdate in the linear TV. Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || YYYYMMDD hh:mm:ss || Yes
|-
| isfullepisode || Full episode flag ||
*"y"– full episode
*"n"– non full episode
||
Yes
|-
|adloadtype || type of ad load:
* 1) Linear – matches TV ad load
* 2) Dynamic – Dynamic Ad Insertion (DAI)
||
*"1" – content with linear ads
*"2" – content with dynamic ads
||
Yes
|}

==== Example Content Object ====
<syntaxhighlight lang="javascript">
var content_metadata_object = {

// SDK Metadata
type: 'content',
assetid: 'VID123-123456',
program: 'program name',
title: 'episode title',
length: '543', // length in seconds (String)
airdate: '19700101 00:00:00',
isfullepisode: 'y',
adloadtype: '2'

}
</syntaxhighlight>

=== Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> || Yes
|-
| assetid || unique ID assigned to Ad || custom || Yes
|}

==== Example Ad Object ====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{
type: 'preroll',
assetid: 'AD-1'
};
</syntaxhighlight>
 
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== Start the Measurement ===
Nielsen APIs calls are made by calling the function ggPM("event", parameter, ...) with "event" Parameter indicating the SDK API.
<syntaxhighlight lang="javascript">
nSdkInstance.ggPM("event", parameter, ...);
</syntaxhighlight>

{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| "loadMetadata" || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| "setPlayheadPosition" || playhead position as integer 
VOD: current position in seconds 
Live: current Unix timestamp (seconds since 01-01-1970 UTC) 
||
Pass playhead position every second during playback
|-
|-
| "stop" || playhead position in seconds || Call when content interrupted/paused or ads complete playing and pass playhead position
|-
| "end" || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. 
Example: At the end of the content stream, if the user switches to another piece of content when the browser is refreshed or closed.
|}

Start the measurement by calling the "event" names "loadMetadata" followed by "setPlayheadPosition".

<syntaxhighlight lang="javascript">
// START OF STREAM (main content)
nSdkInstance.ggPM("loadMetadata", contentMetadataObject);
// CONTENT plays
// pass playhead every second
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
</syntaxhighlight>

==== Example Events ====

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Content Metadata Object

<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
</syntaxhighlight>

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Pre-roll AD Metadata Object

<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('loadMetadata', prerollMetadataObject);
</syntaxhighlight>

*'''Event:''' setPlayheadPosition | '''Value Pass ( Integer ):''' playheadPosition

<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
</syntaxhighlight>

*'''Event:''' stop | '''Value Pass ( Integer ):''' stopPlayheadPosition

<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('stop', stopPlayheadPosition);
</syntaxhighlight>

*'''Event:''' end | '''Value Pass ( Integer ):''' endPlayheadPosition

<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('end', endPlayheadPosition);
</syntaxhighlight>

== Stop/Resume the Measurement for video Playback Interruptions ==

=== Handle Video Playback Interruption ===
The setPlayheadPostion event is used for handling playback interruption. To indicate that the video player is not playing (i.e. paused, buffering), stop passing the playhead position to the SDK.
Once the Playback resumes , begin sending the playhead position again with the correct playhead value.

=== List of video Playback Interruptions ===
The following possible video Playback Interruptions must be handled:
* Player PAUSED
* Player BUFFERING
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
* Network Loss

=== Example for handling Playback Interruption: Browser/Tab close/Page Reload ===
<syntaxhighlight lang="javascript">
window.addEventListener("beforeunload", function(event)
{
// Only inside an Ad indicate <stop> for the ad
nSdkInstance.ggPM("stop", playheadPosition);

// Indicate <end> for the content
nSdkInstance.ggPM("end", playheadPosition);
});
</syntaxhighlight>

<blockquote>'''Note:''' additional code may be needed in order to support specific browser versions (e.g. older versions of Internet Explorer).</blockquote>

== SDK Call Sequence ==
The sample event lifecycles can be used as a reference for identifying the order for calling events.

=== Content Playback Call Sequence ===
<syntaxhighlight lang="javascript">
// START OF STREAM
nSdkInstance.ggPM("loadMetadata", contentMetadataObject);
// CONTENT plays
// pass playhead every second
//
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
//
// END OF STREAM
nSdkInstance.ggPM("end", playheadPosition);
</syntaxhighlight>

=== Ad Playback Call Sequence (Optional for DR) ===
<syntaxhighlight lang="javascript">
// START OF Ad
nSdkInstance.ggPM("loadMetadata", adMetadataObject);
// Ad plays
// pass playhead every second
//
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
// END OF Ad
nSdkInstance.ggPM("stop", playheadPosition);
</syntaxhighlight>

<blockquote>
* "setPlayheadPosition" is used for calculating duration and must be passed every second. The final playhead position must be sent for the current asset being played before calling "stop" or "end".

* For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at "0" when an ad starts.

* When content has resumed following an ad break, the playhead position update must continue where previous content segment left off.
* The playhead position should be passed as a rounded number with no decimals.
</blockquote>

=== Review SDK Integration Architecture Diagram ===

==== For Content Playback ====

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

==== For Ad Playback ====
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Disclose Nielsen Privacy Statement ==
The Browser SDK video measurement does not set cross-domain cookies, therefore no centralized opt-out functionality is available. The Nielsen Browser SDK does not set cookies associated with the collection domain. The SDK sets specific cookie for the domain where the player is hosted (first party) and this cookie is not used across websites.
The only personal information collected with the SDK network pings is the IP address, which is anonymized immediately after collection.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research.
* A link to the Nielsen Digital Measurement Privacy Policy located at
** https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/

=== Turning off the First Party ID for Opt-out Users ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

===== Example of SDK Initialization with enableFpid =====

====== First Party ID turned on ======
<syntaxhighlight lang="javascript">
nSdkInstance = NOLBUNDLE.nlsQ(appID, "videoSdkInstance", {
enableFpid: "true"
});
</syntaxhighlight>

====== First Party ID turned off ======
<syntaxhighlight lang="javascript">
nSdkInstance = NOLBUNDLE.nlsQ(appID, "videoSdkInstance", {
enableFpid: "false"
});
</syntaxhighlight>

== Test your player by yourself ==
=== Guide ===
1. Run your player in the Browser, start a video 
2. Open the Developer Network View in order to monitor network traffic 
3. Filter the network traffic by "nmr" and confirm presence of SDK pings 

=== Example of SDK ping ===
<code><nowiki>https://secure-ksa.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_P&asn=defChnAsset&fp_id=&fp_cr_tm=&fp_acc_tm=&fp_emm_tm=&ve_id=&devmodel=&manuf=&sysname=&sysversion=&sessionId=zlmmxkq867zt4bpnumlyz6dpn9hyp1610980356&tl=Episode%201&prv=1&c6=vc%2Cc77&ca=us-500207_c77_VID5556674-123456&cg=TAMSample%20DK&c13=asid%2CP10DF14BA-937E-436D-99DF-ED39A0422387&c32=segA%2CNA&c33=segB%2CNA&c34=segC%2CNA&c15=apn%2C&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=0&cr=4_00_99_V1_00000&c9=devid%2C&enc=true&c1=nuid%2C999&at=view&rt=video&c16=sdkv%2Cbj.6.0.0&c27=cln%2C0&crs=&lat=&lon=&c29=plid%2C16109803568088038&c30=bldv%2C6.0.0.563&st=dcr&c7=osgrp%2C&c8=devgrp%2C&c10=plt%2C&c40=adbid%2C&c14=osver%2CNA&c26=dmap%2C1&dd=&hrd=&wkd=&c35=adrsid%2C&c36=cref1%2C&c37=cref2%2C&c11=agg%2C1&c12=apv%2C&c51=adl%2C0&c52=noad%2C0&sd=170&devtypid=&pc=NA&c53=fef%2Cy&c54=oad%2C20200713%2010%3A22%3A00&c55=cref3%2C&c57=adldf%2C2&ai=VID5556674-123456&c3=st%2Cc&c64=starttm%2C1610980392&adid=VID5556674-123456&c58=isLive%2Cfalse&c59=sesid%2Cgezrb92q4i9b9jg7acxgn783gjw0a1610980365&c61=createtm%2C1610980392&c63=pipMode%2C&c68=bndlid%2C&nodeTM=&logTM=&c73=phtype%2C&c74=dvcnm%2C&c76=adbsnid%2C&c77=adsuprt%2C2&uoo=&evdata=&c71=ottflg%2C0&c72=otttyp%2Cnone&c44=progen%2C&davty=0&si=http%3A%2F%2Fnielsenonlinesupport.com%2Fdk%2Findex.htm&c66=mediaurl%2Cassets%252FRTVOD_C3%252Fprog_index.m3u8&c62=sendTime%2C1610980392&rnd=714644</nowiki></code>

== Provide your app for certification ==
Once ready please send your web application to Nielsen local staff for certification.

== Going Live ==
After the integration has been certified (but not prior that), disable debug logging by deleting {nol_sdkDebug: "DEBUG"} from Initialization API Call.

'''Note''': before going live you have to inform Nielsen - this is necessary, because Nielsen team has to adjust internal configuration parameter to enable data collection. Without that notification no data will be collected and no data will be reported.

DCR KSA Video Android SDK

2022-07-15T23:39:04Z

ColinBrown: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}} Category:Digital __TOC__ == Overview == The Nielsen SDK is one of the mult..."

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]

== Setting up your Development Environment ==
=== Configuring Android Development Environment ===
*The Nielsen App SDK (located in the [https://engineeringportal.nielsen.com/docs/Special:Downloads Downloads section] of the website) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*The Nielsen App SDK can also be added via [https://engineeringportal.nielsen.com/docs/Digital_Measurement_Android_Artifactory_Guide Artifact Repository].

'''Nielsen App SDK is compatible with Android OS versions 2.3+. Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.'''

The requirement for the Java ''AppSdk.jar'' library and the ''libAppSdk.so'' native library will depend on the type of host application that will make use of them.
* '''For Video player applications'''
** The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
** If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

Once SDK is downloaded ensure to unzip the Nielsen SDK and copy the AppSdk.jar in your app (Android Studio) libs folder, then right click the AppSdk.jar and select '''Add As Library'''.
Ensure the AppSdk.jar file is added in 'build.grade (App Level) file.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture.

==== Google Play Services ====
Add the Google Play Services in the project,
Steps: Android Studio -> File -> Project Structure ->(In module selection) select App -> Dependencies (tab) -> Click "+" button and search for <code>"*play-services*"</code>. Then select the most recent version of the play-services Artifact.
Ensure it is added in build.gradle (App level) file

==== Google AD ID Permissions ====
The following is required if target API level is set to 31 (Android 12) with the Ad Version of the Nielsen SDK.

<syntaxhighlight lang="java">
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
</syntaxhighlight>


==== Manifest File ====
* Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html].

* In <code>AndroidManifest.xml </code>under <code><application></code> add the following metadata

<syntaxhighlight lang="java"><meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version"/></syntaxhighlight>

* App SDK checks to see if there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to missing imports and the app will not be compiled.

==== Library ====
Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

==== Classes/package ====
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || Yes || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || Yes || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
|| Nielsen-specified || Yes || "ksa"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"

|}
 

1) [[AppSDK()|AppSDK()]] is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0.2")
.put("appname", "Nielsen Sample App")
.put("sfcode", "ksa")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0.2")
.put("appname", "Nielsen Sample App")
.put("sfcode", "ksa")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# '''Idle state'''– The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || Yes
|-
|}

==== Create Content Metadata ====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>'content'</code> || Yes
|-
| assetid || unique ID assigned to asset (32 Character limit) || custom (no [[Special Characters|Special Characters]]) || Yes
|-
| program || name of program (100 character limit) || custom || Yes
|-
| title || name of program (100 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (0 for live stream) || Yes
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>'y'</code>- full episode, <code>'n'</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
*<code>'1'</code> Linear – matches TV ad load
*<code>'2'</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>'2'</code> - DCR measures content with dynamic ads
|| Yes

|}

==== Create Ad Metadata ====
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> || Yes
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters|Special Characters]]) || Yes
|}

'''Note:''' All metadata values should be passed as UTF-8 strings.

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")

JSONObject adMetadata = new JSONObject()
.put("type", "postroll")
.put("assetid", "AD-ID123");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| Resume Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

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

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Handling Foreground and Background states ==
There are a few approaches to managing the Foreground and Background states of an app available to use for state measurement.

*Utilizing the Androidx LifeCycleObserver (The recommended approach starting sdk version 7.1.0.0+)
*Utilizing the SdkBgFgDetectionUtility class
*Adding a tag to the Manifest XML
*Manual Management
=== The LifeCycleObserver ===
AndroidX replaces the original support library APIs with packages in the androidx namespace, and Android Studio 3.2 and higher provides an automated migration tool. (Select '''Refactor> Migrate to AndroidX''' from the menu bar.)

Starting with version 7.1.0, with AndroidX support, an additional utility is provided in the AppSDK - application background/foreground state detection by the AppSdk leveraging the Android Architecture component "LifeCycleObserver".

The AppSdk is now capable of detecting the application UI visibility state transitions between background and foreground, without forcing the applications to register for AppSdk's AppSdkApplication class, which is responsible for handling the detection of application background/foreground state transitions at present.

<blockquote>Please note, that if you already have an app designed that utilizes the depreciated SdkBgFgDetectionUtility Class, the AppSDK will ignore any calls to these methods if it can utilize the LifeCycleObserver. LifeCycleObserver based auto detection will take precedence.</blockquote>

==== Adding the AndroidX dependency ====
In order to make use of the app background/foreground state transition auto detection feature of AndroidX AppSdk, the app gradle file needs the androidx dependency. The AppSdk API calls - <code>appInForeground()</code> and <code>appInBackground()</code> will still be respected by AppSdk by executing the old AppSdk flow of handling "app in foreground" and "app in background" states as is.

==== Using the LifeCycle Extension ====
The following androidx dependency is required in the app gradle file:

<syntaxhighlight lang="java">implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"</syntaxhighlight>

<blockquote>If you would like to take advantage of this auto detection feature of AppSdk at the very initial stage (e.g. splash screen or at of app launch time), before the AppSdk is initialized, can do so by calling the following newly introduced AppSdk public api, passing the application context :

<syntaxhighlight lang="java">public static void registerLifeCycleObserver(Context applicationContext)</syntaxhighlight></blockquote>

==== Log messages for the new auto detection ====

*When the AppSdk app successfully registers for the LifeCycleObserver : <code>Registered LifeCycleObserver for App Background/Foreground auto-detection</code>
*When the app enters the foreground state :<code>App is in foreground, auto detected by AppSDK</code>
*When the app enters the background state :<code>App is in background, auto detected by AppSDK</code>
*If the client app doesn't have the "androidx" gradle dependency and AppSdk fails to register LifeCycleObserver :<code>AndroidX LifecycleObserver can not be observed. Please use androidx dependency to activate SDK auto-detection of app background/foreground state.</code>
*When the appInForeground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - foreground</code>
*When the appInBackground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - background</code>

=== The SdkBgFgDetectionUtility class ===
Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement. It may be implemented in multiple ways for Android. This includes

*Enable the Nielsen SDK to measure background/foreground state by makingthe relevant update to the AndroidManifest.
*Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class.
*Custom implementation of the required methods within your application.

==== ForeGround/Background Measurement via AndroidManifest ====
The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.

<syntaxhighlight lang="java"> <application android:name="com.nielsen.app.sdk.AppSdkApplication"> </syntaxhighlight>

==== Using the Android SdkBgFbDetectionUtility Class ====
For developers who are already using the application class, it is recommended that background/foreground state is implemented using the [[Android Background Foreground|SdkBgFgDetectionUtility class.]] The [[Android Background Foreground|SdkBgFgDetectionUtility class.]] is compatible with Android 4+ and has been made available to Nielsen clients. (You will need to copy/paste the code provided into a file).

==== Manual Background/ForeGround State Management ====
In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided [[Android Background Foreground|SdkBgFgDetectionUtility class.]] the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.

The SDK is informed about app state using the below methods.

<syntaxhighlight lang="java">AppLaunchMeasurementManager.appInForeground(getApplicationContext());</syntaxhighlight>
<syntaxhighlight lang="java">AppLaunchMeasurementManager.appInBackground(getApplicationContext());</syntaxhighlight>
Within the lifecycle of individual activities, onResume() and onPause() are best suited to providing indication of the app state.

Correct measurement of the foreground/background state is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Disclose Nielsen Privacy Statement ==
The App SDK uses Mobile Ad IDs (Android ID or IDFA) which are fully hashed on the device before being sent to Nielsen (Nielsen never receives un-hashed values).
Users retain the possibility to oppose the use of Mobile Ad IDs, or to reset them, by using the functionality provided by the mobile operating system (iOS or Android).

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/ .

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "nmrodam" and confirm presence of SDK pings 

=== Example of SDK ping (https call) ===
<code><nowiki>https://secure-ksa.nmrodam.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

2022-06-14T17:55:30Z

ColinBrown:

mDAR Attributes Requirements

2022-06-14T17:54:55Z

ColinBrown: ColinBrown moved page mDAR Attributes Requirements to Mobile DAR Attributes Requirements: Changed paged name to better represent content

#REDIRECT [[Mobile DAR Attributes Requirements]]

Mobile DAR Attributes Requirements

2022-06-14T17:54:55Z

ColinBrown: ColinBrown moved page mDAR Attributes Requirements to Mobile DAR Attributes Requirements: Changed paged name to better represent content

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=1&r=<timestamp> </code>

{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory parameter for mDAR?
|-
| &c7 || OS Grouping ||
|- style="background-color:#eff8ef;"
| &c8 || Device Grouping || <center>✔</center>
|-
| &c9 || Advertising ID || <center>✔</center>
|- style="background-color:#eff8ef;"
| &c10 || Platform || <center>✔</center>
|-
| &c12 || App Version ||
|- style="background-color:#eff8ef;"
| &c13 || AppID (Nielsen assigned App ID) || <center>✔</center>
|-
| &c14 || OS Version ||
|- style="background-color:#eff8ef;"
| &uoo || Opt-out indicator || <center>✔</center>
|}
<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

Template:iOS NoID Privacy and Opt-Out

2022-06-14T03:25:52Z

ColinBrown: /* Display OptOut Notice */

== Privacy and Opt-Out ==
The Irish Market build of the Nielsen SDK automatically Opt's Users out of the collection of any User Identifiable information or any Device Advertising ID.

When building your app:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Retrieve current Opt-Out preference ===
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

Template:iOS NoID Privacy and Opt-Out

2022-06-14T01:57:43Z

ColinBrown: /* Sample Code */

== Privacy and Opt-Out ==
The Irish Market build of the Nielsen SDK automatically Opt's Users out of the collection of any User Identifiable information or any Device Advertising ID.

When building your app:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Retrieve current Opt-Out preference ===
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

=== Display OptOut Notice ===
Nielsen does not use cookies in measurement in Ireland; however, you may want to present this information to your user. Sample code on how to do this is below:

==== Sample Code ====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()
// For English use: https://sites.nielsen.com/priv/browser/cookie-policy-ie-en.html
// For Gaelic use: https://sites.nielsen.com/priv/browser/cookie-policy-ie-ga.html

if let url = URL(string: "https://sites.nielsen.com/priv/browser/cookie-policy-ie-en.html") {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true

}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}}
</syntaxhighlight>

Template:iOS NoID Privacy and Opt-Out

2022-06-14T01:53:33Z

ColinBrown: /* Display OptOut Notice */

== Privacy and Opt-Out ==
The Irish Market build of the Nielsen SDK automatically Opt's Users out of the collection of any User Identifiable information or any Device Advertising ID.

When building your app:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Retrieve current Opt-Out preference ===
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

=== Display OptOut Notice ===
Nielsen does not use cookies in measurement in Ireland; however, you may want to present this information to your user. Sample code on how to do this is below:

==== Sample Code ====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let url = URL(string: "https://sites.nielsen.com/priv/browser/cookie-policy-ie-en.html") {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true

}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}}
</syntaxhighlight>

Template:iOS NoID Privacy and Opt-Out

2022-06-14T01:53:09Z

ColinBrown: /* Retrieve current Opt-Out preference */

== Privacy and Opt-Out ==
The Irish Market build of the Nielsen SDK automatically Opt's Users out of the collection of any User Identifiable information or any Device Advertising ID.

When building your app:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Retrieve current Opt-Out preference ===
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

== Display OptOut Notice ==
Nielsen does not use cookies in measurement in Ireland; however, you may want to present this information to your user. Sample code on how to do this is below:

==== Sample Code ====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let url = URL(string: "https://sites.nielsen.com/priv/browser/cookie-policy-ie-en.html") {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true

}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}}
</syntaxhighlight>

Template:iOS NoID Privacy and Opt-Out

2022-06-14T01:51:46Z

ColinBrown: /* Sample Code */

== Privacy and Opt-Out ==
The Irish Market build of the Nielsen SDK automatically Opt's Users out of the collection of any User Identifiable information or any Device Advertising ID.

When building your app:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Retrieve current Opt-Out preference ==
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

== Display OptOut Notice ==
Nielsen does not use cookies in measurement in Ireland; however, you may want to present this information to your user. Sample code on how to do this is below:

==== Sample Code ====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let url = URL(string: "https://sites.nielsen.com/priv/browser/cookie-policy-ie-en.html") {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true

}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}}
</syntaxhighlight>

Template:iOS NoID Privacy and Opt-Out

2022-06-14T01:51:23Z

ColinBrown: /* Sample Code for Global Build */

== Privacy and Opt-Out ==
The Irish Market build of the Nielsen SDK automatically Opt's Users out of the collection of any User Identifiable information or any Device Advertising ID.

When building your app:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Retrieve current Opt-Out preference ==
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

== Display OptOut Notice ==
Nielsen does not use cookies in measurement in Ireland; however, you may want to present this information to your user. Sample code on how to do this is below:

==== Sample Code ====
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let url = URL(string: "https://sites.nielsen.com/priv/browser/cookie-policy-ie-en.html") {
print ("optout url was:",url)
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true

}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}}
</syntaxhighlight>

Template:iOS NoID Privacy and Opt-Out

2022-06-14T01:50:44Z

ColinBrown: /* Sample Code for Global Build */

== Privacy and Opt-Out ==
The Irish Market build of the Nielsen SDK automatically Opt's Users out of the collection of any User Identifiable information or any Device Advertising ID.

When building your app:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Retrieve current Opt-Out preference ==
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

== Display OptOut Notice ==
Nielsen does not use cookies in measurement in Ireland; however, you may want to present this information to your user. Sample code on how to do this is below:

==== Sample Code for Global Build ====
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let url = URL(string: "https://sites.nielsen.com/priv/browser/cookie-policy-ie-en.html") {
print ("optout url was:",url)
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true

}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}}
</syntaxhighlight>

Template:iOS NoID Privacy and Opt-Out

2022-06-14T01:49:00Z

ColinBrown: /* Retrieve current Opt-Out preference */

== Privacy and Opt-Out ==
The Irish Market build of the Nielsen SDK automatically Opt's Users out of the collection of any User Identifiable information or any Device Advertising ID.

When building your app:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Retrieve current Opt-Out preference ==
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

== Display OptOut Notice ==
Nielsen does not use cookies in measurement in Ireland; however, you may want to present this information to your user. Sample code on how to do this is below:

==== Sample Code for Global Build ====
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}}
</syntaxhighlight>

===== Objective-C =====
<syntaxhighlight lang="objective-c">

#import "OptOutVC.h"
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenAppApi.h>

@interface OptOutVC ()

@property (weak, nonatomic) IBOutlet UIWebView *webView;
@end

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

- (void)viewDidLoad {
[super viewDidLoad];
//Getting the optPut URL from eventTracker
[self.webView loadRequest:[NSURLRequest requestWithURL:[NSURL
URLWithString:self.nielsenApi.optOutURL]]];
}}

</syntaxhighlight>

Digital Measurement iOS Cocoapods Guide

2022-06-13T23:05:58Z

ColinBrown: /* Podfile */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Downloads}} {{Breadcrumb|Digital Measurement iOS Artifactory Guide}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__NOTOC__
= How to install Nielsen SDK using CocoaPods =
CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It has over 30 thousand libraries and is used in over 1.9 million apps. The Nielsen SDK now uses this distribution framework for improved version management and provides a Static and Dynamic Framework.

== Initial Configuration ==
The Nielsen SDK integration requires Cocoapods.
* The XCFramework which requires Cocoapods Version 1.10.1 or higher.
* The Dynamic Framework which requires Cocoapods Version 1.6.1 or higher.
* The Static Framework requires Cocoapods version 1.4.0. or higher.

The full installation guide for this framework is provided on the [https://guides.cocoapods.org/using/getting-started.html Getting Started] page, and how to set up the Podfile is mentioned in [https://guides.cocoapods.org/using/using-cocoapods.html Using Cocoapods] page.

== Repository Credentials ==
The first step is to add the credentials received from Nielsen into your .netrc file.
<blockquote>
[[Image:AlertIcon.png|left|60px|link=|class=smallIcon]] Starting on Sept 21, 2021 the Nielsen SDK has moved to a public repository. Credentials are no longer required.
</blockquote>
 

== Verify version of Cocoapods ==
First verify that Cocoapods is installed.
<syntaxhighlight lang=Javascript>
pod --version
</syntaxhighlight>
If it is not, then install. 
===== Install via gem =====
<syntaxhighlight lang=Javascript>
sudo gem install cocoapods
</syntaxhighlight>
===== Install using homebrew =====
<syntaxhighlight lang=Javascript>
brew install cocoapods
</syntaxhighlight>
== Add Cocoapod repository ==
=== XCFramework (Cocoapods 1.10.1+) ===
If using '''XCFramework''' (preferred approach), from the command line, type the following:
<syntaxhighlight lang=Javascript>
pod repo add NielsenAppSDK https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git
</syntaxhighlight>
Make sure you run the pod init command in your **project's directory.**
<syntaxhighlight lang=Javascript>
pod init
</syntaxhighlight>
 You now need to slightly modify the PodFile that was created in this directory. From the command line, you can use vi or vim to edit. The following must be in the PodFile:
==== Podfile ====
<syntaxhighlight lang=Javascript>
platform :ios, '14.0'
source 'https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git'

target 'YourProjectsNameHere' do
use_frameworks!
#Pods for ApplicationTarget
pod 'NielsenAppSDK-XC'
end
</syntaxhighlight>

<blockquote>'''Note''': If you migrate from the iOS dynamic framework to the XCFramework, just add -XC suffix for the pod in the podfile. E.g. NielsenAppSDK should be replaced with NielsenAppSDK-XC. The same Github repo is used for both dynamic and XCFramework.</blockquote>

<blockquote>'''Note''': Nielsen AppSDK clients with applications on TVOS platform should take into account that TVOS slices are now part of the same XCFramework with iOS slices, so the XCFramework name is the same for both iOS and TVOS. But the TVOS framework imported in the application still has TVOS in its name. This is needed to reduce the number of changes in the existing apps. The code below should be added into the podfiles for TVOS XCFramework users.</blockquote>

<syntaxhighlight lang=Javascript>
# modify XCFramework configuration files to update NielsenAppApi.framework -> NielsenTVAppApi.framework
post_install do |installer|
installer.pods_project.targets.each do |target|
if target.name == 'Pods-NielsenVideoPlayerTVOSPodsXC'
# update Pods-NielsenVideoPlayerTVOSPodsXC.debug.xcconfig file
# update Pods-NielsenVideoPlayerTVOSPodsXC.release.xcconfig file
target.build_configurations.each do |config|
xcconfig_path = config.base_configuration_reference.real_path
puts "post_install: Found #{File.basename(xcconfig_path)}"
xcconfig = File.read(xcconfig_path)
new_xcconfig = xcconfig.sub('-framework "NielsenAppApi"', '-framework "NielsenTVAppApi"')
File.open(xcconfig_path, "w") { |file| file << new_xcconfig }
puts "post_install: Updated #{File.basename(xcconfig_path)} file with a value: NielsenTVAppApi.framework"
end
# update Pods-NielsenVideoPlayerTVOSPodsXC-frameworks.sh file
frameworksh_path = "Pods/Target Support Files/#{target.name}/#{target.name}-frameworks.sh"
if File.exist?(frameworksh_path)
puts "post_install: Found #{File.basename(frameworksh_path)}"
text = File.read(frameworksh_path)
new_contents = text.gsub('NielsenAppApi.framework', 'NielsenTVAppApi.framework')
File.open(frameworksh_path, "w") {|file| file.puts new_contents}
puts "post_install: Updated #{File.basename(frameworksh_path)} file with a value: NielsenTVAppApi.framework"
end
end
end
end
</syntaxhighlight>
<blockquote>If you migrate from the TVOS dynamic framework to the XCFramework, please note that TVOS slices are now part of the same XCFramework with iOS slices. So in addition to appending of the -XC suffix to the pod name in the podfile please remove TVOS. E.g. the naming for the pod NielsenTVOSAppSDK should be changed to NielsenAppSDK-XC.</blockquote>

=== Dynamic Framework (Cocoapods 1.6.1+) ===
<blockquote>'''Note''': We highly recommend to migrate to XCFramework for all our clients.</blockquote>
If using '''Dynamic Framework''', from the command line, type the following:
<syntaxhighlight lang=Javascript>
pod repo add NielsenAppSDK https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git
</syntaxhighlight>
Make sure you run the pod init command in your **project's directory.**
<syntaxhighlight lang=Javascript>
pod init
</syntaxhighlight>
 You now need to slightly modify the PodFile that was created in this directory. From the command line, you can use vi or vim to edit. The following must be in the PodFile:
==== Podfile ====
<syntaxhighlight lang=Javascript>
platform :ios, '11.0'
source 'https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs-dynamic.git'

target 'YourProjectsNameHere' do
use_frameworks!
#Pods for ApplicationTarget
pod 'NielsenAppSDK'
end
</syntaxhighlight>
<blockquote>'''Note''': If you are building an application on a Mac with Apple M1 chip, please add the following fix to end of the podfile</blockquote>

<syntaxhighlight lang=Javascript>
post_install do |installer|
installer.pods_project.build_configurations.each do |config|
config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
end
end
</syntaxhighlight>

=== For Static Framework (Cocoapods 1.4+) ===
From the command line, type the following:
<syntaxhighlight lang=Javascript>
pod repo add NielsenAppSDK https://github.com/nielsendigitalsdk/nielsenappsdk-ios-specs.git
</syntaxhighlight>
Make sure you run the pod init command in your **project's directory.**
<syntaxhighlight lang=Javascript>
pod init
</syntaxhighlight>
 You now need to slightly modify the PodFile that was created in this directory. From the command line, you can use vi or vim to edit. The following must be in the PodFile:
==== Podfile ====
<syntaxhighlight lang=Javascript>
platform :ios, '11.0'
source 'https://github.com/NielsenDigitalSDK/nielsenappsdk-ios-specs.git'

target 'YourProjectsNameHere' do
#Pods for ApplicationTarget
pod 'NielsenAppSDK'
end
</syntaxhighlight>
<blockquote>'''Note''': If you are building an application on a Mac with Apple M1 chip, please add the following fix to end of the podfile</blockquote>

<syntaxhighlight lang=Javascript>
post_install do |installer|
installer.pods_project.build_configurations.each do |config|
config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
end
end
</syntaxhighlight>

''NOTE: You can have multiple pods within the Podfile''
 
 
To select a specific version of the Nielsen SDK, just append the build number. For example, this line is requesting XCFramework build 8.1.0.0:
<syntaxhighlight lang=javascript>
pod 'NielsenAppSDK-XC','8.1.0.0'
</syntaxhighlight>
 
If using version control, a warning message will be displayed within the console trace during the build of your app,
and it will show all sdk versions released to-date, allowing a developer to select a more recent build if desired.


== Execute Install ==
Once that has been edited, you can now execute the install:
<syntaxhighlight lang=Swift>
pod install
</syntaxhighlight>
 
Cocoapods will automatically create a new file with extension “.xcworkspace”. From this moment, that file should be used for using the target project instead of previous one with extension “.xcodeproj”. Inside of this workspace you will see “Pods” target which will include ready to use NielsenAppApi framework.

Open the file with the extension of <code>.xcworkspace</code> file using Xcode.


== Pod Versions ==
The following Pod versions are now available: (For 'kids' apps, please use the NoId framework (EG: NielsenNoIdAppSDK-XC).

<blockquote>'''Note''': Nielsen SDK builds for tvOS are no longer distributed as separated packages. XCFramework allows to combine iOS and tvOS platforms in a single package. Please use the corresponding XCFramework while migrating from static or dynamic framework for tvOS. E.g. NielsenTVOSAppSDK -> NielsenAppSDK-XC.</blockquote>

{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
! App Flavor Name
|-
| NielsenAppSDK-XC
|-
| NielsenNoAdAppSDK-XC
|-
| NielsenNoIdAppSDK-XC
|}

We highly recommend to migrate to XCFramework for all our clients. For clients who still have reasons to keep using the old framework packages in the application and do not migrate to XCFramework we distribute "fat" frameworks both static and dynamic for the release 8.1.0.0. Anyway, our plan to stop distributing "fat" frameworks for future releases and to distribute the Nielsen iOS SDK as an XCFramework only.

The following Pod versions are available: (For 'kids' apps, please use the NoId framework (EG: NielsenNoIdAppSDK, NielsenNoIdTVOSAppSDK)

{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
! App Flavor Name
|-
| NielsenAppSDK
|-
| NielsenNoAdAppSDK
|-
| NielsenNoAdTVOSAppSDK
|-
| NielsenNoIdAppSDK
|-
| NielsenNoIdTVOSAppSDK
|-
| NielsenTVOSAppSDK
|}

=== Regional Builds ===
(For 'kids' apps, please use the NoId framework (EG: NielsenAGFNoIdAppSDK-XC, NielsenAGFNoIdTVOSAppSDK-XC)
{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
! App Flavor Name
|-
| NielsenAGFAppSDK-XC
|-
| NielsenAGFNoAdAppSDK-XC
|-
| NielsenAGFNoIdAppSDK-XC
|}

Fat frameworks are still available for the release 8.1.0.0.

{| class="wikitable" style="width: 30%;"
|- style="background-color:#efefef;"
! App Flavor Name
|-
| NielsenAGFAppSDK
|-
| NielsenAGFNoAdAppSDK
|-
| NielsenAGFNoAdTVOSAppSDK
|-
| NielsenAGFNoIdAppSDK
|-
| NielsenAGFNoIdTVOSAppSDK
|-
| NielsenAGFTVOSAppSDK
|}

=== Appsdk Suffix Reference ===
The Nielsen AppSDK has various configurations per market and distribution type, which can be determined by reviewing the [[Digital Measurement iOS Suffix Guide|sdk suffix]]. The first part will be the SDK version: 3 digits for the major SDK version and 1 digit for the minor SDK version. EG: <code>ai.8.1.0.0_abc</code>

=== Additional Resources ===

For more information on [https://guides.cocoapods.org/using/getting-started.html) CocoaPods] or How to set up the Profile in the [https://guides.cocoapods.org/using/using-cocoapods.html) Using Cocoapods] page.

Template:DCR Content Metadata

2022-05-18T22:36:34Z

ColinBrown:

{| class="wikitable"
|-
! '''Keys''' !! '''Description''' !! '''Values''' !! '''Required'''!!'''Provider'''
|-
| type || Type of asset ||For Video use: <code>content</code> For Static or text <code>static</code> || Yes || Nielsen
|-style="background-color:#e9f9fa;"
| assetid || Unique ID assigned to asset Note: Refrain from using the following special characters [[Special_Characters|(Special Characters)]]. || Examples: <code>BBT345a234 </code> <code>CBSs5e234F2021</code> || Yes || Client
|-
| program ||Complete program or movie title (no abbreviations or shorthand) Note: there is a 25 character limit. ||<code> The Big Bang Theory</code> <code> TheBigBangTheory</code> <code> The Dark Knight</code> <code> TheDarkKnight</code> || Yes || Client
|-style="background-color:#e9f9fa;"
| title ||Episode title with season and episode number (40 character limit) (Formats accepted: S01E03, S1E3, S1 E3). || Examples: <code>The Pants Alternative S03E18</code> <code>The Pants Alternative S3E18</code> <code>The Pants Alternative S3 E18</code> Can also accept: <code> S3E18</code> Not Valid: <code> 318 </code> or <code> 0318 </code>|| Yes || Client
|-
| crossId1 || Gracenote TMS ID (If available) should be passed for all telecasted content for clients using the Gracenote solution for proper matching purposes. Note: The TMS ID will be a 14 character string. Normally leading with 2 alpha characerts ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers.
|| The TMS ID will be a 14 character string. Normally being with 'EV,' 'EP', 'SH', 'SP', or 'MV' Followed by 12 numbers after the initial two letter prefix. The Giant Morning Show: <code>SH009311820022</code> The Pants Alternative Episode : <code>EP009311820061</code> || Optional || Nielsen
|-style="background-color:#e9f9fa;"
| crossId2 || Populated by content distributor to contribute viewing from that distributor to the given content originator. || Custom For a full list of acceptable values, please contact your Nielsen reprentative. || Yes, for distributors || Nielsen
|-
| length || Length of content in seconds Note: Integers and decimals are acceptable values are acceptable for the length parameter. || Examples:
For standard VOD content - <code>300</code> to represent 5 minutes, <code>1320</code> to represent 22 minutes, etc.
 If DAI live stream of a discrete program (Live Event/Sporting Event), pass length of content. See example for standard VOD content above.
 If unknown DAI live steam, pass a value of <code>0</code>.
|| Yes || Client
|-style="background-color:#e9f9fa;"
| airdate ||Original broadcast or release date for the program For USA, date should be EST Outside USA, date should be local time. If not applicable or available, original broadcast or release date for the Program. || Acceptable Formats: <code>YYYY-MM-DDTHH:MI:SS</code> <code>YYYY-MM-DDHH:MI:SS</code> <code>YYYY-MM-DDTHH:MI:SS+xx:xx</code> <code>YYYY-MM-DDTHH:MI:SS-xx:xx</code> <code>YYYYMMDDHH:MI:SS</code> <code>YYYYMMDD HH:MI:SS</code> <code>MM-DD-YYYY</code> <code>MM/DD/YYYY</code> <code>YYYYMMDD</code></big> || Yes || Client
|-
| isfullepisode || Full episode flag to identify differences between long form content. || <code>y</code>- full episode, <code>n</code>- non full episode(clip,teaser,promo,etc.)
Also accept:
 <code>lf</code> or <code>yes</code>- longform
 <code>sf</code> or <code>no</code>- shortform
|| Yes || Nielsen
|-style="background-color:#e9f9fa;"
| adloadtype || <big>Type of ad load:
<code>1</code> Linear – matches TV ad load <code>2</code> Dynamic – Dynamic Ad Insertion (DAI)</big>
|| <code>2</code> - DCR measures content with dynamic ads || Yes || Nielsen
|-
| segB || One of two custom segment for the clients granular reporting within a brand. || Examples: Genre - <code>horror</code>, <code>comedy</code>, etc. Timeslot - <code>primetime</code>, <code>daytime</code>, etc. News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|-style="background-color:#e9f9fa;"
| segC || One of two custom segment for the clients granular reporting within a brand. || Examples: Genre - <code>horror</code>, <code>comedy</code>, etc. Timeslot - <code>primetime</code>, <code>daytime</code>, etc. News type - <code>breakingnews</code>, <code>weather</code>, etc. || Optional || Client
|}
Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.

Examples regarding usage of segments within SDK:
* All comedy clips and stories for a Brand rolled into a "Comedy" segment
* genre grouping content by Comedy vs. Drama
* group related Text + Video content - i.e. for a show that has a lot of - static pages associated with it
* packaging based on how clients sell inventory
* grouping related types of content either by genre, category or platform.

DCR Chromecast Android SDK

2022-05-10T17:56:50Z

ColinBrown: /* 4. Receiver app (JavaScript) - Nielsen SDK implementation */

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

== 1. General Cast architecture ==
 
[[File:ScreenShot-2021-3-09-b.jpg||600px|center|]]
See https://developers.google.com/cast/docs/developers

=== Sender App ===
is a user-controlled native app that runs on a mobile device (Android, iOS) or a laptop (JS).

=== Receiver App ===
is an HTML5/JavaScript application placed at a custom URL that handles communication between the sender app and the Chromecast device.

== 2. Cast scenarios ==

=== 2.1 Pure casting scenario ===
The video is only playing on a Chromecast device. 
The sender app should not pass any Nielsen API calls once the pure casting scenario starts. All Nielsen API calls are handled by the receiver app.
[[File:Screen Shot 2018-09-25 at 09.35.08.png|600px|center]]

=== 2.2 Chromecast mirroring scenario ===
The video is playing on both the sender and receiver apps. 
Both the sender and receiver apps should pass Nielsen API calls.
[[File:Screen Shot 2018-09-25 at 09.35.19.png|600px|center]]

== 3.Sender App (Android/Java) - Nielsen SDK implementation ==

=== 3.1 General ===
By adding the below cast-specific API calls alongside the standard implementation of the Nielsen AppSDK into your native application, a sender app can pass appropriate cast-specific metadata.

=== 3.2 API call updateOTT ===
 
<syntaxhighlight lang="java">
mAppSdk.updateOTT(JSONObject ottInfo)
</syntaxhighlight>
 
Use the updateOTT method to notify the AppSDK whether the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected or disconnected (indicated by "ottStatus").

When the OTT device is connected, call updateOTT with "ottStatus": "1" as well as a set of OTT device related parameters in the ottConfig JSONObject.
<syntaxhighlight lang="java">
ottConfig = new JSONObject()
.put("ottStatus", "1")
.put("ottName", "casting”) // (casting, screen mirroring, ..)
.put("ottDevice", "chromecast")
.put("ottDeviceName", "Google ChromeCast")
.put("ottDeviceID", "xxxx-xxxx-xxxx")
.put("ottDeviceManufacturer", "Google")
.put("ottDeviceModel", "ChromeCast")
.put("ottDeviceVersion", "1.0.0");
</syntaxhighlight>

When the OTT device is disconnected, call updateOTT with "ottStatus": "0".
<syntaxhighlight lang="java">
ottConfig = new JSONObject()
.put("ottStatus", "0")
</syntaxhighlight>

Notes:
* Every time the application is launched or moves to foreground, call updateOTT to report the current OTT status.
* The application needs to report all the possible OTT types (casting, screen mirroring, and any other types) to App SDK.
* Some variables of the ottConfig object can be populated from the cast framework as seen below:
<syntaxhighlight lang="java">
String ottDeviceName = castSession.getCastDevice().getFriendlyName();
String ottDeviceId = castSession.getCastDevice().getDeviceId();
String ottDeviceModelName = castSession.getCastDevice().getModelName();
String ottDeviceVersion = castSession.getCastDevice().getDeviceVersion();
</syntaxhighlight>

=== 3.3 API call getOptOutStatus() and getDemographicId() ===
 
<syntaxhighlight lang="java">
mAppSdk.getOptOutStatus()
mAppSdk.getDemographicId()
</syntaxhighlight>
 
The sender device will need to retrieve the Opt Out status using getOptOutStatus() and the Demographic ID using getDemographicId(). These values should be sent to the Chromecast at the beginning of the casting session. Both API calls must be run in AsyncTasks to retrieve proper values. 

1. Define pre-defined static variables
<syntaxhighlight lang="java">
private static final String MEDIA_METADATA_KEY_DEVICE_ID = "kGCKMetadataNlsKeyDeviceID";
private static final String MEDIA_METADATA_KEY_OPTOUT_STATE = "kGCKMetadataNlsKeyOptout";
</syntaxhighlight>

2. Start AsyncTask to retrieve values
<syntaxhighlight lang="java">
if(mSdkDevIdAndOptoutStateFetcherThread != null && !mSdkDevIdAndOptoutStateFetcherThread.isAlive()){
mSdkDevIdAndOptoutStateFetcherThread.start();
}

private class SdkDevIdAndOptoutStateFetcherThread extends Thread
{
@Override
public void run()
{
if(mAppSdk != null)
{
// Get the demographic id and the user optout status from AppSDK
mDemographicId = mAppSdk.getDemographicId();
mSdkOptoutState = String.valueOf(mAppSdk.getOptOutStatus());
runOnUiThread(new Runnable()
{
@Override
public void run()
{
// Once the optout status is retrieved, proceed with the casting of media to remote cast device
onApplicationConnected(mCastSession);
}
});}} }
</syntaxhighlight>

3. Pass result of getOptOutStatus() and getDemographicId() to defined variable within MediaMetaData
<syntaxhighlight lang="java">
MediaMetadata mediaMetadata = new MediaMetadata( MediaMetadata.MEDIA_TYPE_MOVIE );
mediaMetadata.putString( MediaMetadata.KEY_TITLE, channelName.getText().toString());

mediaMetadata.putString( MEDIA_METADATA_KEY_DEVICE_ID, mDemographicId);
mediaMetadata.putString( MEDIA_METADATA_KEY_OPTOUT_STATE, mSdkOptoutState);

MediaInfo mediaInfo = new MediaInfo.Builder(mNowPlayingUrl)
.setContentType( getString( R.string.content_type_mp4 ) )
.setStreamType( MediaInfo.STREAM_TYPE_BUFFERED )
.setMetadata( mediaMetadata )
.build();
</syntaxhighlight>

Notes :
* To get more information about Opt Out, please refer to general AppSDK implementation guide Chapter Step 6: Privacy and Nielsen Opt-Out
* Result of getOptOutStatus() should be 0 or 1 (true or false)
* Result of getDemographicId() is an alphanumeric string (ex: a5ff494cce22bda39b29da2509f90f52e4e044587107ba9ca092eb3a1c2eccdf)

== 4. Receiver app (JavaScript) - Nielsen SDK implementation ==
Once casting starts, the receiver app becomes important as a BSDK instance must be created and the related appropriate API events must be called. Please refer to the Browser SDK guide for more information.

=== 4.1 BSDK init ===
The BSDK receiver instance gets initialized on load of the Chromecast receiver app.
<syntaxhighlight lang="java">
window.nolSDKInstance = NOLBUNDLE.nlsQ("Pxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx", "ChromeCastInstance" );
</syntaxhighlight>
Note: replace "Pxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx" with your Nielsen provided AppID.

=== 4.2 LoadMetadata===
On load of remote player, retrieve content metadata sent by the sender device and pass it using the loadMetadata API call.
<syntaxhighlight lang="java">
var metadata = {
"assetid" : senderMetadata.assetid,
"type" : senderMetadata.type,
"program" : senderMetadata.program,
"title" : senderMetadata.title,
"length" : senderMetadata.length,
"mediaUrl" : senderMetadata.mediaUrl,
"airdate" : senderMetadata.airdate,
"isfullepisode" : senderMetadata.isfullepisode,
"crossId1" : senderMetadata.crossId1,
"nol_c1" : senderMetadata.nol_c1,
"nol_c2" : senderMetadata.nol_c2,
"segB" : senderMetadata.segB,
"segC" : senderMetadata.segC,
"adloadtype" : senderMetadata.adloadtype,
"hasAds" : senderMetadata.hasAds
};
window.nolSDKInstance.ggPM('loadmetadata', metadata);
</syntaxhighlight>
Note : refer to specification of Czech MetaData and follow it


=== 4.3 Sample code ===
Below is a sample code snippet on how the receiver app should retrieve the ottMetadata received from sender apps and relay the information to receiver BSDK instance.
<syntaxhighlight lang="java">
sampleplayer.CastPlayer.prototype.onLoad_ = function(event) {

var senderMetadata = event.data.media.metadata,

sessionId =senderMetadata.kGCKMetadataNlsKeyDeviceID;

this.cancelDeferredPlay_('new media is loaded');
this.load(new cast.receiver.MediaManager.LoadInfo( (event.data), event.senderId));
var contentMetadata = {
"assetid" : senderMetadata.assetid,
"type" : senderMetadata.type,
"program" : senderMetadata.program,
"title" : senderMetadata.title,
"length" : senderMetadata.length,
"mediaUrl" : senderMetadata.mediaUrl,
"airdate" : senderMetadata.airdate,
"isfullepisode" : senderMetadata.isfullepisode,
"crossId1" : senderMetadata.crossId1,
"nol_c1" : senderMetadata.nol_c1,
"nol_c2" : senderMetadata.nol_c2,
"segB" : senderMetadata.segB,
"segC" : senderMetadata.segC,
"adloadtype" : senderMetadata.adloadtype,
"hasAds" : senderMetadata.hasAds
};

window.nolSDKInstance.ggPM('loadmetadata', contentMetadata);

var ottMetadataObject ={
ottStatus: "1",
ottType: "casting",
ottDevice: "chromecast",
ottDeviceName: "Google Chromecast",
ottDeviceID: sessionId,
ottDeviceManufacturer: "Google",
ottDeviceModel: "ChromeCastModel",
ottDeviceVersion: "1.0.0",
kGCKMetadataNlsKeyOptout : senderMetadata.kGCKMetadataNlsKeyOptout,
kGCKMetadataNlsKeyDeviceID : sessionId
};

window.nolSDKInstance.ggPM('updateOTT', ottMetadataObject);};
</syntaxhighlight>

== 5. Summary - Correct squence of API calls ==
Below is the sequence of API calls sequence from the beginning to the end of casting.

=== SENDER side : ===
1) If the video is playing only on the sender app, the standard Nielsen SDK API calls should be invoked. 
2) Once a user presses the cast icon and if the video was playing already, call '''end()'''. 
3) Inform the AppSDK about the Chromecast's status (connected or disconnected) by calling '''updateOTT(config metadata)'''. 
4) Retrieve the optOutStatus and demographicId by calling '''getOptOutStatus()''' and '''getDemographicId()'''. 
5) Pass the optOutStatus and demographicId into the MediaMetaData object. 
6) Start casting (the video should be stopped on the sender device). 

=== RECEIVER side : ===
Playback has started at ChromeCast device (TV) 
7) Retrieve the MediaMedaData sent by the sender device. 
8) Instantiate the Browser SDK. 
9) Pass metadata by calling '''loadMetaData()'''. 
10) Pass playheads every second by calling '''setPlayheadPosition()'''. 
11) Based on the user's interactions or the playlist state, call '''stop()''' (once paused) or '''end()''' (once the content or casting has ended). 

=== SENDER side : ===
Casting has ended and playback continues on the sender device 
12) Start a new session by calling '''play()''' and '''loadMetaData()'''. 
13) Continue sending API calls as usual.

== 6. Testing implementation ==
See https://developers.google.com/cast/docs/debugging 
Note: make sure that all your test devices and PC are connected to the same network. 
1. Start the Android application and play video. 
2. Connect the app to Chromecast by pressing the cast button. 
[[File:Screen Shot 2018-09-25 at 10.15.38.png|400px|center]]
3. Launch Chrome browser and access URL chrome://inspect. 
4. Under your ChromeCast device, press “inspect” 
[[File:Screen Shot 2018-09-25 at 10.15.49.png|600px|center]]
5. In your browser console, check JS activity - including Nielsen SDK. Note: make sure that the BSDK has DEBUG mode on. 
[[File:Screen Shot 2018-09-25 at 10.16.02.png|600px|center]]
6. In your Network – make sure that outgoing data to Nielsen collection is present. 
[[File:Screen Shot 2018-09-25 at 10.21.23.png|600px|center]]

Template:DCR Content Metadata

2022-05-02T20:14:48Z

ColinBrown:

{| class="wikitable"
|-
! '''Keys''' !! '''Description''' !! '''Values''' !! '''Required'''
|-
| type || type of asset ||For Video use: <code>"content"</code> For Static or text <code>"static"</code> || Yes
|-style="background-color:#e9f9fa;"
| assetid || unique ID assigned to asset Note: Refrain from using the following special characters [[Special_Characters|(Special Characters)]] || Examples: <code>BBT345a234 </code> <code>CBSs5e234F2021</code> || Yes
|-
| program ||Complete program or movie title. (no abbreviations or shorthand) Note: there is a 25 character limit. ||<code> The Big Bang Theory</code> <code> TheBigBangTheory</code> <code> The Dark Knight</code> <code> TheDarkKnight</code> || Yes
|-style="background-color:#e9f9fa;"
| title ||episode title with season and episode number (40 character limit) (Formats accepted: S01E03, S1E3, S1 E3) || Examples: <code>The Pants Alternative S03E18</code> <code>The Pants Alternative S3E18</code> <code>The Pants Alternative S3 E18</code> Can also accept: <code> S3E18</code> Not Valid: <code> 318 </code> or <code> 0318 </code>|| Yes
|-
| crossId1 || The Gracenote TMS ID (If available) || The TMS ID will be a 14 character string. Normally being with 'EV,' 'EP', 'SH', 'SP', or 'MV' Followed by 12 numbers after the initial two letter prefix. The Giant Morning Show: <code>SH009311820022</code> The Pants Alternative Episode : <code>EP009311820061</code> ||
|-style="background-color:#e9f9fa;"
| crossId2 || content originator (only required for distributors) || custom ||
|-
| length || length of content in seconds || If '''continuous''' (24 x 7) stream, pass the value of 86400. If '''live stream''' of a discrete program (Live Event/Sporting Event), pass length of content. If unknown, pass a value of 0.|| Yes
|-style="background-color:#e9f9fa;"
| airdate ||Original broadcast or release date for the program For USA, date should be EST Outside USA, date should be local time. || Acceptable Formats <code>YYYYMMDD HH24:MI:SS</code> <code>YYYYMMDDHH24MISS</code> <code>YYYY-MM-DDTHH:MI:SS</code> <code>YYYY-MM-DDHH:MI:SS</code> <code>YYYYMMDDHH:MI:SS</code> <code>MM-DD-YYYY</code> <code>YYYYMMDD HH:MI:SS</code> || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-style="background-color:#e9f9fa;"
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| segB || custom segment B || custom ||
|-style="background-color:#e9f9fa;"
| segC || custom segment C || custom ||
|}
Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.

Examples regarding usage of segments within SDK:
* All comedy clips and stories for a Brand rolled into a "Comedy" segment
* genre grouping content by Comedy vs. Drama
* group related Text + Video content - i.e. for a show that has a lot of - static pages associated with it
* packaging based on how clients sell inventory
* grouping related types of content either by genre, category or platform.

DCR Video Android SDK

2022-04-29T05:21:11Z

ColinBrown:

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

== Overview ==
The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings ([[DCR & DTVR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a sub section / page in the application.

{{Android_Prerequisites_and_Implementation_Overview}}

__TOC__

{{Android_Setting_Up_Development_Environment}}

{{Android_SDK_Initialization}}

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

== Configure Payload ==
=== Handling JSON Metadata ===
All the SDK methods handles only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of unexpected type is passed to the method, the error message will be logged.
** If string has invalid JSON format, the error message will be logged.
* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary.
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "The Big Bang Theory")
.put("title", "The Pants Alternative S03E18")
.put("crossId1", "EP009311820061") //optional
.put("crossId2", "Content Originator") //optional
.put("length", "3600")
.put("isfullepisode", "yes")
.put("airdate", "2022-03-21T10:05:00")
.put("adloadtype", "2")
.put("segB", "CustomSegmentValueB") //optional
.put("segC", "CustomSegmentValueC") //optional

</syntaxhighlight>

=== Content metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
{{DCR Content Metadata}}

=== Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>'preroll'</code>, <code>'midroll'</code>, <code>'postroll'</code> <code>'ad'</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters]]) || ✓
|}

=== Example Ad Object ===
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

== Sequence of Calls ==
=== play ===
Use [[DCR_Video_APP_SDK#play|play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
<syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>

=== loadMetadata ===
<syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

=== playheadPosition ===
<syntaxhighlight lang="java">
public void setPlayheadPosition(long position)
</syntaxhighlight>

=== stop ===
<syntaxhighlight lang="java">public void stop()</syntaxhighlight>

=== end ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
<syntaxhighlight lang="java">public void end()</syntaxhighlight>

== Configure API Calls ==

=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play];</code> || // call at start of each new stream
|-
| <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>[nielsenMeter setplayheadPosition: position];</code> || // playheadPosition is position of the playhead while the content is being played
|-
| End of Stream || <code>[nielsenMeter end];</code> || // Content playback is completed.
|}

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'play' || || Call at start of each new stream
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'setPlayheadPosition' || playhead position as integer 
VOD: || current position in seconds 
Live: current Unix timestamp (seconds since Jan-1-1970 UTC) 
Note: 'setPlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call during any interruption to content or Ad playback and at the end of each Ad.
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. 
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}
<blockquote>Note: For livestream, send the Unix timestamp; for VOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling <code>'''stop'''</code>, <code>'''end'''</code> or<code> '''loadmetadata'''</code>,.</blockquote>

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance is processing playing information. The <code>'''play'''</code> and <code>'''loadMetadata''' </code> calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## <code>'''setplayheadPosition'''</code> – Call this API every one second when playhead position timer is fired. If a LIVE event, use the current Unix timestamp (seconds since Jan-1-1970 UTC).
## <code>'''stop'''</code> – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## <code>'''end'''</code> – Call when content completes. When called, the SDK instance exits from Processing state.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>'''appDisableApi'''</code> is set to <code>true</code>

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to stop the measurement.
* As soon as the playback resumes, <code>'''loadMetadata''' </code> and <code>'''playheadPosition'''</code> </blockquote>

=== API Call Sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Advertisements ====
Call [[play()]]

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / stop / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

'''Ad Content'''
<syntaxhighlight lang="java"> long pos = mAdPlayer.videoPosition() / 1000;
if (mAppSdk != null)
{
mAppSdk.setPlayheadPosition(pos);
}</syntaxhighlight>
<blockquote>Note: The playhead positions for ad and content should be maintained separately.</blockquote>

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // stream starts
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="3" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content Resumes || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="1" | End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Handling Foreground and Background states ==
There are a few approaches to managing the Foreground and Background states of an app available to use for state measurement.
* Utilizing the Androidx LifeCycleObserver (The recommended approach starting sdk version 7.1.0.0+)
* Utilizing the [[DCR_Video_Android_SDK#The_SdkBgFgDetectionUtility_class|SdkBgFgDetectionUtility]] class
* Adding a tag to the Manifest XML
* Manual Management
=== The LifeCycleObserver ===
AndroidX replaces the original support library APIs with packages in the androidx namespace, and Android Studio 3.2 and higher provides an automated migration tool. (Select '''Refactor> Migrate to AndroidX''' from the menu bar.)

Starting with version 7.1.0, with AndroidX support, an additional utility is provided in the AppSDK - application background/foreground state detection by the AppSdk leveraging the Android Architecture component "LifeCycleObserver".

The AppSdk is now capable of detecting the application UI visibility state transitions between background and foreground, without forcing the applications to register for AppSdk's AppSdkApplication class, which is responsible for handling the detection of application background/foreground state transitions at present.

<blockquote>Please note, that if you already have an app designed that utilizes the depreciated SdkBgFgDetectionUtility Class, the AppSDK will ignore any calls to these methods if it can utilize the LifeCycleObserver. LifeCycleObserver based auto detection will take precedence. </blockquote>
==== Adding the AndroidX dependency ====
In order to make use of the app background/foreground state transition auto detection feature of AndroidX AppSdk, the app gradle file needs the androidx dependency. The AppSdk API calls - <code>appInForeground()</code> and <code>appInBackground()</code> will still be respected by AppSdk by executing the old AppSdk flow of handling "app in foreground" and "app in background" states as is.

==== Using the LifeCycle Extension ====
The following androidx dependency is required in the app gradle file:
<syntaxhighlight lang="java">
implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
</syntaxhighlight>

<blockquote>
If you would like to take advantage of this auto detection feature of AppSdk at the very initial stage (e.g. splash screen or at of app launch time), before the AppSdk is initialized, can do so by calling the following newly introduced AppSdk public api, passing the application context :
<syntaxhighlight lang="java">
public static void registerLifeCycleObserver(Context applicationContext)
</syntaxhighlight>
</blockquote>

==== Log messages for the new auto detection ====

When the AppSdk app successfully registers for the LifeCycleObserver : <code>Registered LifeCycleObserver for App Background/Foreground auto-detection</code>

* When the app enters the foreground state :<code>App is in foreground, auto detected by AppSDK</code>
* When the app enters the background state :<code>App is in background, auto detected by AppSDK</code>
* If the client app doesn't have the "androidx" gradle dependency and AppSdk fails to register LifeCycleObserver :<code>AndroidX LifecycleObserver can not be observed. Please use androidx dependency to activate SDK auto-detection of app background/foreground state.</code>
* When the appInForeground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - foreground</code>
* When the appInBackground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - background</code>

=== The SdkBgFgDetectionUtility class ===
Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement. It may be implemented in multiple ways for Android. This includes
* Enable the Nielsen SDK to measure background/foreground state by makingthe relevant update to the AndroidManifest.
* Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class.
* Custom implementation of the required methods within your application.

==== ForeGround/Background Measurement via AndroidManifest ====
The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.
<syntaxhighlight lang="java">
<application android:name="com.nielsen.app.sdk.AppSdkApplication">
</syntaxhighlight>

==== Using the Android SdkBgFbDetectionUtility Class ====
For developers who are already using the application class, it is recommended that background/foreground state is implemented using the [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class]. The [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class] is compatible with Android 4+ and has been made available to Nielsen clients. (You will need to copy/paste the code provided into a file).

==== Manual Background/ForeGround State Management ====
In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided [https://engineeringportal.nielsen.com/docs/Android_Background_Foreground SdkBgFgDetectionUtility class] the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.

The SDK is informed about app state using the below methods.
<syntaxhighlight lang="java">
AppLaunchMeasurementManager.appInForeground(getApplicationContext());
AppLaunchMeasurementManager.appInBackground(getApplicationContext());
</syntaxhighlight>
Within the lifecycle of individual activities, onResume() and onPause() are best suited to providing indication of the app state.

Correct measurement of the foreground/background state is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).
== Using the NielsenAppSDKJSHandler ==
There could be a scenario in which a browser page, that is already tagged with the Nielsen BSDK, needs to be loaded via a webview. In this situation it is recommended to use the '''NielsenAppSDKJSHandler''' which will allow communication between the AppSDK and the BSDK.
 

'''This feature is supported in versions 7.2 and above.'''
 

=== Implementation ===
* Make sure you have the latest AppSdk.jar from Nielsen
* Enable the javascript on webview using below lines
 
<syntaxhighlight lang=java>
WebSettings webSetting = webView.getSettings();
webSetting.setJavaScriptEnabled(true);
</syntaxhighlight>
 
* Add NielsenAppSDKJSHandler instance as javascript interface to webview with name “NielsenAppSDK” like below snippet
 
<syntaxhighlight lang=java>
webView.addJavascriptInterface(new NielsenAppSDKJSHandler(getApplicationContext()), "NielsenAppSDK");
</syntaxhighlight>
 
This will enable listening to BSDK api calls within the APPSDK. Please make sure your Technical Account Manager is aware that you wish to implement this method so a configuration file can be modified on the Nielsen servers; however, there are '''no changes required to the Browser page'''.

==== Example:====
The below is an example of opening a webview with the NielsenAppSDKJSHandler
<syntaxhighlight lang=java>
WebSettings webSetting = webView.getSettings();
webView.getSettings().setDomStorageEnabled(true);
webSetting.setJavaScriptEnabled(true);
webView.addJavascriptInterface(new NielsenAppSDKJSHandler(getApplicationContext(), ""), "NielsenAppSDK");
String url = "https://nielsen.com.index.htm";
webView.loadUrl(url);
</syntaxhighlight>
 
<code>AndroidManifest.xml</code> may need the following permissions set:
<syntaxhighlight lang=java>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
</syntaxhighlight>
 

=== Closing NielsenAppSDKJSHandler ===
NielsenAppSDKJSHandler should be closed or cleaned up in below scenarios
* Before WebView is getting destructed
* Before loading new page
* Before closing application
NielsenAppSDKJSHandler provides a public interface with name "close()" and this function should be called on NielsenAppSDKJSHandler's instance in all above scenarios.

<syntaxhighlight lang=java>
// get your webview
WebView webView = findViewById(R.id.webView);

//Added JS Handler instance as java script interface for ggpm api type
NielsenAppSDKJSHandler jshandler = new NielsenAppSDKJSHandler(getApplicationContext(), "");
webView.addJavascriptInterface(jshandler, "NielsenAppSDK");

//Close JS Handler before making webview as null
jshandler.close();
webView = null;
</syntaxhighlight>

== Interruptions during playback ==
As part of integrating Nielsen App SDK with the player application, the Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock
* App going in the Background/Foreground
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call [[stop]] immediately (except when content is buffering) and withhold sending playhead position.
* Start sending pings – <code>'loadMetadata'</code> and <code>'playheadPosition'</code> for the new viewing session, once the playback resumes.
Please see the [https://engineeringportal.nielsen.com/docs/Digital_Measurement_Interruption_Scenarios Interruption Scenarios Page] for more details

== Pre-Certification Checklists ==
After the application is ready to be sent for Nielsen Certification, please go through the [[Digital Pre-Certification Checklist App SDK]] and ensure the app behaves as expected, before submitting to Nielsen.

{{Template:Android_Privacy_and_Opt-Out}}
== Required Privacy Links ==
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. Include "About Nielsen Measurement" and "Your Choices" link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Sample Applications ==
The below sample applications have been designed to show the API's functionality and are broken into two distinct categories:
* '''Basic''' - To show the functionality of the Nielsen API using a standard no-frills player.
** [[Android Basic example|Android Studio Example]]

* '''Advanced''' - Nielsen API integrated into a custom video player is bundled with the SDK.

Mobile DAR Attributes Requirements

2022-04-21T05:14:55Z

ColinBrown: /* Additional DAR Tag Parameters for Mobile App Audience Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=1&r=<timestamp> </code>

{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory parameter for mDAR?
|-
| &c7 || OS Grouping ||
|- style="background-color:#eff8ef;"
| &c8 || Device Grouping || <center>✔</center>
|-
| &c9 || Advertising ID || <center>✔</center>
|- style="background-color:#eff8ef;"
| &c10 || Platform || <center>✔</center>
|-
| &c12 || App Version ||
|- style="background-color:#eff8ef;"
| &c13 || AppID (Nielsen assigned App ID) || <center>✔</center>
|-
| &c14 || OS Version ||
|- style="background-color:#eff8ef;"
| &uoo || Opt-out indicator || <center>✔</center>
|}
<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.

Mobile DAR Attributes Requirements

2022-04-21T05:14:35Z

ColinBrown: /* Additional DAR Tag Parameters for Mobile App Audience Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Digital Ad Ratings}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Introduction ==
The standard Nielsen Digital Ad Rating (DAR) tag only supports cookie based '''web browser''' viewing on PCs, MACs, and tablets/smartphone (web-browser). However, when ads are served to tablets/smartphones via native '''app-store applications''', the cookie based tag does not function correctly. Additional tag attributes are needed in order for audience reach measurement to function. Example tags are detailed later in this document.

One way Nielsen clients can accomplish this is by the use of Nielsen’s native iOS/Android App SDK. Nielsen’s App SDK automatically adds these additional tag attributes to the standard cookie based webbrowser tag before the tag is forwarded on to the Nielsen census collection system. However, there is a significant portion of the publisher mobile app universe where it is either not feasible, or desirable to integrate Nielsen’s native App SDK into 3rd party applications.

The purpose of this document is to detail the tag URL parameters required that are '''additional''' to the standard cookie based web-browser tag.

The most critical additional parameter required is the insertion of the Advertising ID (IFA / IDFA / AdID) from the users device that has been exposed to the Ad creative.

If you are reading this document as an Ad server representative then it is assumed that you have published a specification that mobile app publishers follow to pass the appropriate Advertising ID in the Ad request payload. Typically, your Ad server will then expand a macro or label with that value passed in the Ad request URL, insert into the DAR mobile app tag and redirect to Nielsen collections. See s. See [[#Appendix A: Example Implementation]], figure 2 for an example tag workflow.

The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag. If you wish to implement server-side dispatch of mobile in-app DAR tags then see additional section in this document titled '''server-side tag dispatch'''. Please read the rest of this document before reading the section on server-server.

Once you have completed your integration, you will be required to submit to a short certification. See [[#Appendix B: Implementation, Testing & Certification]]. Certification also grants inclusion to the approved publisher and certified Ad server vendor list.

'''Important Note:''' for 2018, the MRC has mandated a series of changes to audience measurement that will require additional tag events to be communicated to Nielsen so that we may compute duration weighting etc. You are strongly urged to contact your Nielsen client service representative to seek a briefing from Nielsen on the best technical methods for tagging in order to be compliant with these changes.

__TOC__

== Standard DAR Tag ==
The DAR tag is available as a 1x1 pixel. The following pixel/tag parameters must be specified for all DAR tags, 1x1, regardless of implementation type: browser, mobile browser, mobile app or connected device.

{| class="wikitable"
|-
! Tag Parameter
! Description
|-
| CI
| Client ID: the ID that is associated with the DAR account that processed tag data is associated with. Will always be hardcoded to a Nielsen generated value that comes from the Nielsen campaign management system
|- style="background-color:#eff8ef;"
| AM
| Ad Server: an ad server participating on the campaign media-plan. This is an internal Nielsen generated value when the ad server is indicated on the campaign during setup
|-
| CA
| Campaign Id: this is the ID associated with your DAR campaign. Unless you are creating and managing the Nielsen campaign via the DAR Tag API, then this parameter value will always be generated from the Nielsen campaign management system. Note: often maps to a media-plan I/O Id
|- style="background-color:#eff8ef;"
| CR
| Creative Id: DAR does not currently report at the creative level; can be hard coded ad server id or associated with a macro expansion
|-
| PC
| Placement Id: can be generated by the ad server via macro expansion or generated by the Nielsen campaign management system. Note: often maps to one of Ad Unit Id, Line Item Id or Video Ad Id
|- style="background-color:#eff8ef;"
| CE
| Site Id: the Id that identifies a publisher site that the placement needs to be mapped to. Maps into the Nielsen MarketView database. Note: can be hardcoded to a pre-registered ad server site id in the Nielsen system or a macro expansion where more than one pre-existing site ids have been made known to Nielsen
|-
| R
| Cachebuster (web): timestamp / random number. Generated by ad server
|- style="background-color:#eff8ef;"
| AT
| Fixed value: “view”
|-
| RT
| Fixed value: “banner”
|- style="background-color:#eff8ef;"
| ST
| Fixed value: “image”
|}
<blockquote> Do not URL encode the values</blockquote>

== Additional DAR Tag Parameters for Mobile App Audience Measurement ==
In this section, the additional URL parameters required beyond the standard cookie based web-browser tag are described in detail.

For each of the tag examples detailed below, we can support both non-secure (http) and secure (https) flavors. The standard cookie based web-browser tag is included below for reference purposes.

'''Important note:''' the values against each value-pair in the following tags are for illustrative purposes only. Values for CA, PC and CE will vary depending on the specific campaign being measured and capabilities of the Ad server for macro/value expansion. For more detail on the core DAR parameters, please see the '''Nielsen DAR Tag Implementation Guide.'''

'''Web Browser DAR tag (cookie based persons identification)'''
<code> //secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&r=<timestamp> </code>

'''Mobile-App DAR Tag Extension (IFA based persons identification)'''
//secure-gl.imrworldwide.com/cgi-bin/m?ci=nlsnci535&am=3&at=view&rt=banner&st=image&ca=nlsn12452&cr=crtve&pc=<creativeid>_plc0001&ce=<siteid>&c7=osgrp,IOS&c8=devgrp,PHN&c9=devid,XXXX-XX-XXXXX-XXXX &c10=plt,MBL&c12=apv,<appVersion>&c13=asid,NIELSEN-PROVIDEDID&c14=osver,7.0.4&uoo=1&r=<timestamp>

{| class="wikitable"
|-
! Additional DAR Tag Parameters for Mobile !! Description !! Mandatory parameter for mDAR?
|-
| &c7 || OS Grouping ||
|- style="background-color:#eff8ef;"
| &c8 || Device Grouping || <center>✔</center>
|-
| &c9 || Advertising ID || <center>✔</center>
|- style="background-color:#eff8ef;"
| &c10 || Platform || <center>✔</center>
|-
| &c12 || App Version ||
|- style="background-color:#eff8ef;"
| &c13 || AppID (Nielsen assigned App ID) || <center>✔</center>
|-
| &c14 || OS Version ||
|- style="background-color:#eff8ef;"
| &uoo || Opt-out indicator || <center>✔</center>
|}
<blockquote>'''Note''': Clients are encouraged to make an effort to always fill-in optional parameters.

'''Note''': Do not URL encode the values.</blockquote>

== C7 - OS Grouping (Optional) ==
Valid device OS Grouping data values are the following literal values:
* osgrp,IOS
* osgrp,DROID
* osgrp,ANDROID
<blockquote>'''Note''': If one of the above values cannot be specific, then the parameter should not be included in the call.</blockquote>

== C8 - Device Grouping (Mandatory)==
Valid literal values for phone, tablet, portable media player (iPod) and unknown are as follows:
* devgrp,PHN - Phone
* devgrp,TAB - Tablet
* devgrp,PMP - Portable Media Player (iPod)
* devgrp,UNWN - Unknown/Unclassified
* devgrp,DSK - Desktop
* devgrp,STV ← CTV/OTT Device
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* “UNWN” will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “STV” is the default value for OTT when the specific device value isn’t passed.</blockquote>

== C9 - Advertising ID (Mandatory) ==
This is the advertiser ID for the client’s mobile device. IDFA for iOS, Google Advertising ID for Android:
* devid,<IDFA>
* devid,<IFA>
* devid,<Google Advertising ID>

==== Notes ====
For Android devices, the Google Advertiser ID should be used as the default and the Android ID as the second option. 

* If C9 is <empty>, upon receiving the ping, the Nielsen collection server will attempt a 302 redirect to the data provider per the regular DAR pixel for browsers.</blockquote>
* As of August 1, 2014, Google is enforcing use of the Advertising ID for advertising and user analytics (http://play.google.com/about/developer-content-policy.html).
<blockquote>'' "Beginning August 1st 2014, all updates and new apps uploaded to the Play Store must use the advertising ID (when available on a device) in lieu of any other device identifiers for any advertising purposes."</blockquote>
* It is preferred that the IDFA or Google Advertising ID be sent as is from the mobile device (“cleartext”). However, if mandated, we will support SHA256 hashed values with no-salt. Passing a hashed value (and/or salting) using any other standard will result in a failed match by the data provider upon receiving the ping. In turn, this results in impressions surfacing in the DAR unmeasurable audience totals. Please contact Nielsen if you anticipate a large percentage of hashed values coming in from your publisher clients.

=== Privacy, Ad Tracking, and Ad Targeting ===
In newer iterations of the iOS and Android device operating systems, a facility exists allowing users to “opt-out” of “Ad Tracking”. It is Nielsen’s interpretation that this setting is primarily designed to allow users to specify opt-out of Ad Targeting rather than Ad Measurement. DAR
does not provide Ad Targeting data.

However, it is also Nielsen’s position that the publisher or Ad network should provide a mechanism to also allow a user to opt-out of Ad Measurement. The Nielsen SDK will honor the Nielsen Ad Measurement opt-out settings configurable @ http://www.nielsen.com/us/en/campaigns/privacy-policy-opt-out.html.

However if the integration approach described in this document is being used instead of the Nielsen SDK then '''YOU''' as the publisher or Ad network must provide a capability to opt-out of Ad Measurement as the configuration on www.nielsen.com will not be detectable. You may
elect to interpret the iOS / Android “Ad Tracking” setting for the purpose of limit Ad measurement or provide a separate discreet mechanism to allow a user to opt-out of Ad measurement.

Please see '''&uoo''' later in this document for implementation details of the optout indicator.

For additional clarification on privacy policy, please contact your Nielsen representative.

== C10 - Platform (Mandatory) ==
To determine this value, Nielsen suggests that the ad network leverage user agent information to determine if the client device is either a mobile or desktop device.

Valid literal values for mobile and desktop data values are as follows:
* plt,MBL
* plt,DSK
* plt,OTT
==== Notes ====
* Mandatory for accurate measurement, and if unable to pass, Nielsen cannot guarantee the impression will be classified correctly.
* Omitting c10, or a value in c10, will result in Nielsen attempting an introspection of the User Agent in the HTTP request sent against Device Atlas for classification.
* “OTT” (Connective Devices) is a valid value that is populated by participating vendors (Amazon, Hulu and Roku). Non-participating vendors will be unmeasurable volumetric metric only.

== C12 - App Version (Optional) ==
This is the version of the ad network system software or SDK that is implemented in this extension. Although this field is not required, this feature can be useful for troubleshooting purposes following deployment.
* apv,<N.N>

== C13 - AppID ==
This Nielsen provided ID is unique to the ad network and is required for certification.
* asid,<NNNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>
An App ID will be provided for testing. A separate App ID will be provided for production use. Please request from your Nielsen representative.
<blockquote>'''Note''': If you are a publisher leveraging the non-SDK solution, you will be provided with a unique App ID for each combination of app and device OS type.</blockquote>

== C14 - OS Version (Optional) ==
Operating system version
* osver,<OS Version>
Example: for iOS -> 7.0.4

== UOO - Opt Out ==
Opt-out parameter
* <Boolean state>
<Boolean state> is a Boolean representation of whether the user is opting out or not.

The absence of uoo in the tag is interpreted as an implicit opt-in. i.e. not opting out.

The following pairings of opt-out are supported. '''Important:''' you must choose one set of paired values only and inform your Nielsen representative.
{| class="wikitable"
|-
! Opt-out !! Opt-in
|-
| uoo=true || uoo=false
|-
| uoo=1 || uoo=0
|-
| uoo=yes || uoo=no
|}
<blockquote>'''Note''': if your Ad server is not capable os supporting the discrete &uoo parameter then you can set the c9 value to <code>devid,optout</code> (for example <code>…&c8=PHN&c9=devid,optout&c10=MBL…</code>)</blockquote>

== Server-Side Tag Dispatch ==
The standard way of triggering a Digital Ad Ratings (DAR) tag on Mobile-App is for the publisher app to trigger (either directly or via Ad server) the tag upon Ad exposure to the user. i.e. a client-side initiated tag.

It is important to note that MRC/IAB measurement standards stipulate that the Ad exposure event still be initiated and recorded from the client-side, even if the Ad measurement tag (in this case a DAR tag) is physically initiated from the server-side. Evidence may be required (publisher log file or similar) from the MRC/IAB that the user was exposed to the Ad creative on their device.

The following additional changes to the standard mobile-app DAR tag are required to support dispatch the DAR tag from a '''server-side''' publisher ad server:

#'''X-Forwarded-For (XFF) IP:''' The original client IP address must be passed in the X-Forwarded-For (XFF) HTTP header field. When the impression is fired directly from the Ad Server, the XReal-IP will be the Ad Server IP.
#'''Cachebuster:''' Already present in the DAR tag, this now becomes mandatory. A cachebuster or random number ensures a new call is made to the Ad Server. By including a cachebuster ('r' parameter), the tag will not be cached. The timestamp of when the Ad was served can be used.
#'''User Agent (UA):''' The HTTP UA from the client device should be used to populate the HTTP UA in the server-server connection/ping.
#'''TLS:''' the tag received by Nielsen must be TLS v1.2 compliant or greater.

==== Important notes ====
* the current iteration of server-server tag collection only supports mobile-app (IFA and AAID) and will NOT support cookie based audience measurement.
* The client’s server-server setup that is going to trigger/send the DAR tag should suppress any Nielsen cookie returned by the Nielsen collection server as a result of the first DAR tag received. If the Nielsen cookie (returned upon receiving the first DAR tag into secure.imrworldwide.com) is not suppressed then invalid traffic (IVT) filtration will quickly be triggered upon receiving the 2nd and nth tag.

== Appendix A: Example Implementation ==
In the below examples, you will see the overall DAR flow (Figure 1) and a detailed illustrative Ad Request / Response model (Figure 2).

<div align="center">'''Figure 1 – End to End Data Flow'''</div>

[[File:mDAR_Dataflow.png|center|link=]]

Nielsen certified publishers and platforms will append the new parameters (below) with the appropriate URL safe values passed to Nielsen’s current DAR tag. The current DAR tag should be acquired using the existing processes for each campaign/placement.

<blockquote><code>'''&c7'''=osgrp,IOS'''&c8'''=devgrp,PHN'''&c9'''=devid,XXXX-XX-XXXXXXXXX'''&c10'''=plt,MBL'''&c12'''=apv,AppVersion'''&c13'''=asid,XXXX-XX-XXXX-XXXX</code></blockquote>

<div align="center">'''Figure 2 – Illustrative Ad Request / Ad Response'''</div>

[[File:ad_response.png|center|link=]]

The above is an example of how an Ad server is supporting the build of mobile DAR tags for its publisher clients.
*Step 2 in Figure 1 is a summary of steps 1 and 2 in Figure 2 above.
*Steps 3 and 4 in Figure 1 is a summary of steps 3 through 9 in Figure 2 above.

== Appendix B: Implementation, Testing & Certification ==
Once you have integrated the ping per the above specs, Nielsen requires you to pass through a one-time certification before traffic can be accepted into the production environment.

The overall process is:
* Valid DAR contract or NDA is in place.
* Kick-off meeting with Nielsen onboarding team.
* Confirm meet minimums testing requirements:
** Host Ad/Tag for in-app delivery
** Can pass opt-out back to Nielsen
** Can pass Device ID in cleartext or SHA-256
* Nielsen provides the mDAR testing form that includes the test App ID and the test tag
* Identify the live campaigns for initial testing and run the test tag; suggest 5,000-10,000 impressions.
* Nielsen validates the data received from the test and confirms the initial test successful and provides the production App ID.
* Ensure contracts are in place for external test campaign with Nielsen Client Service team.
* Identify another live campaigns for production testing with production tag and app ID.
* Nielsen validates the data received from the final test and confirms certification for any DAR countries tested.
==== Goals ====
* To test in full DAR E2E environment, receive matches from data provider for demographics and correct identification of mobile impressions.
* To test that all minimum requirements in step 3 are passed to Nielsen with no issues.
* To test in a full DAR end-to-end environment, receive matches from data providers for demographics and correct identification of mobile impressions.