Immersive Reader SDK Reference Guide

The Immersive Reader SDK is a JavaScript library that allows you to integrate the Immersive Reader into your web application.

Functions

The SDK exposes the functions:

launchAsync

Launches the Immersive Reader within an iframe in your web application.

launchAsync(token: string, subdomain: string, content: Content, options?: Options): Promise<HTMLDivElement>;

Parameters

Name Type Description
token string The Azure AD authentication token. See the Azure AD authentication how-to.
subdomain string The custom subdomain of your Immersive Reader resource in Azure. See the Azure AD authentication how-to.
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<HTMLDivElement>, which resolves when the Immersive Reader is loaded. The Promise resolves to a div element whose only child is an iframe element that contains the Immersive Reader page.

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 is clicked.

close(): void;

renderButtons

This function styles and updates the document's Immersive Reader button elements. If options.elements is provided, then this function will render buttons within options.elements. Otherwise, the buttons will be rendered within the document's elements which have the class immersive-reader-button.

This function is automatically called by the SDK when the window loads.

See Optional Attributes for more rendering options.

renderButtons(options?: RenderButtonsOptions): void;

Parameters

Name Type Description
options RenderButtonsOptions Options for configuring certain behaviors of the renderButtons function. Optional.

Types

Content

Contains the content to be shown in the Immersive Reader.

{
    title?: string;    // Title text shown at the top of the Immersive Reader (optional)
    chunks: Chunk[];   // Array of chunks
}

Chunk

A single chunk of data, which will be passed into the Content of the Immersive Reader.

{
    content: string;        // Plain text string
    lang?: string;          // Language of the text, e.g. en, es-ES (optional). Language will be detected automatically if not specified.
    mimeType?: string;      // MIME type of the content (optional). Currently 'text/plain', 'application/mathml+xml', and 'text/html' are supported. Defaults to 'text/plain' if not specified.
}

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.

HTML Support

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
Hyperlinks Coming Soon

Unsupported tags will be rendered comparably. Images and tables are currently not supported.

Options

Contains properties that configure certain behaviors of the Immersive Reader.

{
    uiLang?: string;           // Language of the UI, e.g. en, es-ES (optional). Defaults to browser language if not specified.
    timeout?: number;          // Duration (in milliseconds) before launchAsync fails with a timeout error (default is 15000 ms).
    uiZIndex?: number;         // Z-index of the iframe that will be created (default is 1000)
    useWebview?: boolean;      // Use a webview tag instead of an iframe, for compatibility with Chrome Apps (default is false).
    onExit?: () => any;        // 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).
    hideExitButton?: boolean;  // Whether or not to hide the Immersive Reader's exit button arrow (default is false). This should only be true if there is an alternative mechanism provided to exit the Immersive Reader (e.g a mobile toolbar's back arrow).
}

RenderButtonsOptions

Options for rendering the Immersive Reader buttons.

{
    elements: HTMLDivElement[];    // Elements to render the Immersive Reader buttons in
}

Error

Contains information about the error.

{
    code: string;    // One of a set of error codes
    message: string; // Human-readable representation of the error
}

Error codes

Code Description
BadArgument Supplied argument is invalid, see message for details.
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.

Launching the Immersive Reader

The SDK provides default styling for the button for launching the Immersive Reader. Use the immersive-reader-button class attribute to enable this styling.

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

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