Skip to main content

​
Overview

Analytics events are simple JSON objects that are emitted by the BeyondWords Player. They contain information about user engagement. They are separate from player events which contain information about the current state of the player. Analytics events can be sent to three possible places:
  1. The BeyondWords dashboard via our ingestion endpoint (metrics.beyondwords.io)
  2. A custom analytics URL that you have configured (see Analytics > Preferences).
  3. A Google Analytics account that you have configured (see Analytics > Preferences).
In all cases, the event schema is identical. You can inspect the events that are sent by searching for metrics.beyondwords.io in the Network tab.

​
Example event

Example event
{
  "event_type": "play",
  "device_type": "desktop",
  "media_type": "content",
  "media_variant": "article"
  "project_id": 123,
  "content_id": "3f57001d-cb30-42c1-ad6f-047e813c360f",
  "source_id": "example-source-id",
  "analytics_id": 333,
  "ad_id": null,
  "media_id": 555,
  "media_format": "audio",
  "local_storage_id": "bef9218d-3871-450e-a7fa-5da65102f532",
  "listen_session_id": "839ff785-0cb8-4e74-a061-506f571c79ce",
  "session_created_at": 1672531200000,
  "duration": 123.45,
  "listen_length_seconds": 0.2,
  "listen_length_percent": 0.1620089105,
  "speed": 1,
  "segment_playback_enabled": true,
  "location": "https://example.com",
  "referrer": "https://example.com"
  "player_version": "1",
  "player_npm_version": "1.2.3",
}

​
Event schema

​
event_type
string
The type of analytics event. There are four types:
  • load: content loaded successfully and the media’s duration is known
  • play: the media started playing for the current content item
  • play_progress: playback reached the next 10% of the audio’s duration
  • ad_link_click: the user clicked on the click-through URL for an advert
​
device_type
string
The type of device that emitted the event. There are three types:
  • phone: the width of the browser was between 0px and 499px
  • tablet: the width of the browser was between 500px and 999px
  • desktop: the width of the browser was 1000px or greater
  • ios: the event was sent from a native ios app (e.g. player-ios)
  • android: the event was sent from a native android app (e.g. player-android)
​
media_type
string
The type of media loaded in the player. There are two types:
  • content: the event was emitted during content playback
  • ad: the event was emitted during advert playback
​
media_variant
string
The variant of media loaded in the player. There are two types:
  • article: the media is for the original article
  • summary: the media is for a summary of the article
​
project_id
integer | null
The numeric ID of the project whose content is loaded into the player. This field might be null if content wasn’t fetched from the API and is instead set manually in the player.
​
content_id
string | integer | null
The string UUID or numeric ID of the content currently loaded into the player. This field might be null if content wasn’t fetched from the API and is instead set manually in the player.
​
source_id
string | null
The string ID that can optionally be associated with the content currently loaded into the player. This field might be null if the source_id ID wasn’t set in the BeyondWords API.
​
analytics_id
integer | null
A numeric ID used by BeyondWords for associating this event with your project. This field might be null if content wasn’t fetched from the API and is instead set manually in the player.
​
ad_id
integer | null
The numeric ID of the advert that is currently loaded into the player. This field is null when an advert isn’t playing, i.e. when content is playing.
​
media_id
integer | null
The numeric ID of the content or advert media field that is currently loaded into the player. This field is null when VAST adverts are playing.
​
media_format
string
The format of media loaded in the player. There are two formats:
  • audio: the player is playing audio (or will play audio)
  • video: the player is playing video (or will play video)
​
local_storage_id
string | null
A string UUID associated with the current user and stored in local storage under the ‘beyondwords’ key. This field is null if advertConsent is set to ‘without-local-storage’.
​
listen_session_id
string
A string UUID associated with the current player instance. This ID changes after the page is reloaded and is different for each player instance.
​
session_created_at
integer
The unix time in milliseconds at which the first analytics event was sent from the current player instance, as reported by the user’s browser.
​
duration
float
The duration in seconds of the content or advert media currently loaded into the player.
​
listen_length_seconds
float
The duration in seconds that the user has listened to of the currently loaded media.
​
listen_length_percent
float
The percentage that the user has listened to of the currently loaded media.
​
speed
float
The speed at which the user is listening to the media, e.g. 0.5, 1 or 2.
​
segment_playback_enabled
boolean
Whether playback from segments is enabled, i.e. whether the clickableSections player setting is anything other than “none”.
​
location
string
The value of window.location.href when the event was emitted.
​
referrer
string
The value of document.referrer when the event was emitted.
​
player_version
string
This will always be the string “1” but we may use this later, e.g. to run A/B tests.
​
player_npm_version
string
The version of the NPM package as specified in the package.json file.

​
Sending your own events

If you are not using the BeyondWords player and have instead built your own player, you can still send analytics to BeyondWords and we will aggregate them and present them in the BeyondWords dashboard. A POST request should be sent to https://metrics.beyondwords.io according to the schema above. Please try to provide all fields so that events can be aggregated and presented correctly to the user. However, if some fields are missing, we will provide sensible defaults. For example, media_variant will default to "article", media_format will default to "audio" and device_type will default to 'desktop". We recommend you do not rely on these defaults if you are able to provide the data in the unlikely event that the defaults change in the future. Some fields may not be applicable (e.g. player_npm_version). In that case, it is fine to leave the fields blank and they will be ignored. It may be helpful to refer to the player implementation for more information about how a particular field is handled. To test custom events, there may be a delay before they appear in the BeyondWords dashboard. You may need to wait an hour or more for the events to appear. If you are having trouble or are unsure what to set a field to, please contact [email protected].