Analytics events data model

Event data is supplied by the client app or firmware to the Audiogum API using an HTTP POST to https://api.audiogum.com/v1/events. Events may be sent in batches using a JSON body structured like so:

{
   "schemaversion": "1.0",
   "events": [

   ]
}

The events array may contain one or many events, each as a map with fields as described below.

This interaction requires authentication. For more information on API integration see the API explorer

Event types

The following are supported types of event (denoted by the type field):

Common data

The following fields apply to all types of event:

FieldMandatoryTypeDescription
typeySee event typesType of event
sessionidyGUID without hyphensClient-generated unique identifier for the session
sequencenumberyLong integerClient-generated incrementing number to indicate ordering of events within session
localtimeyDatetimeFull local ISO date/time according to client
clientyStringName of client app or firmware
clientversionyStringVersion of client app or firmware
platformyStringName of platform/OS hosting app/firmware
platformversionyStringVersion of platform/OS
devicenameyStringName of device or phone
devicemanufactureryStringManufacturer of device/phone
connectionynone, wan or cellularCurrent network connection
countrycoden2-char country codeCountry of operation if known
initiatornuser or clientIndicates whether event resulted from user action or background
timingnLongThe number of milliseconds it took to perform the action, if relevant, for performance diagnostics

Note the above does not include fields that are derived from the access token or otherwise generated by the service, including userid or deviceid. The client will not pass these explicitly in the events POST body per-event.

Example common data:

{
   "type": "...typename...",
   "sessionid": "5f71e09784354cfabd8253fe24d6b701",
   "sequencenumber": 7,
   "localtime": "2016-07-26T08:45:55.721118+01:00",
   "client": "Audiogum Android client",
   "clientversion": "1.0.1",
   "platform": "android",
   "platformversion": "5.1",
   "devicename": "XT1021",
   "devicemanufacturer": "motorola",
   "connection": "wan",
   "countrycode": "gb",
   "initiator": "user"
   // ... type-specific data ...
}

App start events

App start events record when the client app session starts. In addition to the common data, app start events may include:

FieldMandatoryTypeDescription
localen{country: String, language: String}Current locale settings of the device
preferredlanguagesn[String]Current language preferences of the device

Example app start event

{
   "type": "appstartevent",
   // ... common data ...
   "locale": {
      "country": "DE",
      "language":"de-DE"
   },
   "preferredlanguages": ["de-DE"]
}

Authentication events

Authentication events record sign in and sign out of either the Audiogum service or integrated 3rd party such as Spotify. In addition to the common data, such events may include:

FieldMandatoryTypeDescription
actionysignin, signout or failure
servicenStringName of 3rd party service authentication applies to, e.g. "Spotify". Omit if Audiogum login.
providernStringName of federation provider if federated login, e.g. "Facebook". Omit otherwise.

Example authentication events

Sign in to app:

{
   "type": "authevent",
   // ... common data ...
   "action": "signin"
}

Sign in to app using account federation:

{
   "type": "authevent",
   // ... common data ...
   "action": "signin",
   "provider": "facebook"
}

Sign in to Spotify service:

{
   "type": "authevent",
   // ... common data ...
   "action": "signin",
   "service": "spotify"
}

Navigation events record general user navigation around the app. In addition to the common data, navigation events may include:

FieldMandatoryTypeDescription
sourcepagenStringPage or main area of app where navigation originated
sourcesubpagenStringPart of page where navigation originated if appropriate
sourcecontrolnStringControl (e.g. button) where navigation originated
sourcetagnStringArbitrary info to distinguish UI component
sourceindexnLongNumber to identify component e.g. if in a list
targetpagenStringDestination page or main area of app after navigation
targetsubpagenStringPart of destination page if appropriate
referrerurinStringURL of resource where navigation originated if a deep link from external

Example navigation events

{
   "type": "navigationevent",
   // ... common data ...
   "targetpage": "home"
}
{
   "type": "navigationevent",
   // ... common data ...
   "sourcepage": "home",
   "sourcesubpage": "menu",
   "sourcecontrol": "profile-menu-item",
   "targetpage": "profile"
}

Play events

Play events record media player activities such as starting radio, skipping songs etc. In addition to the common data, play events include:

FieldMandatoryTypeDescription
sourceyplayable, spotifyconnect, airplay, bluetooth, dlna, aux, usb, otherThe type of audio source to which the event refers. playable covers all playback initiated via Audiogum playables API.
actionystart, stop, resume, begin, complete, skipnext or skipprevThe event that occured - see Actions
offsetnLongIn the case where the event occured during playback of an item, the time offset in seconds
itemnItemIn the case where the event occured during playback of an item, the details of the item
playablenPlayableIf the source is playable, the details of the playable.
sourcedatanSourcedataIf the source is not playable, details of the source if any exist.
presetnumbernLongIf the action occured playing from a preset, the device's preset number.
outputdevicenOutputdeviceIf the player output is on a separate device to the one recording the event, e.g. headset or Bluetooth speaker, details of that device if known.

Actions

The action field may take the following values:

ActionMeaning
startPlayback from a source started
stopPlayback from a source stopped or paused
resumePlayback from a source resumed (after pause/stop)
beginAn item (song/track/chapter etc) from a source started
completeAn item from a source has completed
skipnextUser has skipped forward
skipprevUser has skipped backward/rewound
seekUser has moved offset in currently playing item

Item

An item object appearing in a play or profile event is a map of the following fields:

FieldMandatoryTypeDescription
typenStringType of item if known, e.g. song, chapter
nameyStringTitle of the item
artistdisplaynamenStringMain artist name as would be displayed for a song
albumnamenStringTitle of the album from which song is taken, if known
durationnLongDuration in seconds, if known
servicenStringName of service from which song is played, e.g. "spotify"
refnStringIdentifying reference for the song occording to the service
idnGUID without hyphensAudiogum id of the song if known
artistsnArray of ArtistsAudiogum artists associated with the song if known

The schema allows other fields to be added here. This is to allow for additional data to be added to Audiogum playable items and recorded in events verbatim.

Playable

The playable object appearing in a play or profile event is a map of the following fields:

FieldMandatoryTypeDescription
idyGUID without hyphensid of the playable
useridyGUID without hyphensid of the user owning the playable
namenStringName of the playable, e.g. the playlist title
startindexnLongThe start index of the current (latest) playables response, if relevant
parametersyObjectThe parameters of the playable (verbatim from playables response)

Sourcedata

The sourcedata object appearing in a play or profile event is a map of the following fields:

FieldMandatoryTypeDescription
namenStringName of the content from the source if any (e.g. playlist name)
servicenStringName of 3rd party service from which content comes, if any, e.g. "spotify"
refnStringIdentifying reference for the content occording to the service if any (e.g. playlist id)

Outputdevice

The outputdevice object appearing in a play or profile event is a map of the following fields:

FieldMandatoryTypeDescription
connectionybluetooth, lightning, usb or auxType of connection from host to output device
deviceidnStringId of output device if known
devicenamenStringName of the output device (e.g. as it appears in list of Bluetooth devices) if known
devicetypenStringType of output device/product if known
devicemanufacturernStringName of output device manufacturer if known
devicefirmwarenStringOutput device firmware name/version if known

Examples

Start an internet radio station from from a preset via an Audiogum playable:

{
  "type": "playevent",
  // ... common data ...
  "action": "start",
  "source": "playable",
  "playable": {
    "id": "b3192fba407043cfb022dd0b1cf19920",
    "userid": "b746b99cdb99455bbd0dfcfe2c5152b4",
    "name": "BBC Radio 1",
    "parameters": {
      "ref": "1357",
      "service": "vtuner",
      "type": "internetradio"
    }
  },
  "presetnumber": 3
}

Start an audiobook from iDaddy via an Audiogum playable:

{
  "type": "playevent",
  // ... common data ...
  "action": "start",
  "source": "playable",
  "playable": {
    "id": "484073c726384460904c62dcfb41434e",
    "userid": "b746b99cdb99455bbd0dfcfe2c5152b4",
    "name": "英语人教版新起点一年级(上)",
    "startindex": 0,
    "parameters": {
      "type": "audiobook",
      "service": "idaddy",
      "ref": "ADAGMVAzDTY="
    }
  }
}

Start a personalised dynamic playlist assigned to a preset:

{
  "type": "playevent",    
  // ... common data ...
  "action": "start",
  "source": "playable",
  "playable": {
    "id": "f75d65fe39814a659af67ceb5853efc0",
    "userid": "b746b99cdb99455bbd0dfcfe2c5152b4",
    "name": "Music Now",
    "startindex": 676,
    "parameters": {
      "type": "dynamicplaylist",
      "variant": "taste"
    }
  },
  "presetnumber": 1
}

New song begins from an Audiogum dynamic playlist playing from Tidal service:

{
  "type": "playevent",    
  // ... common data ...
  "action": "begin",
  "source": "playable",
  "playable": {
    "id": "f75d65fe39814a659af67ceb5853efc0",
    "userid": "b746b99cdb99455bbd0dfcfe2c5152b4",
    "name": "Play Me",
    "startindex": 676,
    "parameters": {
      "type": "dynamicplaylist",
      "service": "tidal",
      "variant": "taste"
    }
  },
  "offset": 0,  
  "item": {
    "service": "tidal",
    "index": 678,
    "ref": "52680",
    "playbackcodec": "FLAC",
    "name": "Superstylin'",
    "type": "song",
    "artistdisplayname": "Groove Armada",
    "id": "fc4c846959394d0ab5c6b74d477b1e5c",
    "artists": [
      {
        "id": "3aded784cb2c49d788c6b74442475500",
        "name": "Groove Armada"
      }
    ]
  }
}

Start playing a playlist from Spotify Connect

{
  "type": "playevent",    
  // ... common data ...
  "action": "start",
  "source": "spotifyconnect",
  "sourcedata": {
    "service": "spotify",
    "ref": "spotify:user:212pk…:playlist:51T9…",
    "name": "My Example Playlist"
  }
}

Skip to next track playing Spotify Connect

{
  "type": "playevent",    
  // ... common data ...
  "action": "skipnext",
  "source": "spotifyconnect",
  "sourcedata": {
    "service": "spotify",
    "ref": "spotify:user:212pk…:playlist:51T9…",
    "name": "My Example Playlist"
  },
  "offset": 25,
  "item": {
    "service": "spotify",
    "ref": "spotify:track:2yWyFT6bW1Rd9cjVvYi4v8",
    "name": "Superstylin'",
    "artistdisplayname": "Groove Armada",
    "albumname": "Goodbye Country (Hello Nightclub)",
    "duration": 360,
    "artists": [
      {
        "service": "spotify",
        "ref": "spotify:artist:67tgMwUfnmqzYsNAtnP6YJ",
        "name": "Groove Armada"
      }
    ]
  }
}

Start playback from auxilliary input

{
   "type": "playevent",
   // ... common data ...
   "action": "start",
   "source": "aux"
}

Play a song from a source supporting playing item data

{
  "type": "playevent",
   // ... common data ...
  "action": "complete",
  "source": "???????",
  "sourcedata": {
    "service": "if relevant, name of 3rd party service",
    "ref": "if relevant, 3rd party id or ref for the content",
    "name": "name of content if any"
  },
  "item": {
    "name": "title of track if available",
    "artistdisplayname": "name of artist if available",
    "albumname": "name of album if available",
    "duration": 32
  }
}

Add output device when phone is playing to a Bluetooth speaker

{
  "type": "playevent",
  // ... common data ...
  // ... action, source, playable, item etc ...
  "outputdevice": {
    "connection": "bluetooth",
    "deviceid": "XX232YY",
    "devicetype": "Monkeybox",
    "devicename": "James' Monkeybox",
    "devicemanufacturer": "Vuaudio",
    "devicefirmware": "12.3.45"
  }
}

Add output device when phone is playing through analogue output (e.g. wired headphones)

{
  "type": "playevent",
  // ... common data ...
  // ... action, source, playable, item etc ...
  "outputdevice": {
    "connection": "aux"
  }
}

Example of play events for a session

Example of play events

Profile events

Profile events record user preference activity such as liking or disliking songs, artists or radio stations. In the case of songs, much of the data is similar to play events when the profile event happens in the context of playing the song. In addition to the common data, profile events may include:

FieldMandatoryTypeDescription
actionylike, dislike, unlike, undislikeThe action performed. Note that un... values represent cancellation of a preference: for example unlike cancels like. This is not the same as dislike.
targetysong, playlist, album, artist, internetradioThe type of content to which the action refers
sourcenplayable, spotifyconnect, airplay, bluetooth, dlna, aux, usb, otherWhen appropriate, the type of audio source playing when the event occurs, as per play events.
offsetnLongWhen appropriate, the offset time in seconds during playback of an item at which the event occured.
itemnItemIn the case where event occured during playback of an item, the details of the song.
playablenPlayableIf the source is playable, the details of the playable.
sourcedatanSourcedataIf the source is not playable, details of the source if any exist.
presetnumbernLongIf the action occured while playing a preset, the device's preset number.
artistnArtistIn the case where target is artist, the details of the artist.
outputdevicenOutputdeviceIf the player output is on a separate device to the one recording the event, e.g. headset or Bluetooth speaker, details of that device if known.

Artist

An artist object appearing in a profile event is a map of the following fields:

FieldMandatoryTypeDescription
idnGUID without hyphensAudiogum id of the artist if known
nameyString
servicenString3rd party service from which artist reference comes, if any
refnStringIdentifier of the aritst from 3rd party service, if any

Example profile events

Like a song played from an Audiogum dynamic playlist

{
  "type": "profileevent",    
  // ... common data ...
  "action": "like",
  "target": "song",
  "source": "playable",
  "playable": {
    "id": "f75d65fe39814a659af67ceb5853efc0",
    "userid": "b746b99cdb99455bbd0dfcfe2c5152b4",
    "name": "Play Me",
    "startindex": 676,
    "parameters": {
      "type": "dynamicplaylist",
      "service": "tidal",
      "variant": "taste"
    }
  },
  "offset": 43,  
  "item": {
    "service": "tidal",
    "index": 678,
    "ref": "52680",
    "playbackcodec": "FLAC",
    "name": "Superstylin'",
    "type": "song",
    "artistdisplayname": "Groove Armada",
    "id": "fc4c846959394d0ab5c6b74d477b1e5c",
    "artists": [
      {
        "id": "3aded784cb2c49d788c6b74442475500",
        "name": "Groove Armada"
      }
    ]
  }
}

Dislike an artist:

{
   "type": "profileevent",
   // ... common data ...
   "action": "dislike",
   "target": "artist",
   "artist": {
      "id": "05e12a2e6206411086ffb6a48dddb64d",
      "name": "Muse"
   }
}

Voice events

Voice events record metrics around voice transcription. In addition to the common data, such events may include:

FieldMandatoryTypeDescription
actionysuccess, or failureMandatory - Whether the transcription succeeded.
stoppedbyyclient, server or userMandatory - How the audio recording was stopped.
refyStringMandatory - unique ref of voice interaction for correlation.
sourcepagenStringOptional - Page or area of app where recording originated.

Example voice events

Voice recording succeeded, but was stopped by user action:

{
   "type": "voiceevent",
   // ... common data ...
   "action": "success",
   "ref": "171d8f27-71c4-44ab-a014-421a7c796643",
   "stoppedby": "user"
}