Digital Audio Browser SDK (4.0)

From Engineering Client Portal

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png Digital Audio breadcrumbArrow.png Digital Audio Browser SDK (4.0)

Requirements

Below are the steps to integrate the Nielsen Browser SDK for Digital Audio Measurement.

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

Prerequisites

To access the Nielsen Browser SDK and begin coding, you need the following

  • Complete the Data Evaluation License: a license to evaluate the SDK library. This form can be obtained from your Nielsen Account Representative and only needs to be completed one time.
  • Obtain Your Application ID: Unique ID assigned to your player by Nielsen to track your player. Your player will pass this ID to the SDK API during startup. The application ID can be obtained from your Technical Account Manager.

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

Please note there is no browser SDK bundle. If you need a sample js player, please contact your Nielsen Technical Account Manager (TAM). ggjw370.js is included as part of the Browser SDK files in the JW Player (Sample Code/JW Player).


Register Stations and Metadata

Submit a list of your players 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

Once you have an application ID, you can begin making the API calls in your player. Below are the appropriate API calls for each user stage of your mobile audio player. Please note that pause and stop are synonymous for this application.

Browser Stages2.png

Important

Failing to call stop after an interruption in audio will prevent full credit from being sent to Nielsen for the station.

Type Sample code Description
Start of stream nSdkInstance.ggPM(loadMetadata, contentMetadataObject); // metadataObject contains the metadata object for the player instance
Content nSdkInstance.ggPM(setPlayheadPosition, playheadPosition); // playheadPosition is the live Unix timestamp (seconds since Jan-1-1970 UTC) while the content is being played
Stream stops or pauses nSdkInstance.ggPM(stop, playheadPosition);

Importing the SDK Library

In the HTML head section of each page, call the Nielsen library using the script tag, as shown below.

   <script type="javascript" src="http://secure-cert.imrworldwide.com/novms/js/2/ggcmb400.js"></script>

For Flash implementations use “ggCom.as”.

Defining Global Parameters

  <script type="javascript">
   var _nolggGlobalParams =
     {
       sfcode: "cert",
       apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
       apn: "test-setup"
     };
</script>

Initializing the SDK

Initialize Browser SDK as soon as the Parent / Main Page is loaded. During the initialization, custom parameters can be appended to the global parameter object. These custom (extended) parameters are optional. Use them only if the player application can handle the custom parameter data.

The Nielsen Browser SDK supports multiple processing instances. To create an instance, call the getInstance() function

    var nSdkInstance=NOLCMB.getInstance(instanceName);

All subsequent calls to getInstance with the same instanceName will return an already created SDK instance with that name. This will allow accessing the same object from different parts of the code.

The "instanceName" parameter is optional and will be set to "default" if missing. To use a single default SDK instance, call

    var nSdkInstance=NOLCMB.getInstance();

To instantiate Nielsen Browser SDK for Flash integration, add the following line within the player setup.

    ggCom.getInstance(RootReference.stage.loaderInfo);

In order to initialize the SDK, parameters must be passed when calling the initialization function (ggInitialize). The available parameters are listed in the table below.

Parameters Description Value Required? (Y/N)
apid UniqueID assigned to player/site. There are two IDs provided for
  1. Test: begins with ‘T’ and is used for testing, and
  2. Production: begins with ‘P’ and is used when testing is completed in live environment.
Nielsen assigned Yes
apn User-defined string value for describing the player/site Client-specified Yes
sfcode Location of collection environment. During testing, all traffic should be directed to cert. "cert" – testing. "drm" – production Yes
nol_sdkDebug Do not include on production version of player. Use "INFO" or "DEBUG" for testing. No

Example

    var gg = window.NOLCMB.getInstance(instanceName /*optional*/);
    gg.ggInitialize(window._nolggGlobalParams);


To test your changes: To enable SDK logging, pass “INFO” or “DEBUG” to the nol_sdkDebug in your global parameters. Do not use the debugging feature in the production version of your app. To turn debugging off, do not pass the nol_sdkDebug parameter.

Configure and fire API calls

The syntax for firing events is

    nSdkInstance.ggPM("event", metadataObject);

CMS data to be sent as an object in the format mentioned above. Event is passed in parameter 1 and the metadataObject is passed in parameter 2.

loadMetadata

Use loadMetadata (Browser) to pass the radio station identification Digital Audio Metadata.

Example

    nSdkInstance.ggPM('loadMetadata', metadataObject);
Note: Digital Audio measurement is for live streaming Am / FM stations. For Digital Audio, provide the parameters shown in the table below.
Parameter name Description Value
dataSrc Source of the data. For Digital Audio, pass dataSrc as "cms" "cms"
type Type of content. For Digital Audio, set type as "radio" "radio"
assetid Station identifier, should include call letters and band (no Special Characters) "WXYZ-FM"
stationType OTA station flag and/or OTA station type

1: OTA streaming station with the same ad load 2:OTA station with a different ad load

"1" or "2"
provider Name of provider "XYZ Provider"

Sample Metadata Object

    var metadataObject =
    {
      dataSrc: "cms",
      type: "radio",
      assetid: "WXYZ-FM",
      stationType: "1",
      provider: "StationOwnerName"
    }

setPlayheadPosition

Call the setPlayheadPosition (Browser) API every 2 seconds consistently while the content is being played so the SDK increments listening duration.

# Key Description Value Required? (Y/N) Example
1 PlayheadPosition Unix timestamp (seconds since Jan-1-1970 UTC) of the live content Seconds elapsed since 1970 Yes 1506544964


Buffering state

  • If the content is in buffering state continuously for more than 30 seconds and the audio has stopped, call stop.

Example

    nSdkInstance.ggPM('setPlayheadPosition', Math.floor(Date.now()/1000));

stop

This API signals to the SDK that the audio has stopped. Call this stop API anytime the station audio stops or pauses, including interruptions in playback like those listed below.

Please Note

Calling stop is very important because it 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.

Also call stop for these interruptions:

  • 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

Example

    nSdkInstance.ggPM('stop', playheadPosition);

Nielsen Measurement Opt-Out Implementation

The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy.

  • A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
  • A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement.

The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Opt Back In

Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

Testing and Debugging

Before submitting your application to Nielsen for certification, you will want to completely test your app.

Tools Required

You will need an HTTP traffic monitoring tool to use this section. Example HTTP traffic-monitoring tools are Charles or Fiddler .

Steps

Step 1. Turn on Debug

This is optional for more information during testing. Turn debug on in your player:

Browsers

  <script type="javascript">
   var _nolggGlobalParams =
     {
       sfcode: "cert",
       apid: "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
       apn: "No change",
       nol_sdkdebug: "console"
     };
  </script>

Step 2: Filter traffic

Filter HTTP traffic with the string "imr" to capture traffic from the SDK as shown in the below figure. This will capture traffic going to Nielsen servers. Now set up the device to proxy to this traffic analyzer.

Note: Instructions may vary from device to device.

fiddler-web-debugger.png

Step 3: Check Opt-Out

If the opt-out function was previously tested, the device will not produce test data. Complete an opt-in on the device and terminate the app completely before restarting.

Step 4. Check Initialization

The first HTTP traffic from the SDK will be the request for configuration information when the player instantiates the SDK. Here is an example. https://secure-drm.imrworldwide.com/cgi-bin/cfg?pli=15138756139246933&sdkv=bj.4.0.0&fmt=jsonp&apn=RadioSample&fbtag=true&cfgv=150&bldv=1.2.19&prefprotocol=https&apid=PF9999999-0E5D-B89A-A456-070AA9999999&sfcode=drm&apv=3.2.1&rnd=700000

Step 5. Check Measurement

Check that the following pings and metadata are present and correct during your testing of your stream functions.

Ping Type Description
Impression Nielsen Impression Ping is sent when the user hits play
View Nielsen V ping is sent 30 seconds after session start </br>
Quarter Hour A minimum of 4 minutes and 30 seconds of listening is needed to qualify for a quarter hour
Duration Nielsen Duration ping is sent every 5 minutes of the hour and at the end of listening. Listeners qualify for each minute. Each D ping maps the listening for a 5 minute segment. For example, 11111 = all five minutes qualified,

11110 = 4 minutes qualified in the final Duration ping of the above session, 10001 = first and last minutes qualified

Example Impression Ping https://secure-drm.imrworldwide.com/cgi-bin/d?ci=APRP6&c29=plid,15138756139246933&c30=bldv,1.2.19&forward=0&c6=drm,NA&ca=38716_HL17_HOL17W3_CC&pc=29&cr=17522_29_I_00000...

Example Duration Ping https://secure-drm.imrworldwide.com/cgi-bin/d?ci=APRP6&c29=plid,15138756139246933&c30=bldv,1.2.19&forward=0&c6=drm,NA&ca=38716_HL17_HOL17W3_CC&pc=29&cr=17522_29_D_01000...

Example Quarter Hour Ping https://secure-drm.imrworldwide.com/cgi-bin/d?ci=APRP6&c29=plid,15138756139246933&c30=bldv,1.2.19&forward=0&c6=drm,NA&ca=38716_HL17_HOL17W3_CC&pc=29&aqhflg=1&cr=17522_Q29_00000...

Check your metadata in the View, Quarter Hour, or Duration pings:

Parameter Description
cr=16602_42_V_00000 Ping type of I, V, Q, or D
c19=stntyp,2 Station type should be 1, 2, or 99
c18=clb,WWWW-FM Should be the FCC defined call letter and band for the station
c17=stnid,37292 Should be a numeric value from 10000 to 99999

Certification

Submit Your App

Provide the URL of your test environment so he or she can test your player for certification. Do not go live with your player until you have completed certification.

Production Deployment

After you obtain Nielsen Certification: 1. Disable debug logging by deleting {nol_sdkDebug: 'DEBUG'} from initialization call. 2. Change your sfcode amd apid to the production values.

Example Production Settings

Notice there are no debug parameters for a production deployment.

var _nolggGlobalParams = { 
     sfcode : "drm", 
     apid : "PXFGJKR-BH45-JKY6-BKH7-67GJKY68GJK7", 
     apn : "AppName"
};

Sample Player

Script samples for the API calls can be obtained from your Nielsen Technical Account Manager.