Immersive Reader JavaScript SDK reference (v1.4)
The Immersive Reader SDK contains a JavaScript library that allows you to integrate the Immersive Reader into your application.
You can 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.4.0.js'></script>
npm install @microsoft/immersive-reader-sdk
yarn add @microsoft/immersive-reader-sdk
Functions
The SDK exposes these functions:
- ImmersiveReader.launchAsync(token, subdomain, content, options)
- ImmersiveReader.close()
- ImmersiveReader.renderButtons(options)
Function: launchAsync
ImmersiveReader.launchAsync(token, subdomain, content, options) 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>;
| Parameter | Type | Description |
|---|---|---|
| token | string | The Microsoft Entra authentication token. To learn more, see How to create an Immersive Reader resource. |
| subdomain | string | The custom subdomain of your Immersive Reader resource in Azure. |
| content | Content | An object that contains 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
If the Immersive Reader fails to load, the returned Promise is rejected with an Error object.
Function: close
ImmersiveReader.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;
Function: renderButtons
The ImmersiveReader.renderButtons(options) function isn't necessary if you use 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 are 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 following code snippet. Otherwise, the buttons are 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 launch button 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;
| Parameter | 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[];
}
| Parameter | Type | Description |
|---|---|---|
| elements | HTMLDivElement[] | Elements to render the Immersive Reader buttons in. |
Type: HTMLDivElement[]
Required: false
Launch button
The SDK provides default styling for the Immersive Reader launch button. 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>
Use the following optional 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 20 px. |
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;
}
| Parameter | 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;
}
| Parameter | Type | Description |
|---|---|---|
| code | String | One of a set of error codes. |
| message | String | Human-readable representation of the error. |
| Error 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[];
}
| Parameter | 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 is passed into the content of the Immersive Reader.
{
content: string;
lang?: string;
mimeType?: string;
}
| Parameter | 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 is 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. |
| application/mathml+xml | Mathematical Markup Language (MathML). |
| 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;
}
| Parameter | 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 shouldn't be necessary. |
| uiZIndex | Number | Z-index of the HTML iframe element that is 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 (for example, 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 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 also disables 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 don'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
Type: String
Required: false
Default value: null
Caution
Don't attempt to programmatically change the values of the -preferences string sent to and from the Immersive Reader application because this might cause unexpected behavior resulting in a degraded user experience. 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.
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;
};
| Parameter | 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. |
Note
Due to browser limitations, autoplay is not supported in Safari.
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
TranslationOptions
type TranslationOptions = {
language: string;
autoEnableDocumentTranslation?: boolean;
autoEnableWordTranslation?: boolean;
};
| Parameter | 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
};
| Parameter | 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 following settings 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 needs 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 following table describes what settings the Immersive Reader stores in its cookie when the cookiePolicy option is enabled.
| 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 (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 is 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 are 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
- Google Chrome
- Mozilla Firefox
- Apple Safari
Next step
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for