Android SDK API Reference

Engineering Portal / Digital / Android SDK API Reference
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 AppSdk 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 AppSdk class: public class AppSdk implements Closeable

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.

Note: App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.

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.

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

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

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).

Browse for project destination directory and click Next.

Go to File > Project Structure > App > Dependencies.

Click + to add library dependency.

Select play-services and click OK

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

Engineering Portal / Digital / DCR & DTVR / Android SDK API Reference

Initialization

Android Application Life Cycle with respect to Nielsen App SDK

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

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);
}

Here, appContext is the App context object and appSdkConfig is JSON object for holding the parameters (appid, appname, sfcode) 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

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

• www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00
• www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00

Note: ID3 tags are not applicable for International (Germany)

Extracting ID3 tags from Android Players

ID3 Support Matrix

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	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).

@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);
         }
     }

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:

com.google.android.exoplayer.demo.player.DemoPlayer

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.

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);
              }
          }
      };
  }

Also in Player.java class:

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");
    }
}

Brightcove Player

While the Brightcove player plays the content, EventListener triggers an event when an ID3 packet is received (SeamlessVideoDisplayComponent.ID3_TAG). 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.

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);
      }
      });
  }

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.

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);
}

VisualOn Player

While the VisualOn player plays the content, VOCommonPlayerListener triggers an event when an ID3 packet is received (VO_OSMP_SRC_CUSTOMERTAGID_TIMEDTAG). 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.

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;
}

NextStream Player

ID3 tags will be received in the NexStream Player through onTimedMetaRenderRender(NexPlayer mp,NexID3TagInformation metadata) callback API. A sample implementation for the callback is shown below:

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);
          }
      }
  }

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

Android SDK API Methods & Properties

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)

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

Event and Error Handling

App SDK Error Codes

Constants with predefined error codes which the AppSdk object can generate.

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

App SDK Event Codes

public static final int EVENT_INITIATE = 2000;
// App SDK is initiated. It will happen as soon as the App SDK is initialized
public static final int EVENT_STARTUP = 2001;
// 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().
public static final int EVENT_SHUTDOWN = 2002;
// App SDK is shutting down. It will happen just before App SDK is destroyed

App SDK Event Codes

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
2002	EVENT_SHUTDOWN	App SDK is shutting down. It will happen just before App SDK is destroyed