Configuration APIReadSpeaker Enterprise Highlighting Developer | ReadSpeaker Enterprise Highlighting Developer - Resources for ReadSpeaker Highlighting developers

Introduction	A short explenation about our API
General Settings	Methods that can be used to change ReadSpeaker general settings
Default Settings	Methods that can be used to change ReadSpeaker default behavior
Phrases	Methods that can be used to change the Phrases used in the ReadSpeaker player
Callback	Methods that can be used to trigger custom functions

Introduction

The ReadSpeaker Highlighting Public API is accessible from any web page that has implemented the ReadSpeaker Highlighting JavaScript file, ReadSpeaker.js. See implementation instructions for more information on how to implement the ReadSpeaker Highlighting service.

The hosting web page interacts with the API by implementing a JavaScript object at window level. The object must be named exactly rsConf, taking uppercase and lowercase letter into account.

Example:

<script type="text/javascript">
window.rsConf = {
	phrases: {
		en_uk: {
			play: 'Start audio'
		}
	}
};
</script>

The way the API has been built; there is (almost) always a default value for each setting which is then overridden in the configuration object. In the example above, the default phrase for play in British English is ‘Play’.

General Settings

Path: rsConf.general
Settings that affect the service in general.

rsConf.general.cookieLifetime

Default value: 360 000 000 (~ 4 days)
Description: How long the settings cookie should survive on the user’s computer, expressed in milliseconds. The default setting is just over four days. Set this to null in order to use a session-only cookie that is not stored on the user’s computer after the browser closes.
Note!Some browsers have functionality for restoring previous sessions when starting. This might cause session-only cookies to be restored as well. This is something that is handled entirely by the browser and is not something ReadSpeaker can control.

rsConf.general.cookieName

Default value: ‘ReadSpeakerSettings’
Description: The name of the main cookie that will be used to store users’ personalized settings.

rsConf.general.defaultSpeedValue

Default value: 100
Description: This is the default speed value sent to Enterprise. This value is equal to the medium speed setting. Slow will be 25 units lower, relative to this default value and fast will be 25 units higher.

rsConf.general.domain

Default value: ‘readspeaker.com’
Description: The domain that is used for the calls to the ReadSpeaker servers.

rsConf.general.popupCloseTime

Default: 2000 (= 2 seconds)
Description: Determines the amount of time the popup will be visible when the user has selected some text. Expressed in milliseconds.

rsConf.general.syncContainer

Default: ‘default’ (font in IE and rs:span in other browsers)
Description: Sets the type of element the sync tags will use. By default <font> is used in Interner Explorer and <rs:span> in other browsers.

rsConf.general.subdomain

Default: ‘app’
Description: The sub-domain that is used for the calls to the ReadSpeaker servers.

rsConf.general.useCloudService

Default: true
Description: Whether or not to use ReadSpeaker’s CDN for fetching online resources. If set to false, the target environment must contain all required files.

rsConf.general.useCompactPopupButton

Default: true
Description: If set to true, only a listen icon will be displayed when the user selects text on a page. The non-compact mode displays the word ‘Listen’ as well as the icon.

Default Settings

Path: rsConf.settings
The difference between configuration and settings is that configuration affects everyone that uses the service, whereas settings/properties only affect the current user in the current browser. (The words settings and properties are used interchangeably throughout this document.)
In this section you specify which default settings should be used, if the user has not yet made any active choices.

rsConf.settings.hltoggle

Default: hlon
Description: This setting toggles highlighting on or off (hlon or hloff). If set to off, it overrides the rsConf.settings.hl value.

rsConf.settings.hl

Default: wordsent
Description: Which highlighting style to use. Default setting is highlighting both word and sentence.

rsConf.settings.hlicon

Default: iconon
Description: Whether or not to display a popup button when selecting text on a web page. The popup button can be used to start the audio playback.

rsConf.settings.hlspeed

Default: medium
Description: The reading speed.

rsConf.settings.hlword

Default: #a4cbff
Description: The color that will be used for highlighting words, expressed as a valid CSS color value.

rsConf.settings.hlsent

Default: #beffd6
Description: The color that will be used for highlighting sentences, expressed as a valid CSS color value.

rsConf.settings.hlscroll

Default: scrolloff
Description: Whether or not to automatically scroll the page vertically when the reading has reached the bottom of the browser’s viewport.

rsConf.settings.hltext

Default: #000000
Description: The color of the text that the highlighted elements should have. The color can be changed if a dark highlighting color is being used.

Phrases

Path: rsConf.phrases
The phrases section defines the translation of labels that are used in the user interface. Each supported language is defined in a separate object, defined by its five-letter countrylanguage code. For languages that have identical phrase sets a function can be used to return the language which serves as the basis for the current language, in order to avoid redundant entries.
Example:

window.rsConf = {
	phrases: {
		en_uk: {
			play: 'Play',
			...
			...
		},
		en_us: function() {
			return this.en_uk;
		}
	}
};

Or, alternatively, if you want to do this programmatically:

window.rsConf.phrases.en_us = function() {
	return window.rsConf.phrases.en_uk;
};

We will not list every single phrase, but we use American English, en_us, as the basis for all other languages. Consequently, en_us lists all phrases that are available for use.

Callback

Path: rsConf.cb
The callback API can be used to trigger custom functions when certain pre-defined events occur. Inside the callback functions the context (the this keyword) is always set to the player element that triggered the event. Optionally, some events provide arguments as well.
Example:

window.rsConf = {
	cb: {
		ui: {
			open: function() {
				doSomething();
			}
		}
	}
};

rsConf.cb.ui.open

Default: None
Description: This event fires when the user opens a player, which happens when the user clicks on a listen button, it always fire before rsConf.cb.ui.play. The reference to this will refer to the container element of the current player.

rsConf.cb.ui.play

Default: None
Description: Fires when the user clicks on a listen button, right after rsConf.cb.ui.open if the player was previously closed. Note that this event also fires when playback starts after the player has been paused or stopped. The this keyword will refer to the container element of the current player.

rsConf.cb.ui.pause

Default: None
Description: Fires when the user clicks on the pause button. The this keyword will refer to the container element of the current player.

rsConf.cb.ui.stop

Default: None
Description: Fires when the user clicks on the stop button. The this keyword will refer to the container element of the current player.

rsConf.cb.ui.beforeclose

Default: None
Description: Fires immediately after the user clicks on the close button in the player before any native close events have taken place. Note that opening a new player while the previous player is playing does not trigger this event, it only responds to direct user interaction. The this keyword will refer to the container element of the closed player.

rsConf.cb.ui.close

Default: None
Description: Fires when the user clicks on the close button in the player and after all native close events have taken place. Note that opening a new player while the previous player is playing does not trigger this event, it only responds to direct user interaction. The this keyword will refer to the container element of the closed player.

rsConf.cb.ui.settingsopened

Default: None
Description: Fires when the user clicks on the settings button. In this case the this keyword will refer to the container element of the settings panel.

rsConf.cb.ui.volumechanged

Default: None
Parameters:
1 New volume value (percent).
Description: Fires when the user changes the volume.

rsConf.cb.ui.timeupdated

Default: None
Parameters:
1 Current time. Tells us where the playhead is currently located in the audiostream.
Format: hh:mm:ss

2 Total time. The total length of the audio buffer. This value will increase as long as the audio file is loading.
Format: hh:mm:ss

Description: Fires every 0.5 seconds when the audio is playing. The this keyword refers to the player’s container element.

rsConf.cb.ui.progresschanged

Default: None
Parameters:
1 New value (percent).
Description: Fires when everytime the progressbar is updated, either because the audio is playing or because the user drag’n’dropped the playhead to a new position. The new value (in percent) is provided as the only parameter.