Digital Audio Browser SDK

From Engineering Client Portal

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

Prerequisites

To start using the Browser SDK, the following details are required:

  • App ID (apid): Unique ID assigned to the player/site and configured by product.
  • sfcode: Unique identifier for the environment that the SDK should point to. During testing, please use the sfcode as "dcr-cert".

If you do not have any of these pre-requisites or if you have any questions, please contact our SDK sales support team.

Import 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-dcr-cert.imrworldwide.com/novms/js/2/ggcmb510.js"></script>

Define GlobalParams

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

Initialize 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 dcr-cert. "dcr-cert" – testing

"dcr" – production || Yes

nsdkv Nielsen SDK Version currently being used. Nielsen assigned (‘511’ for Browser SDK 5.1.0, etc.) Yes
nol_sdkdebug Enables Debug Mode which allows output to be viewed in console. "console" No
    var gg = window.NOLCMB.getInstance(instanceName /*optional*/);
    gg.ggInitialize(window._nolggGlobalParams);

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 radio station Digital Audio Metadata. The CMS data must be passed as a JSON object.

    nSdkInstance.ggPM("loadMetadata", metadataObject);
Note: Digital Audio measurement is for digital-only audio content. For Digital Audio, provide the parameters shown in the table below. The first loadMetadata (Browser) call must have type as radio "type": "radio"
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

0: Custom station built per user 1: OTA streaming station with the same ad load 2:OTA station with a different ad load 3: Multicast eRadio or online station 4: On Demand Audio (podcasting) || 0, 1, 2, 3, or 4

provider Name of provider XYZ Provider


Sample Metadata Object

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

setPlayheadPosition=

Use setPlayheadPosition (Browser) to pass the position of the playhead while the content is being played.

# Key Description Values Required? (Y/N) Example
1 Live Unix timestamp (seconds since Jan-1-1970 UTC) of the live content Client-defined Yes 1541234567

If playhead is not available from audio measurement, allow the app to start a timer (1-5 seconds) and use the timer event to send playhead position to the SDK. Once the actual playhead is available, let the app send the proper playhead position. This allows the SDK to calculate and provide a closer value for duration.

Buffering state

  • Do not supply playhead position while the content is being buffered.
  • If the content is in buffering state continuously for more than 30 seconds, call end API.

stop

Call stop only at the end of ad or in case of interruptions during playback like flight mode, Wi-Fi toggle, etc. Call loadMetadata (Browser) and setPlayheadPosition (Browser) when the stream resumes. Call play when starting the new stream.

end

Call end only at the end of playback (but before a postroll occurs, if postrolls are inserted). Call play (Browser) when resuming the stream / starting a new stream.

    nSdkInstance.ggPM("stop", (Date.now()/1000));

API Call sequence

Use Case 1: Content has no Advertisements

Call loadMetadata with JSON metadata for content as below.

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

Call setPlayheadPosition (Browser) every one second until a pause / stop. Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.

Type Sample code Description
Start of stream nSdkInstance.ggPM(loadMetadata, contentMetadataObject); // contentMetadataObject contains the JSON metadata for the content
Content nSdkInstance.ggPM(setPlayheadPosition, playheadPosition); // playheadPosition is position of the playhead while the content is being played
End of Stream nSdkInstance.ggPM(end, playheadPosition); // playheadPosition is position of the playhead while the content is being played

Nielsen Measurement Opt-Out Implementation

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

When the user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content similar to http://secure-us.imrworldwide.com/nielsen_app_optout.html) should be displayed.

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

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.