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.
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.
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
The following are supported types of event (denoted by the type
field):
appstartevent
: Marks the start of an app sessionauthevent
: Authentication events (sign in and out)navigationevent
: Navigation within the appplayevent
: Player events such as starting and stopping musicprofileevent
: User profile events such as liking or disliking a songvoiceevent
: Voice recording events (success / failure metrics)The following fields apply to all types of event:
Field | Mandatory | Type | Description |
---|---|---|---|
type | y | See event types | Type of event |
sessionid | y | GUID without hyphens | Client-generated unique identifier for the session |
sequencenumber | y | Long integer | Client-generated incrementing number to indicate ordering of events within session |
localtime | y | Datetime | Full local ISO date/time according to client |
client | y | String | Name of client app or firmware |
clientversion | y | String | Version of client app or firmware |
platform | y | String | Name of platform/OS hosting app/firmware |
platformversion | y | String | Version of platform/OS |
devicename | y | String | Name of device or phone |
devicemanufacturer | y | String | Manufacturer of device/phone |
connection | y | none , wan or cellular | Current network connection |
countrycode | n | 2-char country code | Country of operation if known |
initiator | n | user or client | Indicates whether event resulted from user action or background |
timing | n | Long | The 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.
{
"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 record when the client app session starts. In addition to the common data, app start events may include:
Field | Mandatory | Type | Description |
---|---|---|---|
locale | n | {country: String, language: String} | Current locale settings of the device |
preferredlanguages | n | [String] | Current language preferences of the device |
{
"type": "appstartevent",
// ... common data ...
"locale": {
"country": "DE",
"language":"de-DE"
},
"preferredlanguages": ["de-DE"]
}
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:
Field | Mandatory | Type | Description |
---|---|---|---|
action | y | signin , signout or failure | |
service | n | String | Name of 3rd party service authentication applies to, e.g. "tidal". Omit if Audiogum login. |
provider | n | String | Name of federation provider if federated login, e.g. "Facebook". Omit otherwise. |
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:
Field | Mandatory | Type | Description |
---|---|---|---|
sourcepage | n | String | Page or main area of app where navigation originated |
sourcesubpage | n | String | Part of page where navigation originated if appropriate |
sourcecontrol | n | String | Control (e.g. button) where navigation originated |
sourcetag | n | String | Arbitrary info to distinguish UI component |
sourceindex | n | Long | Number to identify component e.g. if in a list |
targetpage | n | String | Destination page or main area of app after navigation |
targetsubpage | n | String | Part of destination page if appropriate |
referreruri | n | String | URL of resource where navigation originated if a deep link from external |
{
"type": "navigationevent",
// ... common data ...
"targetpage": "home"
}
{
"type": "navigationevent",
// ... common data ...
"sourcepage": "home",
"sourcesubpage": "menu",
"sourcecontrol": "profile-menu-item",
"targetpage": "profile"
}
Play events record media player activities such as starting radio, skipping songs etc. In addition to the common data, play events include:
Field | Mandatory | Type | Description |
---|---|---|---|
source | y | playable , spotifyconnect , airplay , bluetooth , dlna , aux , usb , other | The 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) |
action | y | start , mediabegin , mediaerror , begin , stop , resume , continue , seek , complete , skipnext or skipprev | The event that occured - see Actions |
offset | n | Long | In the case where the event occured during playback of an item, the time offset in seconds |
item | n | Item | In the case where the event occured during playback of an item, the details of the item |
playable | n | Playable | If the source is playable , details of the Audiogum playable as returned by the Audiogum API. |
sourcedata | n | Sourcedata | If the source is not playable (i.e. an integration outside of Audiogum API) details of the source content, if any exist. |
presetnumber | n | Long | If the action occured playing from a preset, the device's preset number. |
outputdevice | n | Outputdevice | If 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. |
The action
field may take the following values that are presented in the order would naturally occur:
Action | Meaning |
---|---|
start | Playback from a new source started - this could be a new playable has started or the device has switched to aux input for example. |
begin | An item (song/track/chapter/episode etc.) from a source started. |
mediabegin | Media 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. |
mediaerror | Media 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. |
stop | Playback from a source stopped or paused. |
resume | Playback from a source resumed (after pause/stop). |
continue | Playback 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. |
seek | User has moved offset in currently playing item. |
complete | An item from a source has completed. |
skipnext | User has skipped forward to the next item. |
skipprev | User has skipped backward to the previous item. |
An item
object appearing in a play or profile event is a map of the following fields:
Field | Mandatory | Type | Description |
---|---|---|---|
type | n | String | Type of item if known, e.g. song , chapter |
name | y | String | Title of the item |
artistdisplayname | n | String | Main artist name as would be displayed for a song |
albumname | n | String | Title of the album from which song is taken, if known |
duration | n | Long | Duration in seconds, if known |
service | n | String | Name of service from which song is played, e.g. "tidal" |
ref | n | String | Identifying reference for the song occording to the service |
id | n | GUID without hyphens | Audiogum id of the song if known |
artists | n | Array of Artists | Audiogum artists associated with the song if known |
streamurl | n | String | The 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.
The playable
object appearing in a play or profile event is a map of the following fields:
Field | Mandatory | Type | Description |
---|---|---|---|
id | y | GUID without hyphens | id of the playable |
userid | y | GUID without hyphens | id of the user owning the playable |
name | n | String | Name of the playable, e.g. the playlist title |
startindex | n | Long | The start index of the current (latest) playables response, if relevant |
parameters | y | Object | The parameters of the playable (verbatim from playables response) |
The sourcedata
object appearing in a play or profile event is a map of the following fields:
Field | Mandatory | Type | Description |
---|---|---|---|
name | n | String | Name of the content from the source if any (e.g. playlist name) |
service | n | String | Name of 3rd party service from which content comes, if any, e.g. "apple" |
ref | n | String | Identifying reference for the content occording to the service if any (e.g. playlist id) |
The outputdevice
object appearing in a play or profile event is a map of the following fields:
Field | Mandatory | Type | Description |
---|---|---|---|
connection | y | bluetooth , lightning , usb or aux | Type of connection from host to output device |
deviceid | n | String | Id of output device if known |
devicename | n | String | Name of the output device (e.g. as it appears in list of Bluetooth devices) if known |
devicetype | n | String | Type of output device/product if known |
devicemanufacturer | n | String | Name of output device manufacturer if known |
devicefirmware | n | String | Output device firmware name/version if known |
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"
}
}
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:
Field | Mandatory | Type | Description |
---|---|---|---|
action | y | like , dislike , unlike , undislike | The action performed. Note that un... values represent cancellation of a preference: for example unlike cancels like . This is not the same as dislike . |
target | y | song , playlist , album , artist , internetradio | The type of content to which the action refers |
source | n | playable , spotifyconnect , airplay , bluetooth , dlna , aux , usb , other | When appropriate, the type of audio source playing when the event occurs, as per play events. |
offset | n | Long | When appropriate, the offset time in seconds during playback of an item at which the event occured. |
item | n | Item | In the case where event occured during playback of an item, the details of the song. |
playable | n | Playable | If the source is playable , the details of the playable. |
sourcedata | n | Sourcedata | If the source is not playable , details of the source if any exist. |
presetnumber | n | Long | If the action occured while playing a preset, the device's preset number. |
artist | n | Artist | In the case where target is artist , the details of the artist. |
outputdevice | n | Outputdevice | If 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. |
An artist object appearing in a profile event is a map of the following fields:
Field | Mandatory | Type | Description |
---|---|---|---|
id | n | GUID without hyphens | Audiogum id of the artist if known |
name | y | String | |
service | n | String | 3rd party service from which artist reference comes, if any |
ref | n | String | Identifier of the aritst from 3rd party service, if any |
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 record metrics around voice transcription. In addition to the common data, such events may include:
Field | Mandatory | Type | Description |
---|---|---|---|
action | y | success , or failure | Mandatory - Whether the transcription succeeded. |
stoppedby | y | client , server or user | Mandatory - How the audio recording was stopped. |
ref | y | String | Mandatory - unique ref of voice interaction for correlation. |
sourcepage | n | String | Optional - Page or area of app where recording originated. |
Voice recording succeeded, but was stopped by user action:
{
"type": "voiceevent",
// ... common data ...
"action": "success",
"ref": "171d8f27-71c4-44ab-a014-421a7c796643",
"stoppedby": "user"
}