Immersive Reader JavaScript SDK Reference (v1.2)
The Immersive Reader SDK contains a JavaScript library that allows you to integrate the Immersive Reader into your application.
You may use npm, yarn, or an HTML <script> element to include the library of the latest stable build in your web application:
<script type='text/javascript' src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.2.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk
Functions
The SDK exposes the functions:
launchAsync
Launches the Immersive Reader within an HTML iframe element in your web application. The size of your content is limited to a maximum of 50 MB.
launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<LaunchResponse>;
launchAsync Parameters
| Name | Type | Description |
|---|---|---|
token |
string | The Microsoft Entra authentication token. For more information, see How-To Create an Immersive Reader Resource. |
subdomain |
string | The custom subdomain of your Immersive Reader resource in Azure. For more information, see How-To Create an Immersive Reader Resource. |
content |
Content | An object containing the content to be shown in the Immersive Reader. |
options |
Options | Options for configuring certain behaviors of the Immersive Reader. Optional. |
Returns
Returns a Promise<LaunchResponse>, which resolves when the Immersive Reader is loaded. The Promise resolves to a LaunchResponse object.
Exceptions
The returned Promise will be rejected with an Error object if the Immersive Reader fails to load. For more information, see the error codes.
close
Closes the Immersive Reader.
An example use case for this function is if the exit button is hidden by setting hideExitButton: true in options. Then, a different button (for example a mobile header's back arrow) can call this close function when it's clicked.
close(): void;
Immersive Reader Launch Button
The SDK provides default styling for the button for launching the Immersive Reader. Use the immersive-reader-button class attribute to enable this styling. For more information, see How-To Customize the Immersive Reader button.
<div class='immersive-reader-button'></div>
Optional attributes
Use the following attributes to configure the look and feel of the button.
| Attribute | Description |
|---|---|
data-button-style |
Sets the style of the button. Can be icon, text, or iconAndText. Defaults to icon. |
data-locale |
Sets the locale. For example, en-US or fr-FR. Defaults to English en. |
data-icon-px-size |
Sets the size of the icon in pixels. Defaults to 20px. |
renderButtons
The renderButtons function isn't necessary if you're using the How-To Customize the Immersive Reader button guidance.
This function styles and updates the document's Immersive Reader button elements. If options.elements is provided, then the buttons will be rendered within each element provided in options.elements. Using the options.elements parameter is useful when you have multiple sections in your document on which to launch the Immersive Reader, and want a simplified way to render multiple buttons with the same styling, or want to render the buttons with a simple and consistent design pattern. To use this function with the renderButtons options parameter, call ImmersiveReader.renderButtons(options: RenderButtonsOptions); on page load as demonstrated in the below code snippet. Otherwise, the buttons will be rendered within the document's elements that have the class immersive-reader-button as shown in How-To Customize the Immersive Reader button.
// This snippet assumes there are two empty div elements in
// the page HTML, button1 and button2.
const btn1: HTMLDivElement = document.getElementById('button1');
const btn2: HTMLDivElement = document.getElementById('button2');
const btns: HTMLDivElement[] = [btn1, btn2];
ImmersiveReader.renderButtons({elements: btns});
See the above Optional Attributes for more rendering options. To use these options, add any of the option attributes to each HTMLDivElement in your page HTML.
renderButtons(options?: RenderButtonsOptions): void;
renderButtons Parameters
| Name | Type | Description |
|---|---|---|
options |
renderButtons options | Options for configuring certain behaviors of the renderButtons function. Optional. |
renderButtons Options
Options for rendering the Immersive Reader buttons.
{
elements: HTMLDivElement[];
}
renderButtons Options Parameters
| Setting | Type | Description |
|---|---|---|
| elements | HTMLDivElement[] | Elements to render the Immersive Reader buttons in. |
elements
Type: HTMLDivElement[]
Required: false
LaunchResponse
Contains the response from the call to ImmersiveReader.launchAsync. A reference to the HTML iframe element that contains the Immersive Reader can be accessed via container.firstChild.
{
container: HTMLDivElement;
sessionId: string;
charactersProcessed: number;
}
LaunchResponse Parameters
| Setting | Type | Description |
|---|---|---|
| container | HTMLDivElement | HTML element that contains the Immersive Reader iframe element. |
| sessionId | String | Globally unique identifier for this session, used for debugging. |
| charactersProcessed | number | Total number of characters processed |
Error
Contains information about an error.
{
code: string;
message: string;
}
Error Parameters
| Setting | Type | Description |
|---|---|---|
| code | String | One of a set of error codes. For more information, see Error codes. |
| message | String | Human-readable representation of the error. |
Error codes
| Code | Description |
|---|---|
| BadArgument | Supplied argument is invalid, see message parameter of the Error. |
| Timeout | The Immersive Reader failed to load within the specified timeout. |
| TokenExpired | The supplied token is expired. |
| Throttled | The call rate limit has been exceeded. |
Types
Content
Contains the content to be shown in the Immersive Reader.
{
title?: string;
chunks: Chunk[];
}
Content Parameters
| Name | Type | Description |
|---|---|---|
| title | String | Title text shown at the top of the Immersive Reader (optional) |
| chunks | Chunk[] | Array of chunks |
title
Type: String
Required: false
Default value: "Immersive Reader"
chunks
Type: Chunk[]
Required: true
Default value: null
Chunk
A single chunk of data, which will be passed into the Content of the Immersive Reader.
{
content: string;
lang?: string;
mimeType?: string;
}
Chunk Parameters
| Name | Type | Description |
|---|---|---|
| content | String | The string that contains the content sent to the Immersive Reader. |
| lang | String | Language of the text, the value is in IETF BCP 47-language tag format, for example, en, es-ES. Language will be detected automatically if not specified. For more information, see Supported Languages. |
| mimeType | string | Plain text, MathML, HTML & Microsoft Word DOCX formats are supported. For more information, see Supported MIME types. |
content
Type: String
Required: true
Default value: null
lang
Type: String
Required: false
Default value: Automatically detected
mimeType
Type: String
Required: false
Default value: "text/plain"
Supported MIME types
| MIME Type | Description |
|---|---|
| text/plain | Plain text. |
| text/html | HTML content. Learn more |
| application/mathml+xml | Mathematical Markup Language (MathML). Learn more. |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word .docx format document. |
Options
Contains properties that configure certain behaviors of the Immersive Reader.
{
uiLang?: string;
timeout?: number;
uiZIndex?: number;
useWebview?: boolean;
onExit?: () => any;
customDomain?: string;
allowFullscreen?: boolean;
parent?: Node;
hideExitButton?: boolean;
cookiePolicy?: CookiePolicy;
disableFirstRun?: boolean;
readAloudOptions?: ReadAloudOptions;
translationOptions?: TranslationOptions;
displayOptions?: DisplayOptions;
preferences?: string;
onPreferencesChanged?: (value: string) => any;
disableGrammar?: boolean;
disableTranslation?: boolean;
disableLanguageDetection?: boolean;
}
Options Parameters
| Name | Type | Description |
|---|---|---|
| uiLang | String | Language of the UI, the value is in IETF BCP 47-language tag format, for example, en, es-ES. Defaults to browser language if not specified. |
| timeout | Number | Duration (in milliseconds) before launchAsync fails with a timeout error (default is 15,000 ms). This timeout only applies to the initial launch of the Reader page, when the Reader page opens successfully and the spinner starts. Adjustment of the timeout should'nt be necessary. |
| uiZIndex | Number | Z-index of the HTML iframe element that will be created (default is 1000). |
| useWebview | Boolean | Use a webview tag instead of an HTML iframe element, for compatibility with Chrome Apps (default is false). |
| onExit | Function | Executes when the Immersive Reader exits. |
| customDomain | String | Reserved for internal use. Custom domain where the Immersive Reader webapp is hosted (default is null). |
| allowFullscreen | Boolean | The ability to toggle fullscreen (default is true). |
| parent | Node | Node in which the HTML iframe element or Webview container is placed. If the element doesn't exist, iframe is placed in body. |
| hideExitButton | Boolean | Hides the Immersive Reader's exit button arrow (default is false). This value should only be true if there's an alternative mechanism provided to exit the Immersive Reader (e.g a mobile toolbar's back arrow). |
| cookiePolicy | CookiePolicy | Setting for the Immersive Reader's cookie usage (default is CookiePolicy.Disable). It's the responsibility of the host application to obtain any necessary user consent following EU Cookie Compliance Policy. For more information, see Cookie Policy Options. |
| disableFirstRun | Boolean | Disable the first run experience. |
| readAloudOptions | ReadAloudOptions | Options to configure Read Aloud. |
| translationOptions | TranslationOptions | Options to configure translation. |
| displayOptions | DisplayOptions | Options to configure text size, font, theme, and so on. |
| preferences | String | String returned from onPreferencesChanged representing the user's preferences in the Immersive Reader. For more information, see Settings Parameters and How-To Store User Preferences. |
| onPreferencesChanged | Function | Executes when the user's preferences have changed. For more information, see How-To Store User Preferences. |
| disableTranslation | Boolean | Disable the word and document translation experience. |
| disableGrammar | Boolean | Disable the Grammar experience. This option will also disable Syllables, Parts of Speech and Picture Dictionary, which depends on Parts of Speech. |
| disableLanguageDetection | Boolean | Disable Language Detection to ensure the Immersive Reader only uses the language that is explicitly specified on the Content/Chunk[]. This option should be used sparingly, primarily in situations where language detection isn't working, for instance, this issue is more likely to happen with short passages of fewer than 100 characters. You should be certain about the language you're sending, as text-to-speech won't have the correct voice. Syllables, Parts of Speech and Picture Dictionary won't work correctly if the language isn't correct. |
uiLang
Type: String
Required: false
Default value: User's browser language
timeout
Type: Number
Required: false
Default value: 15000
uiZIndex
Type: Number
Required: false
Default value: 1000
onExit
Type: Function
Required: false
Default value: null
preferences
Caution
IMPORTANT Do not attempt to programmatically change the values of the -preferences string sent to and from the Immersive Reader application as this may cause unexpected behavior resulting in a degraded user experience for your customers. Host applications should never assign a custom value to or manipulate the -preferences string. When using the -preferences string option, use only the exact value that was returned from the -onPreferencesChanged callback option.
Type: String
Required: false
Default value: null
onPreferencesChanged
Type: Function
Required: false
Default value: null
customDomain
Type: String
Required: false
Default value: null
ReadAloudOptions
type ReadAloudOptions = {
voice?: string;
speed?: number;
autoplay?: boolean;
};
ReadAloudOptions Parameters
| Name | Type | Description |
|---|---|---|
| voice | String | Voice, either "Female" or "Male". Not all languages support both genders. |
| speed | Number | Playback speed, must be between 0.5 and 2.5, inclusive. |
| autoPlay | Boolean | Automatically start Read Aloud when the Immersive Reader loads. |
voice
Type: String
Required: false
Default value: "Female" or "Male" (determined by language)
Values available: "Female", "Male"
speed
Type: Number
Required: false
Default value: 1
Values available: 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2, 2.25, 2.5
Note
Due to browser limitations, autoplay is not supported in Safari.
TranslationOptions
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
TranslationOptions Parameters
| Name | Type | Description |
|---|---|---|
| language | String | Sets the translation language, the value is in IETF BCP 47-language tag format, for example, fr-FR, es-MX, zh-Hans-CN. Required to automatically enable word or document translation. |
| autoEnableDocumentTranslation | Boolean | Automatically translate the entire document. |
| autoEnableWordTranslation | Boolean | Automatically enable word translation. |
language
Type: String
Required: true
Default value: null
Values available: For more information, see the Supported Languages section
ThemeOption
enum ThemeOption { Light, Dark }
DisplayOptions
type DisplayOptions = {
textSize?: number;
increaseSpacing?: boolean;
fontFamily?: string;
themeOption?: ThemeOption
};
DisplayOptions Parameters
| Name | Type | Description |
|---|---|---|
| textSize | Number | Sets the chosen text size. |
| increaseSpacing | Boolean | Sets whether text spacing is toggled on or off. |
| fontFamily | String | Sets the chosen font ("Calibri", "ComicSans", or "Sitka"). |
| themeOption | ThemeOption | Sets the chosen Theme of the reader ("Light", "Dark"). |
textSize
Type: Number
Required: false
Default value: 20, 36 or 42 (Determined by screen size)
Values available: 14, 20, 28, 36, 42, 48, 56, 64, 72, 84, 96
fontFamily
Type: String
Required: false
Default value: "Calibri"
Values available: "Calibri", "Sitka", "ComicSans"
CookiePolicy Options
enum CookiePolicy { Disable, Enable }
The settings listed below are for informational purposes only. The Immersive Reader stores its settings, or user preferences, in cookies. This cookiePolicy option disables the use of cookies by default to follow EU Cookie Compliance laws. If you want to re-enable cookies and restore the default functionality for Immersive Reader user preferences, your website or application will need proper consent from the user to enable cookies. Then, to re-enable cookies in the Immersive Reader, you must explicitly set the cookiePolicy option to CookiePolicy.Enable when launching the Immersive Reader. The table below describes what settings the Immersive Reader stores in its cookie when the cookiePolicy option is enabled.
Settings Parameters
| Setting | Type | Description |
|---|---|---|
| textSize | Number | Sets the chosen text size. |
| fontFamily | String | Sets the chosen font ("Calibri", "ComicSans", or "Sitka"). |
| textSpacing | Number | Sets whether text spacing is toggled on or off. |
| formattingEnabled | Boolean | Sets whether HTML formatting is toggled on or off. |
| theme | String | Sets the chosen theme (e.g "Light", "Dark"...). |
| syllabificationEnabled | Boolean | Sets whether syllabification toggled on or off. |
| nounHighlightingEnabled | Boolean | Sets whether noun-highlighting is toggled on or off. |
| nounHighlightingColor | String | Sets the chosen noun-highlighting color. |
| verbHighlightingEnabled | Boolean | Sets whether verb-highlighting is toggled on or off. |
| verbHighlightingColor | String | Sets the chosen verb-highlighting color. |
| adjectiveHighlightingEnabled | Boolean | Sets whether adjective-highlighting is toggled on or off. |
| adjectiveHighlightingColor | String | Sets the chosen adjective-highlighting color. |
| adverbHighlightingEnabled | Boolean | Sets whether adverb-highlighting is toggled on or off. |
| adverbHighlightingColor | String | Sets the chosen adverb-highlighting color. |
| pictureDictionaryEnabled | Boolean | Sets whether Picture Dictionary is toggled on or off. |
| posLabelsEnabled | Boolean | Sets whether the superscript text label of each highlighted Part of Speech is toggled on or off. |
Supported Languages
The translation feature of Immersive Reader supports many languages. For more information, see Language Support.
HTML support
When formatting is enabled, the following content will be rendered as HTML in the Immersive Reader.
| HTML | Supported Content |
|---|---|
| Font Styles | Bold, Italic, Underline, Code, Strikethrough, Superscript, Subscript |
| Unordered Lists | Disc, Circle, Square |
| Ordered Lists | Decimal, Upper-Alpha, Lower-Alpha, Upper-Roman, Lower-Roman |
Unsupported tags will be rendered comparably. Images and tables are currently not supported.
Browser support
Use the most recent versions of the following browsers for the best experience with the Immersive Reader.
- Microsoft Edge
- Internet Explorer 11
- Google Chrome
- Mozilla Firefox
- Apple Safari
Next steps
Feedback
Submit and view feedback for