Breyta

Deila með


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:

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