Class NielsenPlugin

java.lang.Object
com.castlabs.android.Plugin
com.castlabs.sdk.nielsen.NielsenPlugin

public class NielsenPlugin extends Plugin
This plugin integrates the Nielsen SDK. The plugin ensures that playback meta-data is send towards the Nielsen SDK and it allows you to access the Nielsen SDK instance.

The plugin does not bundle the Nielsen AppSdk. Your application needs to add one of its flavours from the Nielsen maven repository. The flavours share the same API and only differ in the device identifier that the Nielsen SDK collects:

  • ad: Google Advertising ID. Requires play-services-ads-identifier and play-services-base
  • noad: Android ID
  • noid: No device identifier, i.e. for kids apps
Please check with Nielsen which flavour applies to your application:
 
 repositories {
     maven { url 'https://raw.githubusercontent.com/NielsenDigitalSDK/nielsenappsdk-android/master/' }
 }
 dependencies {
     implementation 'com.nielsenappsdk.global:noad:10.2.1.0'
 }
 
 

The Nielsen SDK detects on its own when the application goes to background and comes back to foreground.

Before you can use this plugin, you have to register it with the SDK. The plugin takes the Nielsen AppSdk configuration as a JSONObject, which is passed as is to the Nielsen SDK. Only the "appid" is mandatory, the Nielsen SDK populates "appname" and "appversion" from the application resources. The "nol_devDebug" key enables the Nielsen console logging and only accepts "DEBUG", "INFO", "WARN" or "ERROR". Any other value disables the logging:

 
     JSONObject config = new JSONObject()
             .put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
             .put("nol_devDebug", "DEBUG"); // only for debug builds
     PlayerSDK.register(new NielsenPlugin(config));
     PlayerSDK.init(getApplicationContext());
 
 

Once registered, each PlayerController gets its own Nielsen AppSdk instance, created when the player opens content for the first time and closed when the player is destroyed. The plugin forwards the playback data to that instance. You can access it through the NielsenComponent of the player, i.e. to show the Nielsen opt-out page:

 
 NielsenComponent nielsenComponent = playerController.getComponent(NielsenComponent.class);
 AppSdk appSdk = nielsenComponent != null ? nielsenComponent.getAppSdk() : null;
 if (appSdk != null) {
   String optOutUrl = appSdk.userOptOutURLString();
   ...
 }
 
 
To handle the opt-out outside of playback, create your own AppSdk instance with the same configuration, as described in the Nielsen documentation.

The channel information, the content metadata and the ad metadata are passed to the Nielsen SDK as JSONObjects. Use the NielsenPlugin.MetadataBuilder to add them to the AnalyticsMetaData. The plugin fills the values that it can infer when they are not defined in those objects:

  • Channel information: "channelName" from AnalyticsMetaData.assetId, truncated to 32 characters, and "mediaURL" from the content URL. Set "mediaURL" to an empty string to not report it.
  • Content metadata: "type", "mediaURL" from the channel information, "assetid", "length" from AnalyticsMetaData.durationSeconds or the player duration ("0" for live), "islivestn" and "pbstarttm".
  • Ad metadata: "type", "assetid", "title" and "length" from the Ad, and "stationId", "subbrand", "islivestn" and "pbstarttm" from the content metadata. The values returned by AdClientInterface.Listener.onGetMetadata(com.castlabs.android.adverts.Ad) take precedence over the ad metadata JSONObject.
All the values are reported as strings, as required by the Nielsen SDK.

The playhead of live content is the broadcast time of the position in seconds since the epoch, and the final playhead is reported before the measurement stops or ends.

With a SingleControllerPlaylist, each item is measured as its own Nielsen stream with the AnalyticsMetaData of the item. Items without AnalyticsMetaData are not measured.

Since:
4.2.0
  • Constructor Details

    • NielsenPlugin

      public NielsenPlugin(@NonNull JSONObject configuration)
      Create a new instance of the plugin using the given JSON Object to configure the Nielsen SDK
      Parameters:
      configuration - The configuration that will be passed to the Nielsen SDK
  • Method Details

    • getId

      @NonNull public String getId()
      Specified by:
      getId in class Plugin
    • setEnabled

      public void setEnabled(boolean enabled)
      Dynamically enable or disable nielsen integration for playbacks
      Parameters:
      enabled - Enable or disable