Template

iOS Configure API Calls

From Engineering Client Portal

Revision as of 19:42, 28 March 2022 by ColinBrown (talk | contribs) (Use Case 1: Content has no Advertisements)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Configure API Calls

Sample API Sequence

A Sample API sequence could follow this flow:

Type Sample code Description
On App Start
NielsenInit.createMainBrandApi(delegate: self)
self.data = loadStaticMetadata()
self.nielsenMeter .loadMetadata(self.data)
// Pass Static Metadata here if applicable
Start of stream nielsenMeter.play() // Call at start of each new stream
nielsenMeter.loadMetadata(contentMetadata) // MetadataObject contains the JSON metadata
for the content being played
Content nielsenMeter.playheadPosition(pos); // playheadPosition is position of the playhead
while the content is being played
End of Stream nielsenMeter.end() // Content playback is completed.

SDK Events

Event Parameter Description
'play' Call at start of each new stream
'loadMetadata' content/ad metadata object Needs to be called at the beginning of each asset
'playheadPosition' playhead position as integer

VOD: current position in seconds
Live: current UNIX timestamp (seconds since Jan-1-1970 UTC)
Note: 'PlayheadPosition' has to be called every second

Pass playhead position every second during playback

'stop' playhead position Call during any interruption to content or Ad playback and at the end of each Ad.
'end' playhead position in seconds Call when the current video asset completes playback and pass the playhead position.

Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.

Note: For livestream, send the UNIX timestamp, for VOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling stop, end or loadmetadata,.

Life cycle of SDK instance

Life cycle of SDK instance includes four general states:

  1. 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 Idle state.
  2. 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 an event to occur.
  3. Processing state – The SDK instance is processing playing information. The 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.
    1. playheadPosition – Call this API every one second when playhead position is active. If a LIVE event, use the current UNIX timestamp (seconds since Jan-1-1970 UTC).
    2. stop – Call this API when the content or Ad playback is interrupted and at the end of each Ad.
    3. end – Call when content completes. When called, the SDK instance exits from Processing state.
  4. Disabled state – The SDK instance is disabled and is not processing playing information.
    1. appDisableApi is set to true

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

API Call Sequence

Use Case 1: Content has no Advertisements

Call play() at start of stream

Call loadMetadata() with JSON metadata for content as below.

{
  "type": "content",
  "assetid": "vid345-67483",
  "program": "The Big Bang Theory",
  "title": "The Pants Alternative S03E18",
  "airdate": "2022-03-21T10:05:00", 
  "isfullepisode": "Yes",
  "adloadtype": "2",
  "length": "3600",
  ...
}

Call playheadPosition() every one second until a pause / stop. Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.

Type Sample code Description
Start of stream mAppSdk.play(); // Call at start of each new stream
mAppSdk.loadMetadata(contentMetaDataObject); // contentMetadataObject contains the JSON metadata for the content being played
Content mAppSdk.setPlayheadPosition(playheadPosition); // position is position of the playhead while the content is being played
Interruption mAppSdk.stop(); // call stop when content playback is interrupted
Resume Content mAppSdk.loadMetadata(contentMetaDataObject); // Call loadMetadata and pass content metadata object when content resumes
mAppSdk.setPlayheadPosition(playheadPosition); // continue pasing playhead position every second starting from position where content is resumed
End of Stream mAppSdk.end(); // Content playback is completed.

Use Case 2: Content has Advertisements

Call play() at start of stream

Call loadMetadata() with JSON metadata for ad as below.

{
   "type": "preroll",
   "assetid": "ad123"
}

Note: In case the individual ad details are not available, send ad pod (presence) details through the loadMetadata and playhead position through playheadPosition.

Call playheadPosition() every one second until a pause / stop / another loadMetadata() is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of loadMetadata().

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.

Type Sample code Description
Start of stream mAppSdk.play(); // stream starts
mAppSdk.loadMetadata(contentMetaDataObject); // contentMetadataObject contains the JSON metadata for the content being played
Preroll mAppSdk.loadMetadata(prerollMetadataObject); // prerollMetadataObject contains the JSON metadata for the preroll ad
mAppSdk.playheadPosition(playheadPosition); // position is position of the playhead while the preroll ad is being played
mAppSdk.stop(); // Call stop after preroll occurs
Content mAppSdk.loadMetadata(contentMetaDataObject); // contentMetadataObject contains the JSON metadata for the content being played
mAppSdk.playheadPosition(playheadPosition); // position is position of the playhead while the content is being played
Midroll mAppSdk.loadMetadata(midrollMetaDataObject); // midrollMetadataObject contains the JSON metadata for the midroll ad
mAppSdk.playheadPosition(playheadPosition); // position is position of the playhead while the midroll ad is being played
mAppSdk.stop(); // Call stop after midroll occurs
Content Resumes mAppSdk.loadMetadata(contentMetaDataObject); // contentMetadataObject contains the JSON metadata for the content being played
mAppSdk.playheadPosition(playheadPosition); // position is position of the playhead while the content is being played
End of Stream mAppSdk.end(); // Call end() at the end of content
Postroll mAppSdk.loadMetadata(postrollMetaDataObject); // postrollMetadataObject contains the JSON metadata for the postroll ad
mAppSdk.playheadPosition(playheadPosition); // position is position of the playhead while the postroll ad is being played
mAppSdk.stop(); // Call stop after postroll occurs

Note: Each Ad playhead should begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.