Digital Audio Android SDK

From Engineering Client Portal

Revision as of 19:42, 30 November 2018 by Admin (talk | contribs) (Unix timestamp, fix setplayheadposition() link)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png Digital Audio breadcrumbArrow.png Digital Audio Android SDK

Requirements

Below are the requirements and steps to use the Nielsen App SDK for Digital Audio Measurement.

  1. Complete Prerequisites
  2. Register stations and metadata
  3. Call SDK APIs in your app
  4. Install Nielsen Privacy Requirements
  5. Complete a Production License
  6. Obtain Nielsen Certification (app testing)
  7. Deploy your app: using production app identifiers


OS Versions Supported

The minimum Android version supported by the Nielsen App SDK is 2.3+. If the Nielsen App SDK is initialized on devices with earlier versions, the app may not compile or the initialization call could fail.

Prerequisites

To obtain and begin coding with the Nielsen App SDK, you need the following

  • Data Evaluation License: a license to evaluate the SDK library. This form can be accessed here and only needs to be completed one time. You will be forwarded directly to downloads if the form was completed in the past.
  • Nielsen App SDK bundle: a downloadable package that includes the SDK library and sample apps. Please complete the Data Evaluation License to obtain access to the download the Nielsen App SDK.
  • Application ID: Unique ID assigned to your mobile app or player by Nielsen to track your app. Your app will pass this ID to the SDK API during startup

If you do not have any of these prerequisites, please contact your Nielsen Technical Account Manager (TAM) or your Nielsen account Representative.

Register Stations and Metadata

Submit a list of your applications and station identifiers to your TAM so that he or she can check that the identifiers are registered with the Nielsen database and in the correct format for your stations receive complete credit.

SDK API Sequence Flow

Below are the appropriate API calls for each user stage of your mobile audio application. Please note that pause and stop are synonymous for this application.

App Stages.png

Importing the Library

You will need to add the Nielsen App SDK library to your project. Refer to Android SDK API Reference - Importing Frameworks for information on importing the library.

Initializing the SDK

Initialize the Nielsen App SDK as soon as the application is launched within the viewDidLoad view controller delegate method using initWithAppInfo:delegate.

Number of Instances

The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously.

  • The SDK supports a maximum of four SDK instances per appid.
  • When four SDK instances exist, you must destroy an old instance before creating a new one; otherwise, when a fifth SDK instance is launched, the SDK will return “nil” from new AppSdk()
  • The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1.
If the App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.

Refer to Android SDK API Reference - Initialization for more details on initializing an AppSDK object and the parameters required. Please note that the above link includes all products and Digital Audio does not use ID3 tags or the notifications required for ID3 tag usage.

Definition

    public AppSdk(Context context, JSONObject appInfo, IAppNotifier notifier);

Parameters

Initialize a Nielsen App SDK object with AppSdk. The complete list of arguments that can be passed via the AppInfo JSON schema for the API are as follows.

# Parameter Description Values Example
1 appid Unique id assigned to the application by Nielsen String starts with either P or T PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Use Test appid during development, test, and certification processes Use Production appid to submit app to App / Play store, after receiving Nielsen certification.

2 appversion Current version of the application Client defined 7.3.1.8
3 sfcode Nielsen environment that communicates with the SDK "drm" for prod, "uat-cert" for testing drm
N/A appname As of SDK version 6.0.0, appname is no longer a required parameter during initialization. Client defined "Nielsen Sample Application"

Return Values

The application should check for valid return values after initialization. For NielsenAppApi object of type id, a NIL object is returned if the initialization failed.

Examples

Production

        JSONObject sdkConfig = new JSONObject();
        sdkConfig.put("appName", "Radio Player App");
        sdkConfig.put("appVersion", "7.4.1.15");
        sdkConfig.put("sfcode", "drm");
        sdkConfig.put("appId",  PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX); 

        mAppSdk = new AppSdk(context, sdkConfig, this);
        if (!mAppSdk.isValid()) {
            Log.line(TAG, "Nielsen App SDK object was not created");
        }

Notice there is no debug flag provided in production.


Testing and Debugging

Developers can use the SDK's debug flag for testing. To activate debug mode, pass the argument @”nol_devDebug”:@”INFO” in the JSON string for initWithAppInfo:delegate, as below.

        JSONObject sdkConfig = new JSONObject();
        sdkConfig.put("appName", "Radio Player App");
        sdkConfig.put("appVersion", "7.4.1.15");
        sdkConfig.put("sfcode", "uat-cert");
        sdkConfig.put("nol_devDebug", "INFO");
        sdkConfig.put("appId",  TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX); 

        mAppSdk = new AppSdk(context, sdkConfig, this);

The permitted values are

  • INFO: Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as an aide for certification.
  • WARNING: Indicates potential integration / configuration errors or SDK issues.
  • ERROR: Indicates important integration errors or non-recoverable SDK issues.
  • DEBUG: Debug logs, used by the developers to debug more complex issues.

Please take care to deactivate the debug flag before deploying your application to production.

Measurement API calls

play

Use play to tell the SDK that the user has started a listening event. Both channelName and mediaURL are optional for Digital Audio Measurement.

The channel name field is a 32-character field containing the name of the program or feed such as “The Dove-Tampa”, “Hot 107.9”, or “The Morning Zoo”. mediaURL is the URL for the content (media) that is being played.

loadMetadata

Use loadMetadata to pass content identification to the SDK Digital Audio Metadata.

Definition

    loadMetadata(JSONObject jsonMetadata);

The parameters must be passed as a JSON object.

Example

Please see below for an example the JSON parameters.

    {
      "dataSrc": "cms",
      "type": "radio",
      "assetid": "WXYZ-FM",
      "stationType": "1",
      "provider": "My Radio Provider"
    };

setPlayheadPosition

Call setPlayheadPosition() every two seconds until the stream is stopped. The "Sample API Sequence" diagram can be used for reference when identifying the specific events that need to be called during content playback without ads.

public void setPlayheadPosition(long position)


# Key Parameter Required? (Y/N) Example
1 Playhead Position Unix timestamp (seconds since Jan-1-1970 UTC) Yes 1503088575
Please Note: setPlayheadPosition must be called consistently every two seconds or the duration of listening will not credit correctly.

Handling Buffering State

If the content is in a buffering state or experiences connectivity loss that affects the audio for 30 seconds or more, call the stop API.

Sample Parameter Calculation

    
     Calendar c = Calendar.getInstance();
     long secondsUNIX = (c.getTimeInMillis()/ 1000);    // current time as seconds since Jan-1-1970 UTC
     if (mAppSdk != null)
     {
        mAppSdk.setPlayheadPosition(secondsUNIX);  // pass number of seconds
      }

stop

Calling stop helps prevent loss of credit by sending all cached measurement. The SDK only caches a limited amount of measurement when the device has no HTTP connectivity. The SDK will send cached measurement when the app regains connectivity after short periods of network loss. Call stop whenever the stream stops and before the app exits, whenever possible. stop should also be called for interruptions during playback like Airplane Mode, Wi-Fi toggle, and for:

  • Station changes, stops, and pauses
  • App enters buffering state during poor connectivity for 30 seconds or more
  • If streaming stops when headphones are unplugged
  • Alarms or calendar notifications that stop the stream
  • Receiving a phone call, making a phone call
  • Airplane mode or wi-fi enable or disablement


Sample API Sequence

User Action Sample Code Description
Start of stream mAppSdk.play(channelName); // channelName contains a description of the stream in JSON format
mAppSdk.loadMetadata(contentMetaDataObject); // contentMetadataObject contains identification of the stream formatted to Nielsen specifications in JSON format
Streaming mAppSdk.setPlayheadPosition(playheadPosition); // playheadPosition passes the position of the playhead every two seconds while the content is being played
End of Stream mAppSdk.stop(); // Content playback is completed, paused, or stopped

Interruptions during playback Your audio app needs to call stop in the following interruption scenarios:

  • When the user pauses or stops play
  • Phone call interrupt that stops the stream
  • Network loss that causes the stream and audio to stop. When the app utilizes cached media to continue playing, call stop after 30 seconds of audio loss
  • Alarm Interrupt when streaming is stopped. Does not apply to audio ducking or lowered volume
  • Station changes
  • Unplugging of headphone that stops streaming

In case of encountering one of the above interruptions, the player application needs to

Nielsen Privacy Requirements

As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to personally identify the consumer in any way, but they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior. Below is a summary of the privacy requirements. You can obtain the detailed instructions here: Android SDK API Reference - Android Opt-Out Implementation

  • In your Play Store description, disclose that Nielsen collects listening data.
  • Include a link labeled "About Nielsen Measurement and Your Choices" in your Privacy Policy or EULA or as a button in a menu in your app.
  • When the user wants to opt in or opt out of measurement, present a page with Nielsen privacy text and/or choices to the user. The URL for this page must be obtained from the optOutURL) property.
  • The privacy page should be displayed in a webview within the app and not in any external browser.
  • Capture the user’s selection in the webview and pass it to the SDK through userOptOut.
  • Your app should perform the same process as above for Limit Ad Tracking features. In operating systems with Limit Ad Tracking or with opt out features, the Nielsen App SDK will detect the OS settings and opt the user out accordingly. The SDK will ignore the parameters when Limit Ad Tracking is in affect.

For more details, refer to Anroid SDK API Reference - Android Opt-Out Implementation and Nielsen Digital Privacy.

Obtaining Nielsen Certification

IMPORTANT: You must obtain Nielsen certification before releasing your application for usage.

We want to ensure that your stations receive complete credit for listening. Before you deploy Nielsen will test that your app calls the SDK APIs correctly and provides correct station metadata. You can submit your app to Nielsen via TestFlight or other test distribution method. Please allow several days for this testing to complete. Test times vary per app; so, please contact your TAM for a test completion schedule.

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.