DCR & DTVR Flutter Integration

From Engineering Client Portal

Engineering Portal / Digital / DCR & DTVR / DCR & DTVR Flutter Integration

Integrate Nielsen SDK Api in Flutter App

Overview

The Nielsen Flutter Plugin provides a Dart API that bridges into the native Nielsen App SDKs (iOS and Android) using Flutter’s platform channels.

Flow: Dart → Platform Channel → iOS/Android Plugin → Nielsen App SDK

Supports SDK flavors: Global, GlobalAd, GlobalNoAd, AGF, AGFNoAd, AGFNoId

Each flavor corresponds to a different Nielsen SDK package. You select the one required by your business case in the pubspec.yaml.

Note : Support for Flutter in Nielsen SDK is available from version 10.1.0.0

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.

Setting up your Environment

  • Add dependency in pubspec.yaml
   dependencies:
    nielsen_flutter_plugin:
     git:
      url: https://github.com/NielsenDigitalSDK/flutter.git
      # The path below is for the 'Global' flavor.
      # See the table below to select the path for other flavors.
      path: Flutter/FlutterPlugin/Global/nielsen_flutter_plugin/nielsen_flutter_plugin
      ref: main
  • Select Your SDK Flavor Path
  Use the following path values to select the appropriate Nielsen SDK flavor:
Flavor Flavor path in pubspec.yaml
Global Flutter/FlutterPlugin/Global/nielsen_flutter_plugin/nielsen_flutter_plugin
GlobalAd Flutter/FlutterPlugin/GlobalAd/nielsen_flutter_plugin/nielsen_flutter_plugin
GlobalNoAd Flutter/FlutterPlugin/GlobalNoAd/nielsen_flutter_plugin/nielsen_flutter_plugin
AGF Flutter/FlutterPlugin/AGF/nielsen_flutter_plugin/nielsen_flutter_plugin
AGFNoAd Flutter/FlutterPlugin/AGFNoAd/nielsen_flutter_plugin/nielsen_flutter_plugin
AGFNoId Flutter/FlutterPlugin/AGFNoId/nielsen_flutter_plugin/nielsen_flutter_plugin
  • Import the plugin in your Dart code
  import 'package:nielsen_flutter_plugin/nielsen_flutter_plugin.dart';

Public API's

All API methods are static and require the sdkId that is returned by createInstance. 

import 'dart:convert';
import 'package:flutter/foundation.dart';
import 'package:nielsen_flutter_plugin_platform_interface/nielsen_flutter_plugin_platform_interface.dart';


/// Nielsen App SDK – Flutter Public APIs.
class NielsenFlutterPlugin {
 NielsenFlutterPlugin._();
 static final NielsenFlutterPlugin instance = NielsenFlutterPlugin._();

 NielsenFlutterPluginPlatform get _p => NielsenFlutterPluginPlatform.instance;

 bool _debugLogging = false;

 /// Enable/disable debug logging of raw native responses.
 void enableDebugLogs(bool enable) {
 _debugLogging = enable;
 }

 void _logDebug(String api, String? res) {
 if (_debugLogging) {
 debugPrint('[NielsenFlutterPlugin] $api → $res');
 }
 }

 // ----------------------------------------------------------------------
 // Instance lifecycle
 // ----------------------------------------------------------------------

 /// Creates a Nielsen SDK instance with the provided app info.
 /// Returns the generated sdkId string.
 Future<String?> createInstance(Map<String, dynamic> appInfo) async {
 final res = await _p.createInstance(jsonEncode(appInfo));
 _logDebug('createInstance', res);
 return res;
 }

 /// Releases a previously created Nielsen SDK instance.
 Future<void> free(String sdkId) async {
 final res = await _p.free(jsonEncode({'sdkId': sdkId}));
 _logDebug('free', res);
 }

 // ----------------------------------------------------------------------
 // Playback lifecycle and metadata
 // ----------------------------------------------------------------------

 /// Signals playback start and passes play metadata.
 Future<void> play(String sdkId, Map<String, dynamic> playData) async {
 final res =
 await _p.play(jsonEncode({'sdkId': sdkId, 'playdata': playData}));
 _logDebug('play', res);
 }

 /// Loads content/ad/static metadata into the active measurement session.
 Future<void> loadMetadata(String sdkId, Map<String, dynamic> metadata) async {
 final res = await _p
 .loadMetadata(jsonEncode({'sdkId': sdkId, 'metadata': metadata}));
 _logDebug('loadMetadata', res);
 }

 /// Notifies a temporary stop/pause/interruption in playback.
 Future<void> stop(String sdkId) async {
 final res = await _p.stop(jsonEncode({'sdkId': sdkId}));
 _logDebug('stop', res);
 }

 /// Ends the playback measurement session.
 Future<void> end(String sdkId) async {
 final res = await _p.end(jsonEncode({'sdkId': sdkId}));
 _logDebug('end', res);
 }

 /// Ends a static content session (if used in your workflow).
 Future<void> staticEnd(String sdkId) async {
 final res = await _p.staticEnd(jsonEncode({'sdkId': sdkId}));
 _logDebug('staticEnd', res);
 }

 /// Updates the playhead position (in seconds).
 Future<void> setPlayheadPosition(String sdkId, int positionSeconds) async {
 final res = await _p.setPlayheadPosition(
 jsonEncode({'sdkId': sdkId, 'position': '$positionSeconds'}),
 );
 _logDebug('setPlayheadPosition', res);
 }

 /// Reporting OTT update event to the SDK.
 Future<void> updateOTT(String sdkId, Map<String, dynamic> ottData) async {
 final res =
 await _p.updateOTT(jsonEncode({'sdkId': sdkId, 'ottData': ottData}));
 _logDebug('updateOTT', res);
 }

 // ----------------------------------------------------------------------
 // Timed metadata (ID3)
 // ----------------------------------------------------------------------

 /// Sends ID3 timed metadata to the SDK.
 Future<void> sendID3(String sdkId, String id3) async {
 final res = await _p.sendID3(jsonEncode({'sdkId': sdkId, 'sendID3': id3}));
 _logDebug('sendID3', res);
 }

 // ----------------------------------------------------------------------
 // Information / getters
 // ----------------------------------------------------------------------

 /// Returns opt-out status as a string ("true"/"false").
 Future<String?> getOptOutStatus(String sdkId) async {
 final res = await _p.getOptOutStatus(jsonEncode({'sdkId': sdkId}));
 _logDebug('getOptOutStatus', res);
 return res;
 }

 /// Returns the user opt-out URL string.
 Future<String?> userOptOutURLString(String sdkId) async {
 final res = await _p.userOptOutURLString(jsonEncode({'sdkId': sdkId}));
 _logDebug('userOptOutURLString', res);
 return res;
 }
 

/// Returns Disable metering for the app due to user opt out.
 Future<String?> userOptOut(String sdkId, String url) async {
 final res = await _p.userOptOut(jsonEncode({'sdkId': sdkId, 'url': url}));
 _logDebug('userOptOut', res);
 return res;
 }

 /// Returns the meter version string.
 Future<String?> getMeterVersion(String sdkId) async {
 final res = await _p.getMeterVersion(jsonEncode({'sdkId': sdkId}));
 _logDebug('getMeterVersion', res);
 return res;
 }

 /// Returns the demographicId string.
 Future<String?> getDemographicId(String sdkId) async {
 final res = await _p.getDemographicId(jsonEncode({'sdkId': sdkId}));
 _logDebug('getDemographicId', res);
 return res;
 }

 /// Returns the deviceId string.
 Future<String?> getDeviceId(String sdkId) async {
 final res = await _p.getDeviceId(jsonEncode({'sdkId': sdkId}));
 _logDebug('getDeviceId', res);
 return res;
 }

 /// Returns the vendorId string (if implemented natively).
 Future<String?> getVendorId(String sdkId) async {
 final res = await _p.getVendorId(jsonEncode({'sdkId': sdkId}));
 _logDebug('getVendorId', res);
 return res;
 }

 /// Returns the FPID string (if implemented natively).
 Future<String?> getFpId(String sdkId) async {
 final res = await _p.getFpId(jsonEncode({'sdkId': sdkId}));
 _logDebug('getFpid', res);
 return res;
 }
}

API Reference & Examples

  • createInstance

Creates a new Nielsen SDK instance and returns a unique sdkId string for future calls. 

final sdkId = await NielsenFlutterPlugin.instance.createInstance({
  "appid": "PXXXX-XXXX-XXXX",
  "sfcode": "us",
  "nol_devDebug": "DEBUG",
});
  • free

Releases the Nielsen SDK instance associated with the sdkId. Should be called when the session ends. 

await NielsenFlutterPlugin.instance.free(sdkId);
  • loadMetadata

Loads content metadata for the current session. 

await NielsenFlutterPlugin.instance.loadMetadata(sdkId, {
  "type": "content",
  "assetid": "video123",
  "program": "Example Show",
});
  • play

Signals the start of content playback. 

await NielsenFlutterPlugin.instance.play(sdkId);
  • stop

Signals that playback has been paused or stopped. 

await NielsenFlutterPlugin.instance.stop(sdkId);
  • end

Signals the end of content playback. 

await NielsenFlutterPlugin.instance.end(sdkId);
  • staticEnd

Signals the end of a static (non-video) content view. 

await NielsenFlutterPlugin.instance.staticEnd(sdkId);
  • setPlayheadPosition

Updates the SDK with the current playhead position in seconds. 

await NielsenFlutterPlugin.instance.setPlayheadPosition(sdkId, 120);
  • Identifiers & Info

Retrieve various IDs and version information from the SDK. 

final versionNumber = await NielsenFlutterPlugin.instance.getMeterVersion(sdkId);
final fpid = await NielsenFlutterPlugin.instance.getFpid(sdkId);
final vendorId = await NielsenFlutterPlugin.instance.getVendorId(sdkId);
final deviceId = await NielsenFlutterPlugin.instance.getDeviceId(sdkId);
final version = await NielsenFlutterPlugin.instance.getMeterVersion(sdkId);
  • Opt-Out

Check the user's opt-out status and get the URL for the opt-out web page. 

final status = await NielsenFlutterPlugin.instance.getOptOutStatus(sdkId);
final url = await NielsenFlutterPlugin.instance.userOptOutURLString(sdkId);
  • UserOptOut

Disable metering for the app due to user opt out. 

final userOptOut = await NielsenFlutterPlugin.instance.userOptOut(sdkId, url);
  • sendID3

Passes raw ID3 tags to the SDK for live/linear content measurement. 

await NielsenFlutterPlugin.instance.sendID3(sdkId, rawId3Tag);
  • enableDebugLogs

Call this one before you create any Nielsen instance. It enables debug logs from the Nielsen Flutter plugin.  

await NielsenFlutterPlugin.instance.enableDebugLogs(true);

Error Handling (iOS Specific) 

The plugin surfaces descriptive error codes if an API is called incorrectly or in an invalid state. Errors are logged to the console but are designed not to crash the application.

Error Code Error Description
NLS_JSON_INVALID The JSON passed to the API is invalid or cannot be parsed
NLS_ARGS_MISSING One or more required arguments are missing
NLS_SDK_NOT_FOUND No active SDK instance was found for the given sdkId
NLS_INIT_FAILED Nielsen SDK initialization failed
NLS_METHOD_UNSUPPORTED The requested API method is not supported in this context
NLS_PLAYHEAD_INVALID Playhead position is missing or not valid (expected seconds)

Example Log: [NielsenFlutterPlugin][ERROR] NLS_SDK_NOT_FOUND: No active SDK instance was found for the given sdkId - Unknown sdkId: 12345

Retrieved from "https://engineeringportal.nielsen.com/w/index.php?title=DCR_%26_DTVR_Flutter_Integration&oldid=7407"