Analytics

In addition to knowing what hardware you’ve shipped where, you can now monitor when and how your products are being used by your actual customers.

Raw Data and Dashboards

All data sent with the analytics API is segregated from other Audiogum customers. We offer the ability for you to obtain the raw event JSON and aggregations via a dedicated S3 bucket - this can be used to pull the data back into any existing analytics workflows you have.

We also offer Real Time, Daily and Monthly summary dashboards giving views on the aggregated data - see Analytics dashboards. The Raw Play Events dashboard can be useful to see the events being sent by your integration in real time.

If you don't have the credentials to access the dashboards or would like to get to your raw data, email your account manager or get in contact to discuss this.

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 content service. Note that these are created automatically by the platform for content service sign-in. 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. "tidal". 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 Tidal service:

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

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 audio source to which the event refers. The value playable should be used for all playback initiated via Audiogum playables service abstraction - see playback. In the case of other direct content service integrations outside of Audiogum playables, additional source values may be added on request. (Custom source values not listed here)
actionystart, mediabegin, mediaerror, begin, stop, resume, continue, seek, 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, details of the Audiogum playable as returned by the Audiogum API.
sourcedatanSourcedataIf the source is not playable (i.e. an integration outside of Audiogum API) details of the source content, 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 that are presented in the order would naturally occur:

ActionMeaning
startPlayback from a new source started - this could be a new playable has started or the device has switched to aux input for example.
beginAn item (song/track/chapter/episode etc.) from a source started.
mediabeginMedia has successfully begun playback. Certain services require reporting media states - see sendmediaevents under playback requirements. This event should be sent after begin once the media has started playing and should include the item streamurl requested.
mediaerrorMedia playback failed. Certain services require reporting media states - see sendmediaevents under playback requirements. This event should be sent after begin if the media fails to start playing and should include the item streamurl requested.
stopPlayback from a source stopped or paused.
resumePlayback from a source resumed (after pause/stop).
continuePlayback is ongoing. Certain services require periodic reporting that playback is still ongoing for long playing items such as radio - see sendcontinuationevent under playback requirements. This event should be sent after the number of seconds specified in sendcontinuationevent have elapsed since the last event was sent.
seekUser has moved offset in currently playing item.
completeAn item from a source has completed.
skipnextUser has skipped forward to the next item.
skipprevUser has skipped backward to the previous 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. "tidal"
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
streamurlnStringThe stream url in the case of mediabegin and mediaerror events

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. "apple"
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"
      }
    ]
  }
}

Media Failed to load - see mediabegin and mediaerror Actions for more information.

{
  "type": "playevent",    
  // ... common data ...
  "action": "mediaerror",
  "source": "playable",
  "playable": {
    "id": "f75d65fe39814a659af67ceb5853efc0",
    "userid": "b746b99cdb99455bbd0dfcfe2c5152b4",
    "name": "Radio Example",
    "parameters": {
      "type": "internetradio",
      "service": "tunein",
      "ref": "s12345"
    }
  },
  "offset": 0,  
  "item": {
    "service": "tunein",
    "ref": "s12345",
    "name": "Radio Example",
    "type": "internetradio",
    "streamurl": "http://....."
  }
}

Item continues to play - see continue Action for more information.

{
  "type": "playevent",    
  // ... common data ...
  "action": "continue",
  "source": "playable",
  "playable": {
    "id": "f75d65fe39814a659af67ceb5853efc0",
    "userid": "b746b99cdb99455bbd0dfcfe2c5152b4",
    "name": "Radio Example",
    "parameters": {
      "type": "internetradio",
      "service": "1tunein",
      "ref": "s12345"
    }
  },
  "offset": 1800,
  "item": {
    "service": "tunein",
    "ref": "s12345",
    "name": "Radio Example",
    "type": "internetradio"
  }
}

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"
}