The table below contains a list of properties that can be configured in the
player. Usually, you will only need to set the identifiers such as projectId
and contentId and the rest of the settings will come from the API. If the
identifiers are changed after the player has loaded then a new API request will
be made to fetch the content and settings for those identifiers.
If you wish, you can override these settings in the
<script> tag before the player has loaded, or by
using the player SDK after the player has loaded. It is also
possible to load the player without making any API request by 'overriding' the
content and adverts properties with valid data structures as specified in the
table below. This is useful for player demo sites, for example.
| Name | Type | Explanation |
|---|---|---|
| playerApiUrl | string | The URL of the API that the player should fetch its data from. This is only really useful if you're a BeyondWords developer and want to use the internal staging environment to test something. Default value: https://api.beyondwords.io/v1/projects/{id}/player |
| projectId | number | The numeric ID of your project. This can be retrieved from the BeyondWords dashboard by visiting a project and copying the numeric ID from within the URL. Default value: undefined |
| contentId | string or number | The ID of content to load in the player. This can be retrieved from the BeyondWords dashboard by clicking on the embed button next to a piece of a content and copying it from within the code snippet. Normally this will be a string UUID, but legacy numeric IDs are also supported. Note: The player loads content from a projectId and one or more of the following identifiers: { contentId, playlistId, sourceId, sourceUrl, playlist }. If multiple identifiers are provided, the player will load all of the published content into a playlist, which might include other playlists. The order that content is loaded into the player will match the order of identifiers in this table. If you want to use a different order set the playlist property to an array of identifiers. Note that the player will only load content that has been processed and published. If you want to preview audio before publishing, as part of a drafting workflow, refer to the previewToken setting. Default value: undefined |
| playlistId | number | The ID of a 'manual' or 'automatic' playlist to load in the player. This can be retrieved from the BeyondWords dashboard and appears as part of the URL. (see note above regarding identifiers) Default value: undefined |
| sourceId | string | An alternative ID that can be used to load content in the player. This ID is a string that can optionally be provided when creating content via the BeyondWords API. For example, it could be the ID your CMS system uses to identify content. (see note above regarding identifiers) Default value: undefined |
| sourceUrl | string | An alternative method for loading content into the player. The source URL is optional and is the URL of where the content can be found on the web. This method of identifying content is discouraged in case the article moves to a different URL. (see note above regarding identifiers) If no other identifiers are set then the player will set this property to window.location.href. This allows the client-side integration to be used without having to specify an identifier. Default value: undefined |
| playlist | array of objects | An array of identifiers to load into the player. The four identifiers above are supported. The order that content is loaded into the player will match the order of the array: [ { contentId: "67f86dca-02e5-466d-99bf-0d1103f6c6e9" }, { contentId: "cc85c59c-7c68-4e5d-a225-eeecb40617e6" }, { sourceId: "some-external-id-set-by-you" }, { sourceUrl: "https://example.com/my-article" }, { playlistId: 12345 }, { playlistId: 67890 }, ] If other top-level identifiers are set on the player such as contentId, these identifiers will be prepended to the playlist array and appear at the top. (see note above regarding identifiers) Default value: undefined |
| target | string or node | The location in the DOM to use as the root node of the player. It supports the following values: - this: when used in a script tag, the player will be initialized in a new div after the script tag - <string>: a query string to be passed to document.querySelector, e.g. "#some-id" - <node>: a DOM node, e.g. returned from document.getElementById("some-id") If no target is specified then the player will be initialized in a new div at the end of the <body> and the user-interface will not be shown. See Building your own UI for more information.Default value: undefined |
| clientSideEnabled | boolean | Whether to enable the BeyondWords client-side integration which can simplify the process of importing content into the BeyondWords platform. See the dedicated client-side integration documentation for a setup tutorial and a more detailed explanation of this feature. Default value: false |
| showUserInterface | boolean | Whether to show the user-interface. This can be set to false if you want to build your own user-interface on top of the core player functionality (e.g. in our iOS and Android SDKs). If the playerStyle is video then the <video> element will show without any controls. You can call player.target.requestFullscreen() as usual to enter fullscreen. See Building your own UI.Default value: true |
| showBottomWidget | boolean | Whether to show the widget that slides up from the bottom of the screen once you scroll past the player. Normally this is toggled automatically and should not be set manually. If you are building your own UI the widget will not automatically be shown/hidden when scrolling past the player so you will need to set this manually, e.g. using an Intersection Observer. Note that if widgetTarget is set then the widget will always appear inside the widgetTarget and no bottom widget will show, regardless of the value of this boolean. If showUserInterface is set to false then the bottom widget won't appear either, unless the widgetStyle is video. Default value: false |
| playerStyle | string | The style of player to display. There are five supported styles: - small: the smallest player that has the bare minimum of buttons - standard: the default player style that offers a good mix of functionality - large: a larger player that shows the playerTitle and an image - screen: a full screen player designed to be linked to from social media - video: a player that supports video adverts and scrolling text content If playerStyle is set to anything else (e.g. "none") then the player will be hidden. Default value: standard |
| playerTitle | string | The title to show at the top of the large, screen and video players. Normally this is automatically set to the name of your project but can be specified in the BeyondWords dashboard. It can also be overridden when initializing the player if you want to use a different title for the player. Default value: undefined |
| callToAction | string | The prompt to show on the small and standard players when it is stopped. If the value is falsy, it translates 'Listen to this article' into the user's language, according to their browser preference, assuming that language is supported by the player (see the list of supported languages). Default value: undefined |
| skipButtonStyle | string | The style of the skip buttons. There are four supported styles: - auto: skip by 'tracks' for a playlist and 'segments' for a single item - segments: skip backwards and forwards by one paragraph - seconds: seek backwards and forwards by 10 seconds - tracks: skip backwards and forwards by one playlist track By default, the 'seconds' style skips 10 seconds in both directions but you can control this with 'seconds-15' or 'seconds-15-30' to set a different number of seconds for backwards/forwards. Default value: auto |
| playlistStyle | string | Whether to show the playlist. There are three supported styles: - auto: show the playlist when there is more than one content item - show: show the playlist by default (can still by toggled by the user) - hide: hide the playlist by default (can still be toggled by the user) By default, the 'auto' and 'show' styles display 5 items on desktop and 4 on mobile before a scrollbar appears but you can set a different number. For example, 'auto-3' will show 3 items and 'show-10-8' will show a different number on desktop and mobile. This can be set to a very large number, e.g. 'show-99999' to never show a scrollbar. Default value: auto-5-4 |
| playlistToggle | string | Whether to show the playlist toggle button in the player. There are three supported styles: - auto: show the toggle when there is more than one content item - show: show the toggle - hide: hide the toggle Default value: auto |
| downloadFormats | array of strings | An ordered list of file extensions, e.g. ["mp3", "mp4"], that is used to determine whether to show the download button next to playlist items. The first extension that matches one of the content item's audio/video URLs will be downloadable with a filename of "<content title>.<extension>". Default value: [] |
| mediaSession | string | Whether to use the Media Session API. When enabled, the player will appear on your phone's lock screen and can be controlled using your native device buttons. There are three supported types: - auto: use the Media Session API if it is not already being used by your website - override: use the Media Session API and override your website's existing media session - none: do not use the Media Session API If there are multiple players on the page, the media session will be set to the player that is currently playing or that was most recently playing. Otherwise, the first player initialized is chosen. The media session is set whenever playback begins (when the PlaybackPlaying event is emitted). The media session makes use of many player settings. For example: - It shows the title from the content that is currently playing or will play after the advert - It shows the image from the active advert or content item - It falls back to a speaker icon that uses iconColor and backgroundColor - It disables the skip buttons and prevents scrubbing when an advert is playing - It respects the skipButton style, e.g. it can skip between segments (depending on the device) If any player is set to 'override' then the media session may be overridden, including by players that are set to 'auto'. If there is no existing media session, 'auto' and 'override' behave the same. Default value: auto |
| content | array of objects | The array of content to play in the player. Normally this is automatically set based on the identifiers but it can be overridden if you wish to set the content manually without making API requests. A playlist will be shown in the player if the the array contains multiple items. Note: Each content item can contain both audio and video media files. If the playerStyle or widgetStyle is 'video' and the HTML video element is visible when the track changes, the player will prefer video media and fall back to audio. Otherwise, it will prefer audio and fall back to video. The player will attempt to load media in array order until a file format that it is able to play is found. [ { id: "27b760cb-0838-4354-bf86-ac514c2ad0ca", title: "Content Title", imageUrl: "https://example.com/image.jpeg", sourceUrl: "https://example.com/my-article", sourceId: "article-123", adsEnabled: true, duration: 123.45, audio: [{ id: 123, url: "https://x.com/audio.mp3", contentType: "audio/mpeg", duration: 123.45 }], video: [{ id: 124, url: "https://x.com/video.mp4", contentType: "video/mpeg", duration: 123.45 }] segments: [{ marker: "paragraph-1", section: "body", startTime: 0.05, duration: 9.95 }], }, ] All fields are optional and the player will work with what it is given, rather than raise an error. - id will be included in events sent to analyticsCustomUrl and Google Analytics - title will be shown for the content item in the player - imageUrl will be shown in the large, screen and video players - sourceUrl will be used as the href of a link in the screen player - sourceId will be included in BeyondWords/custom/Google analytics events - adsEnabled will determine whether adverts play before/during/after this content item - duration is only used for display in the playlist and is normally fetched from the media - audio is an array of media sources for the content item (see note above) - video is an array of media sources for the content item (see note above) - segments is an array of timestamps used for skipping between paragraphs Default value: [] |
| contentIndex | number | The index of the active content item in the player. This can be set to change the track in a playlist. Default value: 0 |
| introsOutros | array of objects | An array of intros and outros to play before and after all of the content and adverts. Normally intros and outros are automatically set from your project but can be overridden if you wish to set the intros and outros manually. There are two different placements: - pre-roll: The element is an intro that plays before all content and adverts - post-roll: The element is an outro that plays after all content and adverts [ { placement: "pre-roll", audio: [{ url: "https://example.com/intro.mp3", contentType: "audio/mpeg" }], video: [{ url: "https://example.com/intro.mp4", contentType: "video/mpeg" }], }, { placement: "post-roll", audio: [{ url: "https://example.com/outro.mp3", contentType: "audio/mpeg" }], video: [{ url: "https://example.com/outro.mp4", contentType: "video/mpeg" }], }, ] See the note above about content media which also applies to intro and outro media. If the array contains multiple intros or outros, the player will choose one of each at random which then will be used for all players currently loaded on the page to keep the experience consistent. If skipButtonStyle is set to 'segments', the user can skip past the intro to the content and they can skip back from the outro to the last segment of the content. If skipButtonStyle is set to 'tracks', the intro/outro will be considered part of the first/last content item and the user can skip past them in a single click. If content is replayed by the user, the intro and outro will play again. The intro will be skipped if the user begins playback from currentTime > 0, e.g. when clicking on a segment in the article. Default value: [] |
| introsOutrosIndex | number | The index of the active intro or outro in the player. This can be set to play an intro or outro, but it is recommended not to do this manually because the rules around the placement will not apply. Default value: -1 |
| adverts | array of objects | An array of adverts to play in the player. Normally ads are automatically set from your project but can be overridden if you wish to set the adverts manually. There are two types of advert: - custom: An advert that specifies its own media sources and clickThroughUrl - vast: An advert that is fetched from the vastUrl, e.g. from Google Ads In the case of a 'custom' advert, the vastUrl field will be ignored. In the case of a 'vast' advert, the clickThroughUrl and media fields will be ignored. There are three different placements: - pre-roll: The advert plays before the content or between playlist items - mid-roll: The advert plays mid-way through a content item or between playlist items - post-roll: The advert plays after the content or between playlist items [ { id: 123, type: "custom", placement: "pre-roll", clickThroughUrl: "https://example.com/buy-my-product", textColor: "#00f", backgroundColor: "rgba(255, 255, 200, 0.8)", iconColor: "red", videoTextColor: "yellow", videoIconColor: "yellow", audio: [{ id: 555, url: "https://x.com/advert.mp3", contentType: "audio/mpeg", duration: 12.34 }], video: [{ id: 556, url: "https://x.com/advert.mp4", contentType: "video/mpeg", duration: 12.34 }], }, { id: 456, type: "vast", placement: "mid-roll", vastUrl: "https://pubads.g.doubleclick.net/gampad/ads?iu=/123456789/your/advert" textColor: "#00f", backgroundColor: "rgba(255, 255, 200, 0.8)", iconColor: "red", videoTextColor: "yellow", videoIconColor: "yellow", }, ] See the note above about content media which also applies to advert media. While an advert is playing it can 'take over' the user interface to show an image and different color theme or it will fall back to the default player colors for those that are not specified in the advert. Default value: [] |
| advertIndex | number | The index of the active advert in the player. This can be set to play an advert, but it is recommended not to do this manually because the rules around the placement will not apply. Default value: -1 |
| minDuration... ForMidroll | number | The minimum duration that a content item must have for a mid-roll advert to play. If a content item's duration is less than this time in seconds then a mid-roll advert won't play. Additionally, mid-roll adverts won't play during content items in playlists and will instead play in-between playlist items. Pre-roll and post-roll adverts will also play in-between items. Mid-roll adverts play after playback reaches 50% of the content item's duration at the next boundary between segments (paragraphs) to make the listening experience less jarring. Default value: 120 (two minutes) |
| minTimeUntilEnd... ForMidroll | number | When seeking, this setting controls the minimum amount of time before the end of playback that the user must seek for mid-roll adverts to play. In other words, this prevents mid-roll adverts from playing within the last N seconds if the user seeks near to the end of the progress bar. When seeking past 50% of the duration and before the number of seconds specified by this setting, mid-roll adverts will play immediately and interrupt playback. Mid-roll adverts won't be aligned to the boundaries between segments (paragraphs) in this case (as per setting above). Default value: 10 (seconds) |
| persistentAdImage | boolean | Whether to show an advert image in the 'large' and 'screen' playerStyle during regular content playback. The image will be clickable if a clickThroughUrl is set on the advert. The persistent advert will change to whichever advert played most recently. If the content has started but no advert has played yet, the image will be set to the first pre-, mid-, or post-roll advert in the adverts array in that order of precedence, i.e. pre-roll will take precedence. This setting only applies to 'custom' adverts. Adverts with type 'vast' will not be persistent. Default value: false |
| persistentIndex | number | The index of the persistent advert in the player. The can be set to show an advert, but it is recommended not to do this manually because the selection process above will not apply. Default value: -1 |
| duration | number | The duration of the active content item in the player. The duration is fetched from the loaded media, rather than the duration field in the content item which is only used for the playlist display. This property is intended to be read-only and should not be set manually, otherwise the duration shown in the user-interface will be incorrect until the media is changed, e.g. by changing track. Default value: 0 |
| currentTime | number | The current playback time of the media. The currentTime automatically updates while the media is playing and can be retrieved using the player SDK or set to a value to seek to the given time. If this setting is provided when initializing the player, the first track will begin from the given time. There is a brief period in which the currentTime will be 0 while the media loads and it will then revert back to the specified time after the MediaLoaded event has been emitted. Default value: 0 |
| playbackState | string | The current playback state of the media. The can be set to start or stop playback, provided the programmatic call is on behalf of a user action such as clicking a button. There are three states: - stopped: playback has not yet started or it has finished - playing: the media for the content item is playing - paused: the media for the content item is paused Default value: stopped |
| playbackRate | number | The current playback rate of the media. This can be set to speed up or slow down playback. The playbackRate will persist across tracks but temporarily resets to 1 during adverts. Default value: 1 |
| playbackRates | array of numbers | The visible playback rates that can be cycled through in the user interface. It is not a requirement that the playbackRate setting above be set to one of these values when using the player SDK. Default value: [0.5, 0.6, 0.7, 0.8, 0.9, 1, 1.1, 1.2, 1.3, 1.4, 1.5, 2, 2.5, 3] |
| widgetStyle | string | The style of widget to display at the bottom of the page once the user scrolls past the inline player. All five styles are supported (see playerStyle). Can be set to "none" to hide the widget. Default value: standard |
| widgetPosition | string | The horizontal position of the widget when it is showing. There are four supported options: - auto: show the widget in the center for the standard player, otherwise right - left: show the widget on the bottom-left corner of the screen - center: show the widget at the bottom of the screen in the middle - right: show the widget in the bottom-right corner of the screen This setting has no effect when widgetTarget is set. Instead, you can position the widgetTarget as needed using your own css styles that are applied to the root element of the widget. Default value: auto |
| widgetWidth | string | The width of the widget. Can be set to any CSS unit, including 500px, 50rem, 50% and fit-content. This property can be set to 0 to make the player use its smallest possible width. By default, the small playerStyle expands and collapses. You can force it to always be collapsed by setting this property to 0, or to always be expanded by setting this property to initial. Default value: auto |
| widgetMargin | string | The margin of the widget. Can be set to any CSS unit, including 50px, 5rem and 5%. The margin for each side of the widget can be set separately, e.g. "10px 20px 30px 40px" will set the top, right, bottom and left margins, respectively. You may also use shorthands to set multiple margins at once, e.g. "10px 5px" to set top/bottom and left/right margins, respectively. If the widgetPosition is center, the left/right margins will be averaged. Default value: 16px |
| widgetTarget | string or node | The location in the DOM to use as the root node of the widget. It supports the following values: - <string>: a query string to be passed to document.querySelector, e.g. "#some-id" - <node>: a DOM node, e.g. returned from document.getElementById("some-id") If widgetTarget undefined then the widget will show as a fixed element at the bottom of the screen once the user has scrolled past the player. When widgetTarget is set, the widget will always show, regardless of the value of showUserInterface and the scroll position of the user. Please note that the singular <video> element can only show behind one user interface at a time. It will be relocated to/from the widget while active and a message will show in the other interface. Additionally, the widgetPosition setting will have no effect when widgetTarget is used.Default value: undefined |
| textColor | string | The text color. Can be set to any CSS color, including red, #f00, #ff0000 and rgba(255, 0, 0, 0.8). This color can be overridden when an advert is playing by specifying it in the advert object. Default value: #111 |
| backgroundColor | string | The background color. Can be set to any CSS color, including red, #f00 and rgba(255, 0, 0, 0.8). This property can also be set to a linear gradient: linear-gradient(to right, #fcf, #fcc). This color can be overridden when an advert is playing by specifying it in the advert object. Default value: #f5f5f5 |
| iconColor | string | The icon color. Can be set to any CSS color, including red, #f00, #ff000 and rgba(255, 0, 0, 0.8). This color can be overridden when an advert is playing by setting it in the advert object. Default value: rgba(0, 0, 0, 0.8) |
| highlightColor | string | The highlight color for the current and hovered segments. Can be set to any CSS color, including red, #f00, #ff000 and rgba(255, 0, 0, 0.8). This color is not overridden when an advert is playing. Default value: #eee |
| videoTextColor | string | The text color of the surrounding user interface when playerStyle is video. Can be set to any CSS color, including red, #f00, #ff0000 and rgba(255, 0, 0, 0.8). This color can be overridden when an advert is playing by specifying it in the advert object. This setting does not affect the video itself. Default value: white |
| videoIconColor | string | The icon color of the surrounding user interface when playerStyle is video. Can be set to any CSS color, including red, #f00, #ff000 and rgba(255, 0, 0, 0.8). This color can be overridden when an advert is playing by setting it in the advert object. This setting does not affect the video itself. Default value: white |
| logoIconEnabled | boolean | Whether to show the BeyondWords logo icon. Default value: true |
| highlightSections | string | The sections to enable when highlighting segments in the article. This helps readers follow along by highlighting the currentSegment as the currentTime of the player changes. It also helps users understand they can click on a segment in the article to begin playback. It supports the following: - all: allow all segments in the article to be highlighted - body: allow segments that have a section of 'body' to be highlighted - summary: allow segments that have a section of 'summary' to be highlighted - none: don't allow any segments to be highlighted Additionally, you can use a double-barrelled string to set the behavior for the currentSegment and hoveredSegment separately. For example, 'all-none' will enable highlighting for the currentSegment and disable it for the hoveredSegment. Alternatively, 'none-body' will disable highlighting for the currentSegment and enable it for hovered segments in the 'body' section. This feature will only work for elements that have been correctly marked up on your page with a 'data-beyondwords-marker' attribute. See Segments Playback for more information. Default value: all |
| clickableSections | string | The sections to enable for the 'Playback from Segments' feature. This allows users to click on a segment in the article to begin playback from that segment. It supports the following values: - all: allow playback by clicking on any of the segments in the article - body: allow playback by clicking on segments that have a section of 'body' - summary: allow playback by clicking on segments that have a section of 'summary' - none: don't allow playback by clicking on segments If the currentSegment is clicked, it will pause and resume playback from the current position. Otherwise, it will skip to the hoveredSegment's startTime and begin playback. If the segment contains links or other elements that have 'onclick' or 'onmousedown' handlers, this feature will not interfere and the user can click those elements without affecting playback. If event listeners are used, you can call event.preventDefault() to prevent triggering playback. This feature will only work for elements that have been correctly marked up on your page with a 'data-beyondwords-marker' attribute. See Segments Playback for more information. Default value: all |
| segmentWidget... Sections | string | The sections to enable for showing the segment widget. This is a small user-interface that appears next to segments in the article. This allows users to click on a play/pause button next to the segment to begin playback from that segment. It supports the following values: - all: allow the segment widget to be shown next to all segments in the article - body: allow the segment widget to be shown next to segments that have a section of 'body' - summary: allow the segment widget to be shown next to segments that have a section of 'summary' - none: don't allow the segment widget to be shown next to any segments Additionally, you can use a double-barrelled string to set the behavior for the currentSegment and hoveredSegment separately. For example, 'all-none' will show the segment widget to next to the currentSegment and will not change when segments are hovered. Alternatively, 'none-body' will only show the segment widget next to segments that are hovered and have a section of 'body'. If the segment widget appears next to the current segment, it will show the play/pause button as usual. Otherwise, the segment widget will always show a play button and its circular progress bar will show the segment's startTime relative to the duration of the audio. The segment widget is 'sticky' which means that it continues to show when the user stops hovering over a segment. This feature will only work for elements that have been correctly marked up on your page with a 'data-beyondwords-marker' attribute. See Segments Playback for more information. Default value: all |
| segmentWidget... Position | string | The position of the segment widget relative to the segment text's rectangle. For convenience, hours of a clock are used for specifying the position. It supports the following values: - 1-oclock: above the text, on the right - 2-oclock: right of the text, at the top - 3-oclock: right of the text, vertically centered - 4-oclock: right of the text, at the bottom - 5-oclock: below the text, on the right - 6-oclock: below the text, horizontally centered - 7-oclock: below the text, on the left - 8-oclock: left of the text, at the bottom - 9-oclock: left of the text, vertically centered - 10-oclock: left of the text, at the top - 11-oclock: above the text, on the left - 12-oclock: above the text, horizontally centered The widget will be positioned approximately 50% of the widget's width away from the text. If the position is 7-oclock or 11-oclock the segment widget will be indented slightly to align with the play/pause button of the player, taking into account the current playerStyle. If the segment widget appears left or right of the text, a 'position: relative' style will be added to the data-beyondwords-marker element and the segment widget will be positioned absolutely. Default value: 7-oclock |
| currentSegment | object | The segment that aligns with the currentTime of the player. The currentSegment will be unaffected while an advert is playing and the audio will resume from the segment when the advert ends. The currentSegment additionally contains contentIndex and segmentIndex which refers to its position in the content array. The currentSegment is set and the CurrentSegmentUpdated event is emitted regardless of the segmentPlayback and highlightCurrent player settings (see above). This property will only be set for elements that have been correctly marked up on your page with a 'data-beyondwords-marker' attribute. See Segments Playback for more information. This property is intended to be read-only and should not be set manually. Default value: undefined |
| hoveredSegment | object | The segment that is currently being hovered over by the user. This will be set to null if the user hovers over a link or an element with 'onclick' or 'onmousedown' listeners so that highlighting does not apply to the segment from the highlightHovered setting. This helps explain to the user that playback will be unaffected if they click on a link or other elements within the segment. The hoveredSegment additionally contains contentIndex and segmentIndex which refers to its position in the content array. The hoveredSegment is set and the HoveredSegmentUpdated event is emitted regardless of the segmentPlayback and highlightHovered player settings (see above). This property will only be set for elements that have been correctly marked up on your page with a 'data-beyondwords-marker' attribute. See Segments Playback for more information. This property is intended to be read-only and should not be set manually. Default value: undefined |
| loadedMedia | object | The media source that is currently loaded into the player. This is set to an element from the audio or video arrays within content, adverts or introsOutros. { id: 123, url: "https://example.com/audio.mp3", contentType: "audio/mpeg", duration: 123.45, format: "audio", } This property is intended to be read-only and should not be set manually. This property is set by either the MetadataLoaded or the MediaLoaded event (both of them set this property). On iOS Safari, this event might not be emitted until the user presses play. It is recommended to use the ContentAvailable and NoContentAvailable events for deciding when to show the player. Default value: undefined |
| previewToken | string | The preview token that should be used to load pre-published content into the player. This is useful if you want to preview the generated audio before publishing it as part of a draft workflow. For example, this setting is used in our WordPress plugin to initialize the player for draft posts. Preview tokens are generated automatically by BeyondWords when content is first created. You can retrieve the preview token for a content item from our content API. For the previewToken setting to work, its value must match the preview token assigned to the content item. Note that there will still be a short delay while media is generated before the player will load. Default value: undefined |
| advertConsent | string | The level of consent provided by the user of your website for whether personalized ads are allowed. This only applies to adverts of type 'vast' and maps onto the parameters documented here. You are responsible for requesting consent from your users. There are three levels: - personalized: adds the npa=0 parameter to vastUrl so that personalized ads will play - non-personalized: adds the npa=1 parameter to vastUrl which switches off personalized ads - under-the-age-of-consent: adds the tfua=1 parameter which disables many forms of tracking The player copies the approach taken by Google which is to enable personalized ads by default and place the burden on the integrator to ensure they have requested consent from their users. Default value: personalized |
| analyticsConsent | string | The level of consent provided by the user of your website for whether usage analytics are allowed to be sent by the player to the BeyondWords dashboard and to the analyticsCustomUrl if it is set. You are responsible for requesting consent from your users. There are three supported levels: - allowed: analytics will be sent to BeyondWords and analyticsCustomUrl - without-local-storage: analytics will be sent but without local_storage_id - none: analytics will not be sent to BeyondWords or analyticsCustomUrl The player allows analytics by default because they do not contain any personally identifiable information and only contain random UUIDs to identify the same user across sessions. This UUID is persisted in local storage in the browser under the 'beyondwords' key. Default value: allowed |
| analyticsCustomUrl | string | A custom URL that analytics events should be sent to, in addition to BeyondWords. These events are exactly the same as those sent to BeyondWords. See Custom Analytics for more information. Default value: undefined |
| analyticsDeviceType | string | The device_type that should be sent in analytics events. There are six supported options: - auto: automatically detect the type of device (see below) - desktop: set the device_type to 'desktop' - tablet: set the device_type to 'tablet' - mobile: set the device_type to 'mobile' (intended for mobile web rather than native apps) - ios: set the device_type to 'ios' (intended for native iOS apps) - android: set the device_type to 'android' (intended for native Android apps) If device_type is set to auto then the player will use window width as a simple heuristic: - A value of 'desktop' will be sent if the width is >= 1000x - Otherwise, value of 'tablet' will be sent if the width is >= 500px - Otherwise, a value of 'mobile' will be sent This setting will apply to all analytics events emitted by the player, which includes those sent to the BeyondWords Dashboard, the analyticsCustomUrl and Google Analytics if analyticsTag is set. Default value: auto |
| analyticsTag | string | The Google Measurement ID to use when sending events to Google Analytics. When analyticsTag is set, events will always be sent to Google Analytics, regardless of analyticsConsent. Default value: undefined |
| controlPanel | string or node | The location in the DOM to use as a control panel for the player. It supports the following values: - <string>: a query string to be passed to document.querySelector, e.g. "#some-id" - <node>: a DOM node, e.g. returned from document.getElementById("some-id") The control panel allows you to change most of the player settings via dropdowns or text input fields. It automatically updates to show the current state of the player. The control panel appears on the right-hand side of the player demo page and the playback from paragraphs prototype. Default value: undefined |
| transitions | array of arrays | An array of transitions to call at specific times during playback. Transitions can be used to modify the player using its SDK, e.g. to change its style and toggle various settings (all those above). Transitions are used extensively on the player demo page to demonstrate its features. [ [0, 5, p => p.backgroundColor = "red"], [0, 10, p => p.playerStyle = "large"], [0, 15, p => p.playbackState = "paused"], ] The array contains three elements: the contentIndex, the startTime and the transition function. The first transition above will set the backgroundColor during contentIndex 0 after 5 seconds. Transitions are applied based on the currentTime of the player. If the user scrubs to a later time, then all transitions up to that time will run in order. Additionally, if the user scrubs back to an earlier time then the player's state will be restored to before the transition was run. Transitions remain in place when the next contentIndex begins. For example, the backgroundColor will remain "red" when contentIndex 1 plays and will become red if the user skips forward. You may call arbitrary, non-player functions in transitions but their effects will not be reversible. Default value: [] |
| onError | function | The function to call when an unhandled JavaScript error or promise rejection occurs. If this function returns true then the error will stop propagating. This can be useful, for example, to suppress error output from the player appearing in the JavaScript console. This function receives the error object as its only argument. In the case of a rejected promise, the function will receive event.reason which is usually the error object associated with the promise. If any player sets an onError function then all player instances on the page will use the function set first. This setting can only be used during initialization in new BeyondWords.Player(...). If the function is changed later through the player SDK, these changes will be ignored. Default value: () => {} |
