Digital Audio iOS SDK

From Engineering Client Portal

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png Digital Audio breadcrumbArrow.png Digital Audio iOS SDK

Requirements

You need to complete the requirements listed in First Time Installations here: Prerequisites

OS Versions Supported

The minimum IOS version supported by the Nielsen App SDK is iOS 7. If the Nielsen App SDK is initialized on devices with iOS versions 6.x and earlier, the app may not compile or the call to initWithAppInfo:delegate: could fail.

SDK API Sequence Flow

Below are the appropriate API calls for each user stage of your mobile audio application. Please note that pause and stop are synonymous for this application.

App Stages.png

Importing the SDK Library

You will need to add the Nielsen App SDK library to your Xcode project. Refer to iOS SDK API Reference - Importing Frameworks for information on importing the library.

Initializing the SDK

Initialize the Nielsen App SDK as soon as the application is launched within the viewDidLoad view controller delegate method using initWithAppInfo:delegate.

Number of Instances

The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously.

  • The SDK supports a maximum of four SDK instances per appid.
  • When four SDK instances exist, you must destroy an old instance before creating a new one; otherwise, when a fifth SDK instance is launched, the SDK will return “nil” from initWithAppInfo:delegate:
  • The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1.
If the App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.

Refer to iOS SDK API Reference - Initialization for more details on initializing an AppSDK object and the parameters required. Please note that the above link includes all products and Digital Audio does not use ID3 tags or the notifications required for ID3 tag usage.

Definition

 (instancetype)initWithAppInfo:(id)appInfo delegate:(id)delegate;

Parameters

Call initWithAppInfo:delegate: to initialize a Nielsen App SDK object. Please note that all parameters must be passed as a JSON object. The complete list of arguments that can be passed via the AppInfo JSON schema for the API are

# Parameter Description Values Example
1 appid Unique id assigned to the application by Nielsen. Use Test appid during dev and certification processes. Use Production to submit to App Store after receiving Nielsen certification. String starts with either "P" or "T" "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
2 appversion Current version of the application Client defined "7.3.1.8"
3 sfcode Nielsen environment that communicates with the SDK "drm" for prod, "cert" for testing "drm"
N/A appname As of SDK version 6.0.0, appname is no longer a required parameter during initialization. Client defined "Nielsen Sample Application"

Return Values

The application should check for valid return values after initialization. For NielsenAppApi object of type id, a NIL object is returned if the initialization failed.


Testing Example

Developers can use the SDK's debug flag for testing. To activate debug mode, pass the argument @”nol_devDebug”:@”INFO” in the JSON string for initWithAppInfo:delegate, as below.

NSDictionary* appInformation = @
         {
            @"appid": @"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            @"appname": @"Nielsen Sample Application",
            @"appversion": @"7.3.1.8"
            @"sfcode": @"cert",
            @"nol_devDebug": @"INFO"
         };
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];

The permitted values are

  • INFO: Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as an aide for certification.
  • WARNING: Indicates potential integration / configuration errors or SDK issues.
  • ERROR: Indicates important integration errors or non-recoverable SDK issues.
  • DEBUG: Debug logs, used by the developers to debug more complex issues.

Please take care to deactivate the debug flag before deploying your application to production.


Production Example

Notice there is no debug flag provided in production.

NSDictionary* appInformation = @
         {
            @"appid": @"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
            @"appname": @"Nielsen Sample Application",
            @"appversion": @"7.3.1.8"
            @"sfcode": @"drm"
         };
nlsAppApiMeter = [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:self];

Measurement API calls

play

Use play to tell the SDK that the user has started a listening event. If possible, pass descriptive information about the stream in the channelName and / or mediaURL parameters.

Both channelName and mediaURL are optional for Digital Audio Measurement. The channel name field is a 32-character field containing the name of the program or feed such as “The Dove-Tampa”, “Hot 107.9”, or “The Morning Zoo”. mediaURL is the URL for the content (media) that is being played. If mediaURL is not available, pass an empty value.

loadMetadata

Use loadMetadata to pass content identification with SDK Digital Audio Metadata.

Definition

    (void) loadMetadata :(id)metadata;

The parameters must be passed as a JSON object.

Example

Please see below for an example with the JSON parameters.

    
NSDictionary *metadata = @
    {
      @"dataSrc": @"cms",
      @"type": @"radio",
      @"assetid": @"WXYZ-FM",
      @"stationType": @"1",
      @"provider": @"MyRadioProvider"
    };
[nielsenAppApi loadMetadata: metadata];
Note: After the first play call, loadMetadata must have "type": "radio".

playheadPosition

Call playheadPosition every two seconds until the stream is stopped. The "Sample API Sequence" can be used for reference to identify the events and appropriate APIs during listening.

    (void) playheadPosition: (long long) playheadPos
# Key Description Required? (Y/N) Example
1 playheadPos Unix timestamp (seconds since Jan-1-1970 UTC) Yes 1503088575

Handling a Buffering State If the content is in a buffering state or experiences connectivity loss that affects the audio for 30 seconds or more, call the stop API.

Sample Playhead Calculation

    long long pos = [[NSDate date] timeIntervalSince1970];
     [nAppApiObject playheadPosition:pos];

stop

Calling stop helps prevent loss of credit by sending all cached measurement. The SDK only caches a limited amount of measurement when the device has no HTTP connectivity. The SDK will send cached measurement when the app regains connectivity after short periods of network loss. Call stop whenever the stream stops and before the app exits, whenever possible. stop should also be called for interruptions during playback like Airplane Mode, Wi-Fi toggle, and for:

  • Station changes, stops, and pauses
  • App enters buffering state during poor connectivity for 30 seconds or more
  • If streaming stops when headphones are unplugged
  • Alarms or calendar notifications that stop the stream
  • Receiving a phone call, making a phone call
  • Airplane mode or wi-fi enable or disablement


Sample API Sequence

User Action Sample Code Description
Start of stream [nielsenMeter play: channelName]; // channelName contains JSON metadata of channel/video name being played
[nielsenMeter loadMetadata: contentMetadataObject]; // contentMetadataObject contains the JSON metadata for the content being played
Streaming [nielsenMeter playheadPosition: position]; // playheadPosition passes the position of the playhead every two seconds while the content is being played
End of Stream [nielsenMeter stop]; // Content playback is completed, paused, or stopped.

Interruptions during playback Your audio app needs to call stop in the following interruption scenarios:

  • When the user pauses or stops play
  • Phone call interrupt that stops the stream
  • Network loss that causes the stream to stop. Does not apply when the app utilizes cached media to continue playing
  • Alarm Interrupt when streaming is stopped. Does not apply to audio ducking or lowered volume
  • Station changes
  • Unplugging of headphone that stops streaming

In case of encountering one of the above interruptions, the player application needs to

Nielsen Privacy Requirements

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 personally 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. Below is a summary of the privacy requirements. You can obtain the detailed instructions here: iOS SDK API Reference - iOS Opt-Out Implementation

  • In your App Store description, disclose that Nielsen collects listening data.
  • Include a link labeled "About Nielsen Measurement and Your Choices" in your Privacy Policy or EULA or as a button in a menu in your app.
  • When the user wants to opt in or opt out of measurement, present a page with Nielsen privacy text and/or choices to the user. The URL for this page must be obtained from the optOutURL) property.
  • The privacy page should be displayed in a webview within the app and not in any external browser.
  • Capture the user’s selection in the webview and pass it to the SDK through userOptOut.
  • Your app should perform the same process as above for Limit Ad Tracking features. In operating systems with Limit Ad Tracking or with opt out features, the Nielsen App SDK will detect the OS settings and opt the user out accordingly. The SDK will ignore the parameters when Limit Ad Tracking is in affect.

For more details, refer to iOS SDK API Reference - iOS Opt-Out Implementation and Nielsen Digital Privacy.

Obtaining Nielsen Certification

Please Note: You must obtain Nielsen certification before releasing your application for usage.

We want to ensure that your stations receive complete credit for listening. Before you deploy Nielsen will test that your app calls the SDK APIs correctly and provides correct station metadata. You can submit your app to Nielsen via TestFlight or other test distribution method. Please allow several days for this testing to complete. Test times vary per app; so, please contact your TAM for a test completion schedule.

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 Digital Measurement Testing.