Nielsen SDK Documentation

Contents

API Versions

Concept of Operations

API Version 5.1.1 (Current)

This section explains the concept of operations behind Nielsen API measurement framework and the integration of various software components of the SDK.

The Nielsen App SDK allows the third party / player application to pass data that Nielsen uses to accurately measure audience viewing.
  • This includes initializing App SDK with parameters
    • player name
    • version
    • sfcode
    • appid

Player application needs to send ID3 information if the stream contains ID3 tags. Nielsen App object automatically relays this information to Nielsen collection facility.

Description

The Nielsen API framework performs the following activities.

  • Retrieves a configuration file from Nielsen configuration servers based on the Application ID (appid) assigned to the application.
  • Processes ID3 & CMS tags received during video streaming sessions & discards non-Nielsen-specific information (third-party ID3 tags).
  • Buffers and transfers ID3 / CMS tags to Nielsen collection facility.
  • Supports ID3 / CMS tag caching – When users view downloaded content offline (no network connectivity), the player application
    • Transfers cached ID3 / CMS tags Nielsen collection facility after connectivity is restored.
    • CMS tags will not be carried over to the next viewing session.
  • Supports user opt-out selection – When a user opts out of measurement, the player application
    • Notifies Nielsen collection facility about the opt-out, and
    • Stops sending measurement data to Nielsen

Key components of Nielsen App SDK

Once integrated into a client’s player application, the operational flow of Nielsen App SDK is as follows.

  • Configure the application for Nielsen measurement
  • Handle ID3 tags and viewing events
    • Upon each launch of the player application, the application initializes a Nielsen API App SDK object and sets up an NSNotification Center ID3 tag event listener.
      • This handles HLS timed metadata events that come from the iOS media player object.
    • The API component collects general application information, player position (playhead) to ensure accurate measurement. Pass the following information to Nielsen Analytics framework.
      • Name of the player application.
      • Unique application ID (appid) assigned to each player app by Nielsen.
        Nielsen Technical Account Manager (TAM) will assign two appids for the application – a Test appid and a Production appid. The application must use the Test appid during the development, test, and certification processes. The Production appid is used only when the app has completed the certification process with Nielsen and is ready for submission to the App Store.
      • Software revision of the application.
      • CMS tags information using the loadMetadata, if the video content (programming or advertising) includes CMS tags
      • Streaming session start events which are referred as "play" events
      • Video playhead position every one second of streaming (for Digital Audio and DCR).
      • Streaming session pause and stop events which are referred as "stop" events
    • The Nielsen App framework requires access to the following iOS system services in order to function properly.
      Service Description
      UIApplicationWillEnterForegroundNotification
      (handleForeground)
      This system notification will cause the API framework to initiate the class objects, retrieve its config file from Nielsen configuration servers. Then, the framework can process viewing data.
      UIApplicationDidEnterBackgroundNotification
      (handleBackground)
      This notification causes Nielsen API framework to transmit all unsent messages to Nielsen collection facility and perform general housekeeping chores before going to the background. This includes terminating the current viewing session, freeing up memory, etc.
      iOS Application Keychain Services and IDFA identifier These two system services are used to
      • Persist Nielsen ID on the device, in case of application uninstall / re-install
      • Share the Nielsen ID with other Nielsen-enabled player apps
      iOS HTTPS functions Nielsen App SDK uses HTTPS to securely transfer initial configuration data of the streaming to Nielsen collection facilities.
      Persistent memory Persistent memory is used to store API state information, variables, unsent data, etc. The API is capable of caching ID3 tag data for 10 days. In extreme cases, the API will use about 30MB of persistent memory to cache unsent data. After network availability is back, the API will retry sending the cached data.
    • When the user starts viewing media from an HLS HTTP Adaptive Streaming session, the iOS operating system detects timed ID3 metadata events.
      • The player application should use this data to invoke sendID3. This API validates owner ID string from the PRIV frame of ID3 tag, processes its data, and queues data for transfer to Nielsen collection facility.
    • Player application is responsible for obtaining owner ID string in the PRIV frame of ID3 tags.
    • Call appDisableApi only after completely disabling measurement (kill switch) and not to enable / disable Nielsen measurement.
  • Transfer data to Nielsen collection facility
    • Transfer viewing data to Nielsen collection facility using a HTTP and HTTPS connection. Data transferred to Nielsen collection facility should include –
      • Nielsen ID3 tags
      • Channel name
      • Descriptive information including CMS tags (for Digital Audio or DAR)
      • Viewing patterns and
      • General information about the player application (player name, player version, Nielsen API revision, etc.).
    • All data collected and transferred to the collection facility is carefully protected to ensure that the anonymity of the user is preserved.

Nielsen App SDK supports measurement on TVOS-based devices like Apple TV. Contact your Nielsen TAM for more details.