DTVR Browser SDK

Engineering Portal / Digital / Digital in TV Ratings / DTVR Browser SDK

Prerequisites

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

• App ID (appid): Unique ID assigned to the player/site and configured by product.
• sfcode: Location of collection environment. During testing, please use the sfcode as “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-cert.imrworldwide.com/novms/js/2/ggcmb510.js"></script>

Define GlobalParams

    <script type=”text/javascript”>
    var _nolggGlobalParams =
    {
        sfcode: "cert",
        apid: "XXXXXXXXXXXXXXX",
        apn: "test-setup"
    };
    </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 data requirement. 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();

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	No
sfcode	Location of collection environment. During testing, all traffic should be directed to "cert".	"cert" – testing "us" – production || Yes
nol_sdkDebug	Enables Debug Mode which allows output to be viewed in console.	"console"	No

apid and sfcode are mandatory parameters while nol_sdkDebug and apn are optional. Use nol_sdkDebug to create logs, only in test environments.

    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", parameter object);

Event is passed in parameter 1 and the argument is passed in parameter 2.

Configure API calls - loadMetadata

Use loadMetadata (Browser) to pass the metadata object. The data must be passed as a JSON string.

    this.onMeta(function(data, player) {nSdkInstance.ggPM("loadMetadata", metadataObject) });

Below is a sample metadata object.

    var metadataObject =
    {
        channelName: "WXYZ",
        type: "content",
        adModel: "1"
    }

Configure API calls - sendID3

Use sendID3 (Browser) to send ID3 payload of HLS content being played, as and when an ID3 packet is received (approximately, once in every 10 seconds).

    this.onTimedMetadata(function(args) {nSdkInstance.ggPM("sendID3", ID3_Object) });

ID3_Object is the container to pass the retrieved ID3 tag from the streaming. The player should look for 'PRIV' ID3 tags and send 'owner' field (which typically starts from "www.nielsen.com") through this API. Refer to Browser SDK API Reference - Retrieving ID3 Tags for more information.

Sample ID3 tags

• www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00
• www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00

Note: ID3 tags are not applicable for International (Germany)

Refer to Browser SDK API Reference - Retrieving ID3 Tags section to know more details.

Configure API calls - end

Call end (Browser) only at the end of playback. Call play (Browser) when resuming the stream / starting the new stream.

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 [1]) should be displayed.
• For more details, refer to Browser SDK API Reference - Browser Opt-Out Implementation and Nielsen Digital Privacy.
  • Use getOptOutStatus (Browser) to retrieve the device’s Opt-Out status.

Testing an Implementation - App

See Digital Measurement Testing.