Agent configuration and payload specification

This page describes the configuration parameters of the Insight Agent, as well as the specifications of the payload that the agents send the Insight Collector for reporting.

Agent configuration

The agent supports the following configuration parameters:

Name	Type	Description	Example
collectorURL	String	Endpoint of the NAGRA Insight Collector service	"https://collector.insight-stats.com/api/v1/"
operatorId	String	Operator token, secret used to identify the tenants	“abcXYZ123"
appName	String	Name of the application	“My Video Player"
appVersion	String	Version of the application	“1.0"
deviceType	String	Type of device (handheld, desktop, stb)	“handheld"
samplingInterval	Integer	Number of seconds between each metrics sample.	30
reportingInterval	Integer	Number of seconds between each report that submits a collection of samples. (The actual reporting time should include a +-10% random jitter)	300

Payloads

There are two types of payload that the Insight Agent sends to the collector. Each of them is sent to a different API endpoint and are defined below:

Playback Metrics

Click here to see a playback metric report containing an array of playback metrics.

CODE

[
  {
    "viewingSeconds" : 0,
    "playerContext" : {
      "device" : {
        "id" : "testAppDeviceId"
      },
    },
    "timestamp" : 34576382.450433753,
    "sessionId" : "2E9105A8-6C74-4E1E-A412-C1AA15C377BC",
    "contentInformation" : {
      "uri" : "http://nagra.com",
      "channelId" : "channel1",
      "channelName" : "Channel One",
      "eventName" : "Event One",
      "bitrates" : [
        100,
        200
      ],
      "genre" : [
        "Music",
        "Documentary"
      ],
      "type" : "LIVE",
      "eventId" : "event1"
    },
    "bufferingSeconds" : 0
  },
  {
    "playerContext" : {
      "device" : {
        "id" : "testAppDeviceId"
      },
    },
    "offsetFromLive" : 20,
    "bufferingSeconds" : 0,
    "contentInformation" : {
      "uri" : "http://nagra.com",
      "channelId" : "channel1",
      "channelName" : "Channel One",
      "eventName" : "Event One",
      "bitrates" : [
        100,
        200
      ],
      "genre" : [
        "Music",
        "Documentary"
      ],
      "type" : "LIVE",
      "eventId" : "event1"
    },
    "sessionId" : "2E9105A8-6C74-4E1E-A412-C1AA15C377BC",
    "viewingSeconds" : 120,
    "timestamp" : 34696382.450433753
  },
  {
    "playerContext" : {
      "device" : {
        "id" : "testAppDeviceId"
      },
    },
    "offsetFromLive" : 20,
    "bufferingSeconds" : 10,
    "contentInformation" : {
      "uri" : "http://nagra.com",
      "channelId" : "channel1",
      "channelName" : "Channel One",
      "eventName" : "Event One",
      "bitrates" : [
        100,
        200
      ],
      "genre" : [
        "Music",
        "Documentary"
      ],
      "type" : "LIVE",
      "eventId" : "event1"
    },
    "sessionId" : "2E9105A8-6C74-4E1E-A412-C1AA15C377BC",
    "viewingSeconds" : 20,
    "timestamp" : 34726382.450433753
  },
  {
    "playerContext" : {
      "device" : {
        "id" : "testAppDeviceId"
      },
    },
    "offsetFromLive" : 0,
    "bufferingSeconds" : 0,
    "contentInformation" : {
      "uri" : "http://nagra.com",
      "channelId" : "channel1",
      "channelName" : "Channel One",
      "eventName" : "Event One",
      "bitrates" : [
        100,
        200
      ],
      "genre" : [
        "Music",
        "Documentary"
      ],
      "type" : "LIVE",
      "eventId" : "event1"
    },
    "sessionId" : "2E9105A8-6C74-4E1E-A412-C1AA15C377BC",
    "viewingSeconds" : 230,
    "timestamp" : 34956382.450433753
  }
]

Playback Events

Click here to see a playback event report containing an array of playback events

CODE

[
   {
      "sessionId":"b3c0cf04-f259-4cb8-8b89-aeeff3deb7c5",
      "timestamp":1585047146506,
      "playerContext":{
         "device":{
            "id":"123456",
            "type":"desktop"
         }
      },
      "contentInformation":{
         "type":"VOD",
         "contentId":"ABC123",
         "contentName":"Sintel Trailer",
         "duration":52.209
      },
      "events":[
         {
            "name":"play",
            "timestamp":1585047084228
         },
         {
            "name":"playing",
            "timestamp":1585047084273
         },
         {
            "name":"timeToVideoStart",
            "timestamp":1585047084273,
            "properties":{
               "time":0
            }
         },
         {
            "name":"pause",
            "timestamp":1585047090361
         },
         {
            "name":"playing",
            "timestamp":1585047092489
         },
         {
            "name":"pause",
            "timestamp":1585047096698
         },
         {
            "name":"seeked",
            "timestamp":1585047096700
         },
         {
            "name":"seeked",
            "timestamp":1585047096700
         },
         {
            "name":"playing",
            "timestamp":1585047096817
         },
         {
            "name":"pause",
            "timestamp":1585047121582
         },
         {
            "name":"playing",
            "timestamp":1585047123068
         }
      ]
   }
]

API specification document

The direct use of our API is strongly discouraged as it might change anytime without notice. You should use our agents (i.e. SDK) as they are actively maintained and provide a stable API as well as other desirable features such as data quality checks.