DCR Video Browser SDK

Engineering Portal / Digital / DCR & DTVR / DCR Video 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".
• ggCom.as (For Flash Player Porjects only): Nielsen ActionScript Library to compile within the Flash player project. Configure ggCom.as as mentioned in subsequent sections and include the edited file in the project.

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

Step 1: 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>

Step 2: Define GlobalParams

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

For Flash integration, global parameters must be set as an object in ggCom.as, as follows.

   public var _nolggGlobalParams:Object =
   {
      apid: "TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      sfcode: "dcr-cert",
      apn: "test-player",
      nol_sdkDebug: "DEBUG",
      nsdkv: "511"
   };

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 Test: begins with ‘T’ and is used for testing, and 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);

For Flash integration Instantiate Nielsen Browser SDK in the Flash player’s controller. Below is an example code for player setup & instantiation of the SDK.

    public function setupPlayer():void
    {
      ggCom.getInstance(RootReference.stage.loaderInfo);
      var setup:PlayerSetup = new PlayerSetup(_player, _model, _view);
      …
      …
    }

Step 4: 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. For Flash integration

    ggCom.getInstance().PM('loadMetadata',_metadata);

Configure API calls - loadMetadata

Use loadMetadata (Browser) to pass ‘content’ and ‘ad’ metadata. The CMS data must be passed as a JSON object.

    nSdkInstance.ggPM("loadMetadata", metadataObject);

Refer to loadMetadata (Browser) for the list of parameters to be passed in the JSON object.

Note: Trigger the loadMetadata (Browser) call with content metadata ("type": "content") before sending any "preroll" ad metadata.

Configure API calls - setPlayheadPosition (Content)

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**	UTC of the live content	Client-defined	Yes	Seconds since 1970
2	Video On Demand (VOD)**	Position taken from beginning of the content in seconds.	Client-defined	Yes	Current player position from beginning of the content.

**Only one of these parameters is mandatory

For Flash integration

Video On Demand (VOD) Content

    ggCom.getInstance().PM('setPlayheadPosition', position);

Live Content

    ggCom.getInstance().PM('setPlayheadPosition', (Date.now()/1000));

Configure API calls - setPlayheadPosition (Ad)

Use setPlayheadPosition (Browser) to pass the position of the playhead for every one second while the advertisement is being played.

Key	Description	Values	Required? (Y/N)	Example
Ad	Position taken from beginning of the ad in seconds	Client-defined	Yes	Seconds since start of the ad

Configure API calls - stop

Call stop (Browser) when switching between content and ads, and also on pause. For Flash integration

    ggCom.getInstance().PM('stop', position);

Configure API calls - end

Call end (Browser) 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. For Flash integration

    ggCom.getInstance().PM('end', position);

API Call sequence

Use Case 1: Content has no Advertisements

Call loadMetadata (Browser) with JSON metadata for content as below.

{
  "type": "content",
  "assetid": "vid345-67483",
  "program": "ProgramName",
  "title": "Program S3, EP1",
  "length": "3600",
  "segB": "CustomSegmentValueB",
  "segC": "CustomSegmentValueC",
  "crossId1": "Reference11",
  "crossId2": "Reference22",
  "isfullepisode": "y",
  "airdate": "20161013 20:00:00",
  "adloadtype": "2",
  "hasAds": "0"
}

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

Use Case 2: Content has Advertisements

Call loadMetadata (Browser) with JSON metadata for ad as below.

{
   "type": "preroll",
   "assetId_ad": "ad=123"
}

Note: In case the individual ad details are not available, send ad pod (presence) details through the loadMetadata (Browser) and playhead position through setPlayheadPosition (Browser).

Call setPlayheadPosition (Browser) every one second until a pause / stop / another loadMetadata is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of loadMetadata (Browser).

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.

Type	Sample code	Description
Start of stream	nSdkInstance.ggPM(loadMetadata, contentMetadataObject);	// contentMetadataObject contains the JSON metadata for the content
Preroll	nSdkInstance.ggPM(loadMetadata, prerollMetadataObject);	// prerollMetadataObject contains the JSON metadata for preroll ad
	nSdkInstance.ggPM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the preroll ad is being played
	nSdkInstance.ggPM(stop, playheadPosition);	// Call stop after preroll occurs
Content	nSdkInstance.ggPM(loadMetadata, contentMetadataObject);	// contentMetadataObject contains the JSON metadata for the content being played
	nSdkInstance.ggPM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the content is being played
	nSdkInstance.ggPM(stop, playheadPosition);	// Call stop after the content is paused (ad starts)
Midroll	nSdkInstance.ggPM(loadMetadata, midrollMetadataObject);	// midrollMetadataObject contains the JSON metadata for the midroll ad
	nSdkInstance.ggPM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the midroll ad is being played
	nSdkInstance.ggPM(stop, playheadPosition);	// Call stop after midroll occurs
Content (End of stream)	nSdkInstance.ggPM(loadMetadata, contentMetadataObject);	// contentMetadataObject contains the JSON metadata for the content being played
	nSdkInstance.ggPM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the content is being played
	nSdkInstance.ggPM(end, playheadPosition);	// Called at the end of content
Postroll	nSdkInstance.ggPM(loadMetadata, postrollMetadataObject);	// postrollMetadataObject contains the JSON metadata for the postroll ad
	nSdkInstance.ggPM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the postroll ad is being played
	nSdkInstance.ggPM(stop, playheadPosition);	// Call stop after postroll occurs

Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.

For Flash integration

Type	Sample code	Description
Start of stream	ggCom.getInstance().PM(‘loadMetadata’,contentMetadataObject);	// contentMetadataObject contains the JSON metadata for the content
Preroll	ggCom.getInstance().PM(loadMetadata, prerollMetadataObject);	// prerollMetadataObject contains the JSON metadata for preroll ad
	ggCom.getInstance().PM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the preroll ad is being played
	ggCom.getInstance().PM(stop, playheadPosition);	// Call stop after preroll occurs
Content	ggCom.getInstance().PM(loadMetadata, contentMetadataObject);	// contentMetadataObject contains the JSON metadata for the content being played
	ggCom.getInstance().PM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the content is being played
	ggCom.getInstance().PM(stop, playheadPosition);	// Call stop after the content is paused (ad starts)
Midroll	ggCom.getInstance().PM(loadMetadata, midrollMetadataObject);	// midrollMetadataObject contains the JSON metadata for the midroll ad
	ggCom.getInstance().PM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the midroll ad is being played
	ggCom.getInstance().PM(stop, playheadPosition);	// Call stop after midroll occurs
Content (End of stream)	ggCom.getInstance().PM(loadMetadata, contentMetadataObject);	// contentMetadataObject contains the JSON metadata for the content being played
	ggCom.getInstance().PM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the content is being played
	ggCom.getInstance().PM(end, playheadPosition);	// Called at the end of content
Postroll	ggCom.getInstance().PM(loadMetadata, postrollMetadataObject);	// postrollMetadataObject contains the JSON metadata for the postroll ad
	ggCom.getInstance().PM(setPlayheadPosition, playheadPosition);	// playheadPosition is position of the playhead while the postroll ad is being played
	ggCom.getInstance().PM(stop, playheadPosition);	// Call stop after postroll occurs

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 Opt-Out Implementation and Nielsen Digital Privacy.

• Use getOptOutStatus (Browser) to retrieve the user’s current Opt-Out status.

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 Testing App Implementation.