DCR React Native Integration
From Engineering Client Portal
Overview
The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc. The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings (DCR & DTVR), Digital Ad Ratings (DAR), Digital Audio. Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
- Application launch events and how long app was running
- Time of viewing a sub section / page in the application.
This guide will show how to use the Nielsen SDK in React Native applications on Android and iOS devices. We will not go into detail about what React Native is or how to create Apps with this Framework. If you are looking for information on this, please read the React-Native documentation.
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: Unique identifier for the environment that the SDK should point to.
- Nielsen SDK: The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team. Refer to Digital Measurement Onboarding guide for information on how to get a Nielsen App SDK and appid.
For more detail on the native SDKs please refer to the App integration guides available on this portal.
Implementation
This guide covers implementation covers
- the implementation of React-Native bridges for iOS and Android
- the usage of the exposed Javascript API
What we will not cover is the general setup of React-Native applications. If you are new to React-Native please refer to React-Native for documentation.
For simplicity we have focused on implementing a single instance of the Nielsen SDK. Should there be the need for multiple instances developers have to add some logic for that.
Setting up your Environment
iOS
The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the iOS Xcode project before working with the Nielsen SDK.
- UIKit.framework
- Foundation.framework
- AdSupport.framework
- SystemConfiguration.framework
- Security.framework
- Nielsen Analytics framework makes use of a number of functions in this library.
- AVFoundation.framework
- This framework is mandatory for the iOS SDK version 5.1.1 to work.
- CoreLocation.framework (Not applicable for International (Germany))
- CoreMedia.framework
- NielsenAppApi.framework
Nielsens App SDK is compatible with Apple iOS versions 9.0 and above.
Android
The first step is to add the AppSdk.jar library that runs on the Android’s Dalvik Virtual Machine to the libs folder (might have to be created) for the Android part of your project.
android/app/libs
The next step is to add the following permissions on the project’s AndroidManifest.xml file.
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>
For more details to handle runtime permissions in Android versions, please visit [1]. Download the latest google-play-services_lib and include it in the App’s project in order to use the App SDK.
- App SDK checks to see if there is a Google service available and updated.
- If not available or updated, App SDK will not use this service when executing its functions and will make reference to missing imports and the app will not be compiled.
Library
Nielsen App SDK uses the following packages/classes from the Google Play service.
- google-play-services_lib
Classes/package
- com.google.android.gms.ads.identifier.AdvertisingIdClient;
- com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
- com.google.android.gms.common.ConnectionResult;
- com.google.android.gms.common.GooglePlayServicesUtil;
- com.google.android.gms.common.GooglePlayServicesRepairableException;
- com.google.android.gms.common.GooglePlayServicesNotAvailableException;
Creating React-Native bridges for the Nielsen SDK
In order to be able to use Nielsens native SDKs React-Native bridges have to be implemented and added to the iOS and Android projects. The following shows implementations for both platforms, that provide the basic methods to start measuring the app. The source code can be copied from below to provide an easy start.
Please refer to the integration guides for Nielsens native SDKs to get a deeper understanding of the technical detail.
iOS
The iOS implementation of the bridge module consists of two files, a header and an implementation file, written in Objective-c. These two files need to be added to the iOS XCode project.
The header file is NielsenReactBridge.h
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#import <React/RCTBridgeModule.h>
#import <React/RCTEventEmitter.h>
@interface NielsenReactBridge : RCTEventEmitter <RCTBridgeModule>
@end
The actual implementation of the module happens in NielsenReactBridge.m
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#import "NielsenReactBridge.h"
#import <NielsenAppApi/NielsenAppApi.h>
static NSString *const TAG = @"NielsenReactBridge";
@interface NielsenReactBridge() <NielsenAppApiDelegate>
@property (strong) NielsenAppApi* nlsSDk;
@end
@implementation NielsenReactBridge
RCT_EXPORT_MODULE();
/**
* Since we need to communicate the opt-out url to javascript via events
* we need to implement the following method
*/
- (NSArray<NSString *> *)supportedEvents
{
return @[@"OptOutUrl"];
}
/**
* A logging helper method
*/
void NLSLog(NSString* tag, NSString* format, ...)
{
va_list argList;
va_start(argList, format);
NSLog(@"%@", [[NSString alloc] initWithFormat:[NSString stringWithFormat:@"[%@]: %@", tag, format] arguments: argList]);
va_end(argList);
}
/**
* Init creates the SDK instance and passes on the provided metadata.
* appInfo is simply passed to initWithAppInfo since the SDK already
* performs error checking
*/
RCT_EXPORT_METHOD(init:(NSDictionary *)appInfo)
{
NLSLog(TAG, @"init called with metadat '%@''", appInfo);
if (!self.nlsSDk) {
self.nlsSDk= [[NielsenAppApi alloc] initWithAppInfo:appInfo delegate:self];
}
}
/**
* Wrapper for the SDK's play method. The provided metadata is
* simply passed on
*/
RCT_EXPORT_METHOD(play:(NSDictionary *)channelInfo)
{
NLSLog(TAG, @"play called with metadata '%@'", channelInfo);
if (self.nlsSDk) {
[self.nlsSDk play:channelInfo];
}
}
/**
* Wrapper for the SDK's loadMetadata method. The provided contentMetaData is
* simply passed on
*/
RCT_EXPORT_METHOD(loadMetadata:(NSDictionary *)contentMetaData)
{
NLSLog(TAG, @"loadMetadata called with '%@'", contentMetaData);
if (self.nlsSDk) {
[self.nlsSDk loadMetadata:contentMetaData];
}
}
/**
* Wrapper for the SDK's setPlayheadPosition method. The provided playhead is
* simply passed on to the SDK
*/
RCT_EXPORT_METHOD(setPlayheadPosition:(nonnull NSNumber *)ph)
{
NLSLog(TAG, @"setHeadPosition called with '%@'",ph);
if (self.nlsSDk) {
[self.nlsSDk playheadPosition:[ph longLongValue]];
}
}
/**
* Wrapper for the SDK's stop method.
*/
RCT_EXPORT_METHOD(stop)
{
NLSLog(TAG, @"stop called");
if (self.nlsSDk) {
[self.nlsSDk stop];
}
}
/**
* Wrapper for the SDK's end method.
*/
RCT_EXPORT_METHOD(end)
{
NLSLog(TAG, @"end called");
if (self.nlsSDk) {
[self.nlsSDk end];
}
}
/**
* optOutUrl retrieves the url from the SDK instance and fires off the
* OptOutUrl event, so the url can be captured
*/
RCT_EXPORT_METHOD(optOutUrl)
{
[self sendEventWithName:@"OptOutUrl" body:@{@"url": self.nlsSDk.optOutURL}];
}
@end
Android
The Android implementation of the bridge module consists of two files, an implementation of a NielsenPackage to announce the actual module and the implementation of NielsenReactBridge itself. The implementations have been put into the Java package
com.nielsen.app.react
The package implementation is in com/nielsen/app/react/NielsenPackage.java
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package com.nielsen.app.react;
import com.facebook.react.bridge.NativeModule;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.ReactPackage;
import com.facebook.react.uimanager.ViewManager;
import com.nielsen.app.react.NielsenReactBridge;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
*/
public class NielsenPackage implements ReactPackage {
/**
* Override createNativeModules to return our bridge module
*/
@Override
public List<NativeModule> createNativeModules(ReactApplicationContext reactContext) {
List<NativeModule> modules = new ArrayList<>();
modules.add(new NielsenReactBridge(reactContext));
return modules;
}
/**
*/
@Override
public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {
return Collections.emptyList();
}
}
com/nielsen/app/react/NielsenReactBridge.java
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package com.nielsen.app.react;
import android.util.Log;
import com.facebook.react.bridge.LifecycleEventListener;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.modules.core.DeviceEventManagerModule;
import com.facebook.react.bridge.ReactMethod;
import com.facebook.react.bridge.ReadableMap;
import com.facebook.react.bridge.WritableMap;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.bridge.ReadableMapKeySetIterator;
import com.nielsen.app.sdk.AppSdk;
import com.nielsen.app.sdk.IAppNotifier;
import com.nielsen.app.sdk.AppLaunchMeasurementManager;
import org.json.JSONObject;
import org.json.JSONException;
/**
* NielsenReactBridge is the class briding between react JS code
* and the native Nielsen SDK.
*/
public class NielsenReactBridge extends ReactContextBaseJavaModule
implements IAppNotifier, LifecycleEventListener {
/**
*/
private static final String NIELSEN_TAG = "NielsenReactBridge";
private AppSdk mAppSdk = null; // the AppSdk main object
/**
* Constructor for the NielsenReactBridge
* Adds the new instance as LifeCycleEventListener for conttex
* @param context The react application context
*/
public NielsenReactBridge(ReactApplicationContext context) {
super(context);
context.addLifecycleEventListener(this);
}
/**
* Implements getName method from ReactContextBaseJavaModule
* @return The constant string 'NielsenReactBridge'
*/
@Override
public String getName() {
return "NielsenReactBridge";
}
/**
* Implements getName method from IAppNotifier
*/
@Override
public void onAppSdkEvent(long l, int i, String s) {}
/**
* Initializes the module for use
* @param obj An instance of ReadableMap (mapped JS object) containing
* initialization meta data
*/
@ReactMethod
public void init(final ReadableMap obj) {
Log.d(NIELSEN_TAG, "Called init");
if (null == mAppSdk) {
try {
JSONObject appSdkConfig = readableMapToJSONObject(obj);
mAppSdk = new AppSdk(getReactApplicationContext(), appSdkConfig, this);
if (!mAppSdk.isValid())
{
Log.e(NIELSEN_TAG, "SDK Init failed");
}
}
catch(Exception ex) {
}
}
}
/**
* Static method to convert ReadableMap instances to JSONObject instances
* (used by the Nielsen SDK)
* @param obj The ReadableMap instance to be converted
* @return An instance of JSONObject containing the mapped JS object
* values (if successful, empty otherwise)
*/
static private JSONObject readableMapToJSONObject(final ReadableMap obj) {
JSONObject ret = new JSONObject();
try {
ReadableMapKeySetIterator it = obj.keySetIterator();
while (it.hasNextKey()) {
String key = it.nextKey();
ret.put(key, obj.getDynamic(key).asString());
}
}
catch (JSONException ex) {
Log.e(NIELSEN_TAG, ex.getMessage());
}
return ret;
}
/**
* Wrapper for the Nielsen SDK play method. Simply forwards calls
* to the SDK.
* @param obj ReadableMap instance containing the mapped JS meta
* data object, e.g. {channelName: 'channel name here'}
*/
@ReactMethod
public void play(final ReadableMap obj) {
Log.d(NIELSEN_TAG, "Called play " + obj.toString());
if (null != mAppSdk) {
JSONObject playObject = readableMapToJSONObject(obj);
mAppSdk.play(playObject);
}
}
/**
* Wrapper for the Nielsen SDK loadMetadata method. Simply forwards calls
* to the SDK.
* @param obj ReadableMap instance containing the mapped JS meta
* data object
*/
@ReactMethod
public void loadMetadata(final ReadableMap obj) {
Log.d(NIELSEN_TAG,"Called loadMetadata");
if (null != mAppSdk) {
JSONObject contentMetadata = readableMapToJSONObject(obj);
mAppSdk.loadMetadata(contentMetadata);
}
}
/**
* Wrapper for the Nielsen SDK setPlayheadPosition method. Simply
* forwards calls to the SDK.
* @param ph The current playhead position
*/
@ReactMethod
public void setPlayheadPosition(final Double ph) {
Log.d(NIELSEN_TAG,"Called setPlayHeadPosition: " + " " + ph);
if (null != mAppSdk) {
mAppSdk.setPlayheadPosition(ph.longValue());
}
}
/**
* Wrapper for the Nielsen SDK stop method. Simply
* forwards calls to the SDK.
*/
@ReactMethod
public void stop() {
Log.d(NIELSEN_TAG, "Called stop");
if (null != mAppSdk) {
mAppSdk.stop();
}
}
/**
* Wrapper for the Nielsen SDK end method. Simply
* forwards calls to the SDK.
*/
@ReactMethod
public void end() {
Log.d(NIELSEN_TAG,"Called end");
if (null != mAppSdk) {
mAppSdk.end();
}
}
/**
* Wrapper to retrieve the optOutUrl from the Nielsen SDK.
* Emits a "OptOutUrl" event with the url as payload.
* Needs to be catched in JS
*/
@ReactMethod
public void optOutUrl() {
WritableMap params = Arguments.createMap();
if (null != mAppSdk) {
params.putString("url", mAppSdk.userOptOutURLString());
}
getReactApplicationContext()
.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
.emit("OptOutUrl", params);
}
/**
* Implements LifecycleEventListener's onHostResume method.
* Uses AppLaunchMeasurementManager.appInForeground to notify SDK about
* app coming to foreground again
*/
@Override
public void onHostResume() {
Log.d(NIELSEN_TAG,"Called onHostResume");
AppLaunchMeasurementManager.appInForeground(getReactApplicationContext());
}
/**
* Implements LifecycleEventListener's onHostPause method.
* Uses AppLaunchMeasurementManager.appInBackground to notify SDK about
* app going to background
*/
@Override
public void onHostPause() {
Log.d(NIELSEN_TAG,"Called onHostPause");
AppLaunchMeasurementManager.appInBackground(getReactApplicationContext());
}
/**
* Implements LifecycleEventListener's onHostDestroy method.
*/
@Override
public void onHostDestroy() {
Log.d(NIELSEN_TAG,"Called onHostDestroy");
}
}
The package needs to be provided in the getPackages method of the MainApplication.java file. This file exists under the android folder in your react-native application directory. The path to this file is: android/app/src/main/java/com/your-app-name/MainApplication.java.
import com.nielsen.app.react.NielsenPackage; //<-- Import the package in MainApplication.java
//...
protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
//...,
new NielsenPackage()); // <-- Add the bridge package to the getPackages method.
}
In order to import the bridges into the Javascript context, create a file
NielsenModule.js
import { NativeModules } from 'react-native'
export default NativeModules.NielsenReactBridge
SDK Initialization
The bridge implementations above allow the usage of one instance of the Nielsen App SDK. The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. For more information on this please read the relevant App SDK Guide.
The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
- The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
| Parameter / Argument | Description | Source | Required? | Example |
|---|---|---|---|---|
| appid | Unique id for the application assigned by Nielsen. It is GUID data type. | Nielsen-specified | Yes | PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX |
| appname | Name of the application | Client-defined | No | Nielsen Sample App |
| appversion | Current version of the app used | Client-defined | No | "1.0.2" |
| sfcode | Nielsen collection facility to which the SDK should connect.
Italian Clients
|
Nielsen-specified | Yes | "it" |
| nol_devDebug | Enables Nielsen console logging. Only required for testing | Nielsen-specified | While not live | "DEBUG" |
Sample SDK Initialization Code
import NielsenModule from './NielsenModule';
let appInformation = {"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "it",
"nol_devDebug": @"DEBUG"};
NielsenModule.init(appInformation);
APP SDK Error & Event Codes
To view the Error and Event codes for iOS and Android, please review the App SDK Event Code Reference page.
Configure Payload
All metadata is passed to the bridges in form of objects containing the in the following described properties. An example metadata object could look like
let metadata = {
'type':'content',
'assetid':'asset12345',
'program':'My Program',
'title':'My Title',
'length':'42',
'airdate':'20180302 16:32:00',
'isfullepisode':'n',
'adloadtype':'2'
};
The following section will explain the different values.
Configure metadata
Configure metadata should remain constant throughout the completion of an episode or live stream.
| Key | Description | Values | Required |
|---|---|---|---|
| channelName | Any string representing the channel/stream | custom | ✓ |
Content metadata
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
| Keys | Description | Values | Required |
|---|---|---|---|
| type | type of asset | "content" |
Yes |
| assetid | unique ID assigned to asset | custom (no Special Characters) |
Yes |
| program | name of program (25 character limit) | custom | Yes |
| title | name of program (40 character limit) | custom | Yes |
| length | length of content in seconds | seconds (0 for live stream) |
Yes |
| airdate | the airdate in the linear TV; if not known set it to eg. "19700101 00:00:00" | YYYYMMDD HH24:MI:SS | Yes |
| isfullepisode | full episode flag | "y"- full episode, "n"- non full episode |
Yes |
| adloadtype | type of ad load:
|
"2" - DCR measures content with dynamic ads |
Yes |
Ad Metadata
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
| Keys | Description | Values | Required |
|---|---|---|---|
| type | type of ad | 'preroll', 'midroll', or 'postroll' | ✓ |
| assetid | unique ID assigned to ad | custom | ✓ |
Static Measurement
The Nielsen SDK is able to monitor Application launch events and how long your app has been running. Once the Nielsen module has been Initialized, pass a metadata object to loadMeta data that follows these rules:
| Key | Description | Data Type | Value | Required? |
|---|---|---|---|---|
| type | asset type | fixed | 'static' |
Yes |
| assetid | Unique ID for each article | dynamic | custom | Yes |
| section | section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values | dynamic | custom | Yes |
You only need to do this once upon app start.
Configure API Calls
Sample API Sequence
A Sample API sequence could follow this flow:
| Type | Sample code | Description |
|---|---|---|
| On App Start | NielsenModule.loadMetadata(contentMetadata); |
// contentMetadata Object contains the JSON metadata for the impression |
| Start of stream | NielsenModule.play(channelName); |
// channelName contains JSON metadata of channel/video name being played |
NielsenModule.loadMetadata(contentMetadataObject); |
// contentMetadataObject contains the JSON metadata for the content being played | |
| Content | NielsenModule.playheadPosition(position); |
// playheadPosition is position of the playhead while the content is being played |
| End of Stream | NielsenModule.end(); |
// Content playback is completed. |
Life cycle of SDK instance
Life cycle of SDK instance includes four general states:
- Initial state – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the Initial state.
- Idle state – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
- Processing state – The SDK instance is processing playing information. play and loadMetadata calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
- playheadPosition – Call this API every one second when playhead position timer is fired.
- stop – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
- end – SDK instance exits from Processing state when this API is called.
Note: For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.
Note: In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call stop to stop the measurement.
- As soon as the playback resumes, call loadMetadata and playheadPosition.
Sequence of Calls
play
Use the play function to pass the channel descriptor information through channelName parameter when the user taps the Play button on the player.
NielsenModule.play(channelInfo);
loadMetadata
The loadMetadata function is used to inform the SDK about new content. The contentMetadata object passed in should contain the values as described above.
NielsenModule.loadMetadata(contentMetadata);
playheadPosition
Use playheadPosition to tell the SDK about the current position in the video. For live content this should be the Unix timestamp (seconds since Jan-1-1970 UTC). For on-demand content, simply the playhead position in seconds.
NielsenModule.playheadPosition(playheadPos);
stop
Tell the SDK that content playback has stopped.
NielsenModule.stop();
end
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
NielsenModule.end();
Privacy and Opt-Out
Opt-Out Implementation
To opt out, users must have access to "About Nielsen Measurement" page. User can click this page from app settings screen.
Include About Nielsen Measurement and Your Choices link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.
- URL for the Nielsen Privacy web page should be retrieved from via the
optOutURL()method of the SDK bridge and opened in 'WebView' / External browser. - If the returned value is null or empty, handle the exception gracefully and retry later.
Due to the limitation that native methods can't return values directly, the URL will be sent to the Javascript context as "OptOutUrl" event, with the url as the payload.
const nielsen = new NativeEventEmitter(NielsenModule);
const subscription = nielsen.addListener(
'OptOutUrl',
(data) => {
//display data.url
}
);
NielsenModule.optOutUrl();
//...
subscription.remove(); // do not forget to unsubscribe
The app must provide access to "About Nielsen Measurement" page for the users. Include "About Nielsen Measurement" and Your Choices link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.
- App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.
Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: Settings → Privacy → Advertising → Limit Ad Tracking.
User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.
Note: For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.
Going Live
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.
- Debug Logging: Disable logging by deleting
{nol_devDebug: 'DEBUG'}from initialization call.- Example Production Initialization Call - Refer to the production initialization call below:
Example:
let appInformation = {
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "it"
// Remove Flag: "nol_devDebug": "DEBUG"
};
NielsenModule.init(appInformation);