DCR Static Android SDK

Engineering Portal / Digital / US DCR & DTVR / DCR Static Android SDK

Prerequisites

To start using the App SDK, the following items are required:

	Item	Description	Source
☑	App ID (appid)	Unique ID assigned to the player/site and configured by product.	Contact Nielsen
☑	sfcode	Environment that the SDK must point to	Contact Nielsen
☑	Nielsen SDK	Includes SDK libraries and sample implementation; See Android SDK Release Notes	Download

If you do not have any of these pre-requisites or if you have any questions, please contact our SDK sales support team. Refer to Digital Measurement Onboarding guide for more information on how to get a Nielsen App SDK and appid.

Import Library

Refer to Android SDK API Reference - Setting Up Development Environment for information on importing libraries.

• The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.

Note: The latest version of App SDK contains only appsdk.jar file and does not feature any native shared libraries like libAppSdk.so.

Note: The integrator should always tag the landing page on the app.

Initialize SDK

Initialize App SDK as soon as the application is launched. Refer to Initalization for details on initializing an AppSDK object and the parameters required.

Configure API calls - play

For static <App Measurement> content, play API is not required.

Configure API calls - loadMetadata

Use loadMetadata to pass 'content' Digital Measurement Metadata. The CMS data must be passed as a JSON object.

    loadMetadata(JSONObject jsonMetadata);

Refer to Digital Measurement Metadata for the list of parameters to be passed in the JSON object.

Note: The loadMetadata call must have ("type": "static").

Configure API calls - playheadPosition

For static <App Measurement> content, no playhead has to be supplied to the SDK.

stop

For static <App Measurement> content, stop API is not required.

API Call sequence

Call loadMetadata with JSON metadata as below.

    new JSONObject()
        .put("type", "static")
        .put("section", "siteSection")
        .put("assetid", "vid345-67483")
        .put("segA", "segmentA")
        .put("segB", "segmentB")
        .put("segC","segmentC")
    }

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.

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.

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 - appInForeground() and appInBackground() 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:

implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"

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 :

public static void registerLifeCycleObserver(Context applicationContext)

Log messages for the new auto detection

When the AppSdk app successfully registers for the LifeCycleObserver : Registered LifeCycleObserver for App Background/Foreground auto-detection

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

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.

<application android:name="com.nielsen.app.sdk.AppSdkApplication">

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 SdkBgFgDetectionUtility class. The 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 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.

AppLaunchMeasurementManager.appInForeground(getApplicationContext());
AppLaunchMeasurementManager.appInBackground(getApplicationContext());

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

Privacy and Opt-Out

There are currently 3 flavors of the Nielsen SDK:

1. Global Android SDK Opt-out - managed by Opt out of Ads Personalization setting on device (preferred approach).
2. Global Android SDK No Ad Framework Optout - Direct call to SDK. Can be used without Google Play Services or when using the noAd version of the SDK.
3. Global Android SDK No ID Optout - Direct call to SDK. Should be used for Kids Category.

Global Android SDK Opt-out

OS-level Opt-out method available on Nielsen Android when the Google Play services APIs have been setup in your project.

The Nielsen SDK automatically leverages the Android's Opt out of Ads Personalization setting. The user is opted out of demographic measurement if the OS-level Opt out of Ads Personalization setting is enabled. As a publisher, you cannot override this setting.

Webview Element

It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL. If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

If you are implementing on Android TV or Fire TV here are your Opt Out verbiage options : https://engineeringportal.nielsen.com/docs/DCR_Video_%26_Static_CTV_Device_SDK_Privacy

Retrieve current Opt-Out preference

Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the getOptOutStatus() property in the Nielsen Android SDK API. appSdk.getOptOutStatus()

Global Android SDK No Ad Framework Optout

The No Ad Framework Optout can be used when the host application does not leverage Google Play Services such as when using the noAd version or the NoID version.

Nielsen Android SDK 5.1.1.18 and above will check for OS-level opt-out first, if available. The user will be opted out if indicated at the OS-level OR the App-level.

The No Ad Framework Optout method works as follows:

• Get the current Nielsen opt-out URL via userOptOutURLString()
• Display a WebView element whose loadUrl is set to the value obtained from userOptOutURLString()
• Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
  • Opt-out if the WebView URL = nielsenappsdk://1
  • Opt-in if the WebView URL = nielsenappsdk://0
• Pass the detected URL to the userOptOut() function
  • Example:

    appSdk.userOptOut("nielsenappsdk://1");  // User opt-out
    

Global Android SDK No ID Optout (Kids_Category)

If you are building an app that will be listed in the Kids Category:

1. Ensure that you are using the NoID version of the Nielsen SDK Framework.
2. Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:

appSdk.userOptOut("nielsenappsdk://1");  // User opt-out

OptOut Example Code

Below you will find some sample code for the:

• Global Android SDK - managed by Opt out of Ads Personalization setting on device (preferred approach).
• Global Android noAd Framework - Use if Google Play APIs are unavailable or running noAd version.
• It is currently not required to display an OptOut page for the NoID/Kids Build of the SDK.

Global OptOut Example

The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build

public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

    WebView webView;
    AppSdk appSdk;

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_optout);
        webView = (WebView) findViewById(R.id.webView);
        webView.getSettings().setJavaScriptEnabled(true);

        webView.setWebViewClient(new WebViewClient() {
            @SuppressWarnings("deprecation")
            @Override
            public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
                Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
            }
            @TargetApi(android.os.Build.VERSION_CODES.M)
            @Override
            public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
                // Redirect to deprecated method, so you can use it in all SDK versions
                onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
            }

        });
        String url = appSdk.userOptOutURLString();   // Request Optout URL from NielsenSDK
        webView.loadUrl(url);                         //Display to the user in a Webview
    }
    @Override
    public void onBackPressed() {
        super.onBackPressed();
        mSdkInterface.getSDK(appSdk);
    }
    @Override
    protected void onDestroy() {
        super.onDestroy();
        if (appSdk != null)
        {
            appSdk.close();
            appSdk = null;
        }
    }
}

No Ad Framework Optout Sample Code

The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.

public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

    WebView webView;
    AppSdk appSdk;

    @Override
    public void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_optout);
        webView = (WebView) findViewById(R.id.webView);
        webView.getSettings().setJavaScriptEnabled(true);

        webView.setWebViewClient(new WebViewClient() {
            @SuppressWarnings("deprecation")
            @Override
            public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
                Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
            }
            @TargetApi(android.os.Build.VERSION_CODES.M)
            @Override
            public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
                // Redirect to deprecated method, so you can use it in all SDK versions
                onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
            }

  
            @Override
            public boolean shouldOverrideUrlLoading(WebView view, String url) {

                if(url.contains("nielsen")){
                    // If url value = "nielsenappsdk://1 it means the user selected Opt Out
                    // If url value = "nielsenappsdk://0" it means the user selected Opt-In
                    appSdk.userOptOut(url);
                }
                return true;
            }

        });
        String url = appSdk.userOptOutURLString();   // Request Optout URL from NielsenSDK
        webView.loadUrl(url);                         //Display to the user in a Webview
    }
    @Override
    public void onBackPressed() {
        super.onBackPressed();
        mSdkInterface.getSDK(appSdk);
    }
    @Override
    protected void onDestroy() {
        super.onDestroy();
        if (appSdk != null)
        {
            appSdk.close();
            appSdk = null;
        }
    }
}

Retrieve current Opt-Out preference

Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the getOptOutStatus() property in the Nielsen Android SDK API. appSdk.getOptOutStatus()

Going Live

Following Nielsen testing, you will need to:

1. Disable Debug Logging: Disable logging by deleting {nol_devDebug: 'DEBUG'} from initialization call.
2. 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.

Pre-Certification Checklists

After the application is ready to be sent for Nielsen Certification, please go through the Pre-Certification Checklist and ensure the app behaves as expected, before submitting to Nielsen.

Testing an Implementation - App

See Digital Measurement Testing.