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>;

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;

renderButtons options

Options for rendering the Immersive Reader buttons.

{
    elements: HTMLDivElement[];
}

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.

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;
}

Error

Contains information about an error.

{
    code: string;
    message: string;
}

Types

Content

Contains the content to be shown in the Immersive Reader.

{
    title?: string;
    chunks: Chunk[];
}

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;
}

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

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;
}

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

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;
};

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;
};

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
};

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.

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.

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