View source for Android SDK API Reference

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
The Nielsen App SDK (located in the ''com.nielsen.app.sdk'' package) class is the primary application interface to the Nielsen App SDK on Android.
*Create and initialize an instance object of <code>AppSdk</code> class.
*The player application can use this object to collect HLS timed metadata through a [[sendID3()]] call.
The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package. It inherits from the closeable interface and exposes the public APIs the client’s app will use. Below is the declaration of the <code>AppSdk</code> class: <code>public class AppSdk implements Closeable</code>

== Setting Up Development Environment ==
'''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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that runs on the Android’s Dalvik Virtual Machine.
* The C/C++ libAppSdk.so native library that runs directly on the device’s hardware.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote

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.
* '''For Audio player applications'''
** The Android OS hosting the App SDK should be at version 2.3 and later since the SDK depends on the Google Play support to work properly.

=== Setting up in Eclipse IDE ===
Ensure to unzip the Nielsen App SDK sample app and copy the ''AppSdk.jar'' into the libs/ folder on the App’s Eclipse project. Copy the ''libAppSdk.so'' file under ''libs/armeabi/'' folder into the same Eclipse project.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture; the respective ''libAppSdk.so'' can be found under the ''libs/x86/'', ''libs/mips/'', and ''libs/armeabi-7a/'' folders.
Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java"><uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:required="false" />
<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].   Download the latest ''google-play-services_lib'' and include it in the App’s project in order to use the App SDK.
* 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.
To include the Google Play library in the media player project, copy the ''google-play-services_lib'' folder into the same location as the project
* Access '''File > Import'''.
* Select '''Existing Android Code into Workspace''' and click '''Next'''.
* Click '''Browse''' and navigate to the ''google-play-services_lib'' to include it into the projects.
* Select the exact '''Project Build Target''' for Eclipse to use from Android SDK.
** Android 4.4.2, etc. OR
** Edit ''project.properties'' file to point to Android target version e.g. target= android-19.

[[File:andr-properties-drm.jpg|link=]]

Once the google-play-services_lib is included into the App project, include the following code under the <code><application></code> node in the <code>AndroidManifest.xml</code>.

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

Also, include the ''version.xml'' file that comes with the ''google-play-services_lib'' under the res/values directory of the media player project.
* Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface.
Nielsen App SDK uses the following packages/classes from the Google Play service.

'''Library''':
* 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;
 
=== Setting up in Android Studio IDE ===
Launch '''Android Studio''' and select '''Import project (Eclipse ADT)'''.

[[File:andr-setup-launch.jpg|link=]]

Browse for project destination directory and click '''Next'''.

[[File:andr-import-project.jpg|link=]]

Go to '''File > Project Structure > App > Dependencies'''.

[[File:andr-pro-structure.jpg|link=]]

Click '''+''' to add library dependency.

Select '''play-services''' and click '''OK'''

[[File:andr-choose-library.jpg|link=]]

For more information, refer to https://developer.android.com/google/play-services/setup.html

== Initialization ==
=== Android Application Life Cycle with respect to Nielsen App SDK ===
[[File:andr-init-img1.jpg|link=]]

=== Step 1: App SDK initialization ===
==== For API version 4.0.0 and above ====

[[AppSDK()]] is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="objective-c">
JSONObject config = null;
 
try
{
  // Prepare AppSdk configuration object (JSONObject)
  JSONObject appSdkConfig = new JSONObject()
          .put("appid", "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
          .put("appname", "Sample App Name")
          .put("sfcode", "uat-cert")
          .put("nol_devDebug", "INFO") // only for debug builds
          .put("custom_key1", "custom_value1")
          .put("custom_key2", "custom_value2");
// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
  Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

==== Android Application Life Cycle with respect to Nielsen App SDK ====
[[File:andr-radioandvideo-app.jpg|link=]]

=== Step 2: App SDK libraries inclusion in project ===
The integration of Nielsen App SDK will depend on type of client app.
*Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on property page of the App’s project).

=== Step 3: Nielsen App SDK Streaming Sessions ===
After ensuring that the SDK object has been initialized, link the streaming session APIs. The next steps are:
*Call [[play()]] when starting or resuming a streaming session. Use the channelName parameter to pass channel descriptor information. The channel name field is a 32-character free-form text field containing the name of the program or feed being sent (such as ESPN2, Food Network, etc.) which must be inserted on a JSON string.
*Load the CMS metadata by calling the [[loadMetadata()]] on the SDK object.
*Call [[stop()]] when ending or pausing a viewing session.
*During session playback, call the SDK [[setPlayheadPosition()]] and / or [[sendID3()]]
**Call [[setPlayheadPosition()]] every one second until the stream is stopped or paused. Normally this happens on Digital Audio measurements.
**Call [[sendID3()]] if the client relies on the Nielsen ID3 tags for its measurements; this call should happen whenever a new Nielsen ID3 metadata is available for processing. Normally this happens on DTVR and ID3 measurements.
Nielsen App SDK object handles filtering of ID3 tags and CMS tags, queuing/buffering of data, and all communications with Nielsen collection facility.
*The client’s app must clearly identify the mode of operation (live vs. VOD) and stick to the type of playhead coordinates until the playback is completed. The client must reliably provide the appropriated playhead position value depending on the type of content streamed.
*If streaming live video content, the client must pass the current UTC time in seconds as playhead position.
*If streaming VOD (video on demand), the client must stream the offset from the beginning of the file as playhead position.
*For all Digital Audio listening, the client must pass the current UTC time in seconds as playhead position, regardless of station type.

== Retrieving ID3 Tags ==
ID3 tags have a payload of about 249 characters and start with "www.nielsen.com".

=== Sample ID3 tags ===
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</code>
* <code>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</code>
<blockquote>'''Note''': ID3 tags are not applicable for International (Germany)</blockquote>

=== Extracting ID3 tags from Android Players ===
==== ID3 Support Matrix ====
{| class="wikitable"
|-
! Player Name !! Minimum supported version !! Description
|-
| Android Native Media Player || Android 6 || Android 6 Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags, generates TimedMetaData.
|-
| Google ExoPlayer || Android 4.1 ||
|-
| Brightcove Player || Android 4.1 || Support for Android versions 2.3.3 and 4.0 is now deprecated. Learn more about why Brightcove is removing support for these versions as of January 1, 2016 in this [https://support.brightcove.com/en/perform/docs/announcement-brightcove-sdk-android-version-support|announcement]
|-
| Adobe PrimeTime Player || Android 4.2 ||
|-
| VisualOn Player || Android 2.3 || Android 5 is the latest supported version
|-
| NexStream Player || Android 1.6 || Supported till Android 6
|}


==== Android Native Media Player ====
As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from '''Android 6 (Android API 23)''', Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag).

<syntaxhighlight lang="java">@Override
   public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data)
     {
       byte[] iD3PayloadArray = data.getMetaData();
       String iD3Payload = new String(iD3PayloadArray, StandardCharsets.UTF_8);
       if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
         {
           int index = iD3Payload.indexOf("www.nielsen.com");
           String id3String = iD3Payload.substring(index, (index + 249));
           Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);
           appProcessID3tag(id3String);
         }
     }</syntaxhighlight>

==== ExoPlayer ====
he SDK is designed around an event-driven architecture where components emit events to allow other components to listen and respond to state changes.

'''Player SDK Classes used:'''
<syntaxhighlight lang="java">com.google.android.exoplayer.demo.player.DemoPlayer</syntaxhighlight>

Since Nielsen App SDK is interested in extracting the Timed Metadata (ID3 Tags) in HLS and VOD on the EXO Player, trace the ID3_TAG emitted during video content played using EXOPlayer component as below.

<syntaxhighlight lang="java">DemoPlayer implements ExoPlayer.Listener
—————————————————–
/**
* A listener for receiving ID3 metadata parsed from the media stream.
*/
public interface Id3MetadataListener
{
  void onId3Metadata(Map<String, Object> metadata);
}
——————————————————-
MetadataTrackRenderer.MetadataRenderer<Map<String,
Object>> getId3MetadataRenderer()
  {
    return new MetadataTrackRenderer.MetadataRenderer<Map<String, Object>>()
      {
        @Override
        public void onMetadata(Map<String, Object> metadata)
          {
            if (id3MetadataListener != null)
              {
                id3MetadataListener.onId3Metadata(metadata);
              }
          }
      };
  }</syntaxhighlight>

Also in ''Player.java'' class:
<syntaxhighlight lang="java">Player implements DemoPlayer.Id3MetadataListener
—————————————————–
@SuppressWarnings("rawtypes")
@Override
public void onId3Metadata(Map<String, Object> metadata)
{
  try
    {
      for (Object o : metadata.entrySet())
        {
          Map.Entry pairs = (Map.Entry) o;
          if (metadata.containsKey(TxxxMetadata.TYPE))
            {
              TxxxMetadata txxxMetadata = (TxxxMetadata) metadata
              .get(TxxxMetadata.TYPE);
            }
          else
            {
              String aStr = new String((byte[]) pairs.getValue());
              MainActivity.mAppSdk.sendID3(aStr);
            }
        }
    }
  catch (Exception e)
    {
      e.printStackTrace();
      Log.d(TAG, "onId3Metadata(): No Id3 tags");
    }
}</syntaxhighlight>

[[File:andr-exo-retrievingID3tags.png|link=]]

==== Brightcove Player ====
While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (<code>SeamlessVideoDisplayComponent.ID3_TAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">brightcoveVideoView.getEventEmitter().on(SeamlessVideoDisplayComponent.ID3_TAG, new EventListener()
  {
    public void processEvent(Event event)
      {
        NlsId3Tag nlsID3 = new NlsId3Tag(event.properties.get(SeamlessVideoDisplayComponent.ID3_DATA).toString());
        Log.w("ID3", nlsID3.NlsPayload);
        // Sent ID3 Tags to App
        appProcessID3tag(nlsID3.NlsPayload);
      }
      });
  }</syntaxhighlight>

==== Adobe PrimeTime Player ====
While the Adobe PrimeTime player plays the content, MediaPlayer.PlaybackEventListener triggers a callback when an ID3 packet is received (onTimedMetadata). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.
<syntaxhighlight lang="java">public void onTimedMetadata(TimedMetadata id3Metadata)
{
  NlsId3Tag nlsID3 = new NlsId3Tag(id3Metadata.getMetadata().toString());
  Log.w(LOG_TAG, "ID3 Timed Data –> " + nlsID3.NlsPayload);
  Log.w(LOG_TAG, "PayLoad Size –> " + nlsID3.NlsPayload.length());
  appProcessID3tag(nlsID3.NlsPayload);
}</syntaxhighlight>

==== VisualOn Player ====
While the VisualOn player plays the content, <code>VOCommonPlayerListener</code> triggers an event when an ID3 packet is received (<code>VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG</code>). Upon receiving this event, collect the incoming ID3 tags and only pass the Nielsen payload of the PRIV frame to the App SDK for analysis.

<syntaxhighlight lang="java">case VO_OSMP_SRC_CB_CUSTOMER_TAG:
{
  VO_OSMP_SRC_CUSTOMERTAGID tag = VO_OSMP_SRC_CUSTOMERTAGID.valueOf(nParam1);
  switch (tag)
    {
      case VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG:
      // do something with this tag
      int time = nParam2;
      byte[] b = (byte[]) obj;
      String s = new String(b);
      NlsId3Tag nlsID3 = new NlsId3Tag(b);
      // Sent ID3 Tags to App
      appProcessID3tag(nlsID3.NlsPayload);
      if (appid3If != null)
      appid3If.onId3(nlsID3.NlsPayload);
      break;
      case VO_OSMP_SRC_CUSTOMERTAGID_MAX:
      // ignore this type of tag
      break;
      default:
      break;
    }
      break;
}</syntaxhighlight>

==== NextStream Player ====
ID3 tags will be received in the NexStream Player through <code>onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata)</code> callback API. A sample implementation for the callback is shown below:
<syntaxhighlight lang="java">public void onTimedMetaRenderRender(NexPlayer mp, NexID3TagInformation m)
  {
    text = m.getPrivateFrame();
    if (text != null)
      {
        data = text.getTextData();
        if (data != null)
          {
            // make sure to identify the beginning  of  the
            // Nielsen ID3 tag payload by searching for the
            // "www.nielsen.com" string on the ID3 tag and
            // passing to the App SDK all information that
            // follows. It should be:
            // nlsPayload = "www.nielsen.com" + dataFollowing
            nlsPayload = getDataAfterWwwNielsenCom(data);
            if (nlsPayload!= NULL)
            mAppSdk.sendID3(nlsPayload);
          }
      }
  }</syntaxhighlight>

The [[sendID3()]] sends the extracted Nielsen ID3 payload to the App SDK for analysis.

== Android SDK API Methods & Properties ==
{| class="wikitable sortable"
|-
! Scenario !! Method / Property !! DTVR !! DAR !! Digital Audio !! DCR !! International (Germany) !! Description
|-
| Initialize || [[AppSDK()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to create a new instance of the SDK object
|-
| Measurement || [[play()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used when there is an ID3 fed product such as DTVR and the client does not want to send in all the CMS metadata that is sent in loadMetadata. This allows the client to send in at least the required “channel name” value associated to the ID3 feed. If this is not called then the “channel name” value populated will be the default value of “defaultChannelName”.
|-
| Measurement || [[loadMetadata()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used when there is a preroll ad that needs to be associated with content metadata. The loadmetadata will first be called to populate the content metadata values and then the loadMetadata for ad metadata will be called. This allows sending a content ping with the ad info, even if the user bails out during the preroll ad.
|-
| Measurement || [[sendID3()]] || ✔ || ✘ || ✘ || ✘ || ✘ || Used to send the ID3 metadata.
|-
| Measurement || [[setPlayheadPosition()]] || ✘ || ✘ || ✔ || ✔ || ✔ || Used to send the playhead position.
|-
| Measurement || [[stop()]] || ✔ || ✘ || ✔ || ✔ || ✔ || Used when playback is paused and when switching between ad and content or content and ad.
|-
| Measurement || [[end()]] || ✔ || ✘ || ✔ || ✔ || ✔ || Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content
|-
| Measurement || [[updateOTT()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to notify App SDK that the remote OTT device (like Google ChromeCast, Roku, Amazon FireTV, etc.) is connected / disconnected (change of OTT status).
|-
| Opt-out || [[userOptOutURLString()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to fetch the Nielsen opt-out web page URL.
|-
| Opt-out || [[userOptOut()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to supply the response message from opt-out webpage to the SDK.
|-
| Opt-out || [[getOptOutStatus()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Call this API to retrieve the Opt-Out or Opt-In state.
|-
| Opt-out
| [[appDisableApi()]]
(kill switch) 
|| ✔ || ✔ || ✔ || ✔ || ✔ || Used to disable the SDK.
|-
| Opt-out || [[getAppDisable()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query if the SDK is disabled or not.
|-
| Log || [[getLastEvent()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last status
|-
| Log || [[getLastError()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to query the SDK for the last error
|-
| Log || [[isValid()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to check if the SDK was successfully instantiated or not.
|-
| Log || [[getMeterVersion()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Returns the current SDK version.
|-
| Log || [[getNielsenId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Used to get a string defining the Nielsen ID (NUID) number for the device.
|-
| Log || [[getDeviceId()]] || ✔ || ✔ || ✔ || ✔ || ✔ || Returns the current device id.
|-
| Log || [[appInBackground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app going to background.
|-
| Log || [[appInForeground()]] || ✘ || ✘ || ✘ || ✔ || ✔ || Used to capture the event of app coming to foreground
|-
| Log || [[setDebug()]] || ✘ || ✘ || ✘ || ✘ || ✔ || Used to enable/disable debug flags. Newly introduced in SDK version 5.0.0 for International (Germany)
|}

== Android Opt-Out Implementation ==
To opt out, users must have access to "About Nielsen Measurement" page. User can click this page from app settings screen.

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.
*URL to this web page should be called from SDK by invoking [[userOptOutURLString()]] and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[getOptOutStatus()]] method.

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
   mWebView = (WebView) findViewById(R.id.webView);
   mWebView.getSettings().setJavaScriptEnabled(true);
   mWebView.getSettings().setBuiltInZoomControls(true);
   mWebView.getSettings().setDisplayZoomControls(false);
   mWebView.getSettings().setLoadWithOverviewMode(true);
   mWebView.getSettings().setUseWideViewPort(true);
   mWebView.setWebViewClient(new MonitorWebView());
   mWebView.setWebChromeClient(new WebChromeClient());
   mWebView.loadUrl(optOutUrl);
}
else
{
   //Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. 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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

=== Sequence Diagram ===
[[File:optoutsequence-andr.jpg|link=]]

== Opt-out Android SDK Version '''5.1.1.18 or above''' ==
<blockquote>'''Note:''' If using Android SDK Versions 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14, skip ahead to: [[#Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14|Opt-out Android SDK Version 1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14]]</blockquote>

Starting from SDK version 5.1.1.18, Opt-Out related behavior has been changed in the following ways:
*SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<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.</blockquote>

== Opt-out Android SDK Version '''1.2.3, 4.0.0.8, 5.1.0, 5.1.1.14''' ==
<blockquote>'''Note:''' If using Android SDK Version 5.1.1.18 or above, refer to documentation above ([[#Opt-out Android SDK Version 5.1.1.18 or above|Opt-out Android SDK Version 5.1.1.18 or above]])</blockquote>

When a user clicks the Opt-Out / Opt-In link, the application should invoke [[optOutURL]] to get the link to the Nielsen Privacy page from SDK.
=== Privacy Page ===
[[File:privacy-policy.jpg|link=]]
*There are two click here links – one for Opt-Out and one for Opt-In. Click the required link:
**Capture user’s selection
**Pass the selection back to the SDK via the [[userOptOut()]].

=== Capture and forward user selection ===
<syntaxhighlight lang="java">
private class MonitorWebView extends WebViewClient
{
  private static final String NIELSEN_URL_OPT_OUT = “nielsenappsdk://1”;
  private static final String NIELSEN_URL_OPT_IN = “nielsenappsdk://0”;
 
  @Override
  public boolean shouldOverrideUrlLoading(WebView view, String url)
  {
    if (NIELSEN_URL_OPT_OUT.equals(url)
      || NIELSEN_URL_OPT_IN.equals(url))
    {
      // Get AppSdk instance from the host
      AppSdk appSdk = HostApp.getAppSdk();
      // Send the URL to the AppSdk instance
      appSdk.userOptOut(url);
      return true;
    }
    return false;
  }
}
</syntaxhighlight>

<blockquote>'''Note:''' When 'WebView' is closed, pass the status returned from 'WebView' to the SDK within the app.</blockquote>
<blockquote>'''Note:''' App SDK manages the user's choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.


'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>
 
*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

== Nielsen Sample Applications ==

== Nielsen Privacy Requirements ==
Privacy protections that Nielsen ensures to have with each App SDK integration are as follows.
*Disclosure of viewership data collection in app store description
*Disclosure of viewership data collection in EULA / Privacy Policy
*A link in the EULA/Privacy policy, or in another conspicuous location within the App, to a Nielsen-hosted web page outlining what Nielsen is collecting and how it is being used
*Method for users to opt-out of Nielsen measurement, any time while using the application

=== Ratings Data Flow ===
Every view of creditable and watermarked content is measured by Nielsen.
[[File:RatingsDataFlow.png]]

'''Information NOT Shared'''
* '''With Nielsen'''
** User's Identity
* '''With Data Provider'''
** Content information
** Whether user is viewing an ad or video content
** Player used to play the streaming (audio / video, etc.)
** Values being de-duped / aggregating for

Nielsen collects only what it needs for audience measurement. Every view of creditable, watermarked content will be measured by Nielsen.

=== Data Collected ===
{| class="wikitable"
|-
! Type of Information !! Parameter !! Transmitted to Nielsen? !! Sent to Provider?
|-
| rowspan="8" | Nielsen ID3 Watermark
|-
| FinalDistributor Timestamp || Yes || No
|-
| Program Content Timestamp || Yes || No
|-
| Mobile Breakout Code || Yes || No
|-
| Commercial Credit Code – Linear or Dynamic || Yes || No
|-
| Time ShiftedViewing Code || Yes || No
|-
| Segment Number || Yes || No
|-
| Segment View Pattern || Yes || No
|-
| rowspan="10" | Device/App Info
|-
| Device OSVersion || Yes || Yes 
|-
| Device Model || Yes || No
|-
| Device Advertiser ID (Apple IDFA or Google AdID/Android ID) || Yes || Yes 
|-
| Cache Buster || Yes || Yes 
|-
| App Version || Yes || No
|-
| App Name || Yes || No
|-
| SDKDisabled Flag || Yes || No
|-
| ServerCode || Yes || No
|-
| Channel or URL || Yes || No
|-
| rowspan="9" | Nielsen Identifiers
|-
| Client ID || Yes || No
|-
| Campaign ID || Yes || Yes 
|-
| Nielsen Unique Device ID || Yes || No
|-
| Application ID || Yes || No
|-
| DeviceGroup (ex. Tablet, Smartphone, Desktop) || Yes || Yes 
|-
| OS Group (ex. Android, iOS, Windows) || Yes || Yes 
|-
| SDKVersion || Yes || No
|-
| IP Address for DMA, Country Code || Yes || Yes 
|}
<blockquote>'''Note''': Data is hashed, and encrypted using AES 128 before transmission to data provider.</blockquote>

==== Example ping sent to provider ====
* <code><nowiki>https://provider.com/cgi-bin/brandlift.php</nowiki>?campaign_id=ff12725d724fac7934cf6003f096b4cd<wbr />&placement_id=a4164b8fba9ee7c873a9c72c7091bb58<wbr />&creative_id=25280139b61a947e127a52f56c8a2fdd<wbr />&segment1=9000<wbr />&segment2=41<wbr />&segment3=iOS<wbr />&OSVer=iOS6.1<wbr />&c9=<wbr />&devgrp=tablet<wbr />&h=f5f243fe6d<wbr />&rnd=1376971827360</code>


This ping passes the following parameters to the provider:
* Campaign ID – (campaign, placement, creative)
* Country Code
* DMA
* OS Group (ex. iOS, Android)
* DeviceOS Version
* Device Advertiser ID
* DeviceGroup (ex. Tablet, Smartphone, Desktop)
* Cache Buster

=== Nielsen Measurement Opt-Out ===
In accordance with Nielsen’s SDK licensing agreement, developers are required to provide basic informational data to users about Nielsen’s Privacy Policy with a navigation to additional information on Nielsen measurement.

Nielsen currently uses Opt Out of Ads for Personalization for the latest versions of the SDK (5.1.1.18 and above). However, for older SDK versions, the app must provide a means for the user to opt out, or opt back in to Nielsen Measurement. Users can opt out of Nielsen online measurement research through this feature.
* If the user has this app running on more than one mobile device, the user will need to opt out of this measurement on each device.
<blockquote>'''Note''': Opt Out feature does NOT rely on "Opt Out of Ads for Personalization" setting since Nielsen’s systems provide measurement metrics and do not serve ads to users.</blockquote>

In the Description of the app in Google Play Store, include a short description about Nielsen measurement, as below.

<blockquote>'''Sample Google Play Store Disclosure'''
This app features Nielsen proprietary measurement software which will allow you to contribute to market research, like Nielsen’s TV Ratings.

To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy for more information.</blockquote>

== Event and Error Handling ==
=== App SDK Error Codes ===
Constants with predefined error codes which the AppSdk object can generate.

{| class="wikitable"
|-
! Event Code !! Event Name !! Description !! Behavior
|-
| 1001 || ERROR_FAILED_CREATE_URL_STRING || Failed generating ping string due to error on parsing || Include last error message from URL parser
|-
| 1002 || ERROR_FAILED_RECEIVE_CONFIG || Failed to receive configuration file from Census || On 5th time, it will log event and keep requesting config 10 min apart
|-
| 1003 || ERROR_FAILED_PARSING_CONFIG || Failed parsing the config file JSON string || Include json error number/short message from iOS or Android
|-
| 1004 || ERROR_FAILED_PARSING_PLAY || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1005 || ERROR_FAILED_PARSING_METADATA || Failed parsing the play() JSON string || Include JSON error number/short message from iOS or Android
|-
| 1006 || ERROR_FAILED_GENERATING_PING || Failed creating ping before adding it to the UPLOAD table) || Include ping nol_url index, cadence to identify ping
|-
| 1007 || ERROR_FAILED_PROCESSOR_START || Failed starting data processor thread. Normally, that means a product || Include processor that failed to start
|-
| 1008 || ERROR_FAILED_PROCESS_ID3 || Failed processing data on a data processor. Normally, that means the input to a product || Include processor and data that failed to process (ID3 tag on a MTVR impression, for example)
|-
| 1009 || ERROR_FAILED_HTTP_SEND || Failed sending HTTP or HTTPS requests || Include HTTP error number
|-
| 1010 || ERROR_FAILED_SENDING_PING || Failed sending pings (on ANDROID, the ping on the UPLOAD table) || Include ping up to 80 char from the end
|-
| 1011 || ERROR_FAILED_SENDING_TSV || Failed sending TSV requests || Include TSV request message
|-
| 1012 || ERROR_FAILED_SENDING_STATION_ID || Failed sending Station ID requests || Include Station ID request message
|-
| 1013 || ERROR_FAILED_ACCESSING_DB || Failed read/write from/to database table || Include SQL statement and data and SQLite error number/message
|-
| 1014 || ERROR_CHANGED_DEVICE_ID || Device ID changed
|-
| 1015 || ERROR_CHANGED_NUID || NUID changed
|-
| 1016 || ERROR_SDK_NOT_INITIALIZED || App SDK initialization failed
|-
| 1017 || ERROR_FAILED_SDK_SUSPEND || App SDK failed to suspend activities
|-
| 1018 || ERROR_INVALID_PARAMETERS || App SDK invalid parameters
|-
| 1019 || ERROR_INVALID_STATE || App SDK called in incorrect state
|-
| 1020 || ERROR_FAILED_PROCESS_PLAYHEAD || App SDK failed processing playhead position
|-
| 1021 || ERROR_FAILED_PROCESS_METADATA || App SDK failed processing not-null, syntax valid JSON metadada
|-
| 1022 || ERROR_FAILED_PROCESS_STOP || App SDK failed processing stop
|}

=== App SDK Event Codes ===
'''App SDK Event Codes '''
{| class="wikitable"
|-
! Event Code !! Event Name !! Event Description
|-
| 2000 || EVENT_INITIATE || App SDK is initiated. It will happen as soon as the App SDK is initialized
|-
| 2001 || EVENT_STARTUP || App SDK has started up. It will happen only after App SDK has received a valid config file. This is the location in the code to acquire the value of [[userOptOutURLString()]].
|-
| 2002 || EVENT_SHUTDOWN || App SDK is shutting down. It will happen just before App SDK is destroyed
|}