Edit

How to launch the Immersive Reader

  • Article

In the overview, you learned about what the Immersive Reader is and how it implements proven techniques to improve reading comprehension for language learners, emerging readers, and students with learning differences. This article demonstrates how to launch the Immersive Reader JavaScript, Python, Android, or iOS.

Prerequisites

  • Azure subscription - Create one for free
  • An Immersive Reader resource configured for Microsoft Entra authentication. Follow these instructions to get set up. You will need some of the values created here when configuring the environment properties. Save the output of your session into a text file for future reference.
  • Node.js and Yarn
  • An IDE such as Visual Studio Code

Create a Node.js web app with Express

Create a Node.js web app with the express-generator tool.

npm install express-generator -g
express --view=pug myapp
cd myapp

Install yarn dependencies, and add dependencies request and dotenv, which will be used later in the tutorial.

yarn
yarn add request
yarn add dotenv

Acquire a Microsoft Entra authentication token

Next, write a backend API to retrieve a Microsoft Entra authentication token.

You need some values from the Microsoft Entra auth configuration prerequisite step above for this part. Refer back to the text file you saved of that session.

TenantId     => Azure subscription TenantId
ClientId     => Azure AD ApplicationId
ClientSecret => Azure AD Application Service Principal password
Subdomain    => Immersive Reader resource subdomain (resource 'Name' if the resource was created in the Azure portal, or 'CustomSubDomain' option if the resource was created with Azure CLI PowerShell. Check the Azure portal for the subdomain on the Endpoint in the resource Overview page, for example, 'https://[SUBDOMAIN].cognitiveservices.azure.com/')

Once you have these values, create a new file called .env, and paste the following code into it, supplying your custom property values from above. Do not include quotation marks or the "{" and "}" characters.

TENANT_ID={YOUR_TENANT_ID}
CLIENT_ID={YOUR_CLIENT_ID}
CLIENT_SECRET={YOUR_CLIENT_SECRET}
SUBDOMAIN={YOUR_SUBDOMAIN}

Be sure not to commit this file into source control, as it contains secrets that should not be made public.

Next, open app.js and add the following to the top of the file. This loads the properties defined in the .env file as environment variables into Node.

require('dotenv').config();

Open the routes\index.js file and replace its content with the following code.

This code creates an API endpoint that acquires a Microsoft Entra authentication token using your service principal password. It also retrieves the subdomain. It then returns an object containing the token and subdomain.

var request = require('request');
var express = require('express');
var router = express.Router();

router.get('/getimmersivereaderlaunchparams', function(req, res) {
    request.post ({
                headers: {
                    'content-type': 'application/x-www-form-urlencoded'
                },
                url: `https://login.windows.net/${process.env.TENANT_ID}/oauth2/token`,
                form: {
                    grant_type: 'client_credentials',
                    client_id: process.env.CLIENT_ID,
                    client_secret: process.env.CLIENT_SECRET,
                    resource: 'https://cognitiveservices.azure.com/'
                }
        },
        function(err, resp, tokenResponse) {
                if (err) {
                    return res.status(500).send('CogSvcs IssueToken error');
                }

                const token = JSON.parse(tokenResponse).access_token;
                const subdomain = process.env.SUBDOMAIN;
                return res.send({token: token, subdomain: subdomain});
        }
  );
});

/* GET home page. */
router.get('/', function(req, res, next) {
  res.render('index', { title: 'Express' });
});

module.exports = router;

The getimmersivereaderlaunchparams API endpoint should be secured behind some form of authentication (for example, OAuth) to prevent unauthorized users from obtaining tokens to use against your Immersive Reader service and billing; that work is beyond the scope of this tutorial.

Launch the Immersive Reader with sample content

  1. Open views\layout.pug, and add the following code under the head tag, before the body tag. These script tags load the Immersive Reader SDK and jQuery.

    script(src='https://ircdname.azureedge.net/immersivereadersdk/immersive-reader-sdk.1.2.0.js')
script(src='https://code.jquery.com/jquery-3.3.1.min.js')

  2. Open views\index.pug, and replace its content with the following code. This code populates the page with some sample content, and adds a button that launches the Immersive Reader.

    extends layout

block content
      h2(id='title') Geography
      p(id='content') The study of Earth's landforms is called physical geography. Landforms can be mountains and valleys. They can also be glaciers, lakes or rivers.
      div(class='immersive-reader-button' data-button-style='iconAndText' data-locale='en-US' onclick='launchImmersiveReader()')
      script.

        function getImmersiveReaderLaunchParamsAsync() {
                return new Promise((resolve, reject) => {
                    $.ajax({
                            url: '/getimmersivereaderlaunchparams',
                            type: 'GET',
                            success: data => {
                                    resolve(data);
                            },
                            error: err => {
                                    console.log('Error in getting token and subdomain!', err);
                                    reject(err);
                            }
                    });
                });
        }

        async function launchImmersiveReader() {
                const content = {
                        title: document.getElementById('title').innerText,
                        chunks: [{
                                content: document.getElementById('content').innerText + '\n\n',
                                lang: 'en'
                        }]
                };

                const launchParams = await getImmersiveReaderLaunchParamsAsync();
                const token = launchParams.token;
                const subdomain = launchParams.subdomain;

                ImmersiveReader.launchAsync(token, subdomain, content);
        }

  3. Our web app is now ready. Start the app by running:

    npm start

  4. Open your browser and navigate to http://localhost:3000. You should see the above content on the page. Select the Immersive Reader button to launch the Immersive Reader with your content.

Specify the language of your content

The Immersive Reader has support for many different languages. You can specify the language of your content by following the steps below.

  1. Open views\index.pug and add the following code below the p(id=content) tag that you added in the previous step. This code adds some content Spanish content to your page.

    p(id='content-spanish') El estudio de las formas terrestres de la Tierra se llama geografía física. Los accidentes geográficos pueden ser montañas y valles. También pueden ser glaciares, lagos o ríos.

  2. In the JavaScript code, add the following above the call to ImmersiveReader.launchAsync. This code passes the Spanish content into the Immersive Reader.

    content.chunks.push({
  content: document.getElementById('content-spanish').innerText + '\n\n',
  lang: 'es'
});

  3. Navigate to http://localhost:3000 again. You should see the Spanish text on the page, and when you select Immersive Reader, it will show up in the Immersive Reader as well.

Specify the language of the Immersive Reader interface

By default, the language of the Immersive Reader interface matches the browser's language settings. You can also specify the language of the Immersive Reader interface with the following code.

  1. In views\index.pug, replace the call to ImmersiveReader.launchAsync(token, subdomain, content) with the code below.

    const options = {
    uiLang: 'fr',
}
ImmersiveReader.launchAsync(token, subdomain, content, options);

  2. Navigate to http://localhost:3000. When you launch the Immersive Reader, the interface will be shown in French.

Launch the Immersive Reader with math content

You can include math content in the Immersive Reader by using MathML.

  1. Modify views\index.pug to include the following code above the call to ImmersiveReader.launchAsync:

    const mathML = '<math xmlns="https://www.w3.org/1998/Math/MathML" display="block"> \
  <munderover> \
    <mo>∫</mo> \
    <mn>0</mn> \
    <mn>1</mn> \
  </munderover> \
  <mrow> \
    <msup> \
      <mi>x</mi> \
      <mn>2</mn> \
    </msup> \
    <mo>ⅆ</mo> \
    <mi>x</mi> \
  </mrow> \
</math>';

content.chunks.push({
  content: mathML,
  mimeType: 'application/mathml+xml'
});

  2. Navigate to http://localhost:3000. When you launch the Immersive Reader and scroll to the bottom, you'll see the math formula.

Next steps

Prerequisites

Configure authentication credentials

Create a new file called .env, and paste the following names and values into it. Supply the values given when you created your Immersive Reader resource.

TENANT_ID={YOUR_TENANT_ID}
CLIENT_ID={YOUR_CLIENT_ID}
CLIENT_SECRET={YOUR_CLIENT_SECRET}
SUBDOMAIN={YOUR_SUBDOMAIN}

Don't commit this file into source control because it contains secrets that shouldn't be made public.

Secure the getimmersivereadertoken API endpoint behind some form of authentication, for example, OAuth. Authentication prevents unauthorized users from obtaining tokens to use against your Immersive Reader service and billing. That work is beyond the scope of this tutorial.

Create a Python web app on Windows

Create a Python web app by using flask on Windows.

Install Git.

After Git is installed, open a command prompt and clone the Immersive Reader SDK Git repository to a folder on your computer.

git clone https://github.com/microsoft/immersive-reader-sdk.git

Install Python.

Select the Add Python to PATH check box.

Python Windows Install dialog step 1

Add Optional Features by selecting check boxes, and then select Next.

Python Windows Install dialog step 2

Select Custom installation, and set the installation path as your root folder, for example, C:\Python37-32\. Then select Install.

Python Windows Install dialog step 3

After the Python installation is finished, open a command prompt and use cd to go to the Python Scripts folder.

cd C:\Python37-32\Scripts

Install Flask.

pip install flask

Install Jinja2. It's a full-featured template engine for Python.

pip install jinja2

Install virtualenv. This tool creates isolated Python environments.

pip install virtualenv

Install virtualenvwrapper-win. The idea behind virtualenvwrapper is to ease usage of virtualenv.

pip install virtualenvwrapper-win

Install the requests module. Requests is an Apache2 Licensed HTTP library, written in Python.

pip install requests

Install the python-dotenv module. This module reads the key-value pair from the .env file and adds them to the environment variable.

pip install python-dotenv

Make a virtual environment.

mkvirtualenv advanced-python

Use cd to go to the sample project root folder.

cd C:\immersive-reader-sdk\js\samples\advanced-python

Connect the sample project with the environment. This action maps the newly created virtual environment to the sample project root folder.

setprojectdir .

Activate the virtual environment.

activate

The project should now be active, and you'll see something like (advanced-python) C:\immersive-reader-sdk\js\samples\advanced-python> in the command prompt.

Deactivate the environment.

deactivate

The (advanced-python) prefix should be gone because the environment is deactivated.

To reactivate the environment, run workon advanced-python from the sample project root folder.

workon advanced-python

Start the Immersive Reader with sample content

When the environment is active, run the sample project by entering flask run from the sample project root folder.

flask run

Open your browser, and go to http://localhost:5000.

Create a Python web app on OSX

Create a Python web app by using flask on OSX.

Install Git.

After Git is installed, open Terminal and clone the Immersive Reader SDK Git repository to a folder on your computer.

git clone https://github.com/microsoft/immersive-reader-sdk.git

Install Python.

The Python root folder, for example, Python37-32, should now be in the Applications folder.

After the Python installation is finished, open Terminal and use cd to go to the Python Scripts folder.

cd immersive-reader-sdk/js/samples/advanced-python

Install pip.

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py

Run the following code to install pip for the currently signed-in user to avoid permissions issues.

python get-pip.py --user

sudo nano /etc/paths
  • Enter your password, when prompted.
  • Add the path of your pip installation to your PATH variable.
  • Go to the bottom of the file, and enter the path you want to add as the last item of the list, for example, PATH=$PATH:/usr/local/bin.
  • Select CTRL+X to quit.
  • Enter Y to save the modified buffer.
  • That's it! To test it, in a new Terminal window, enter echo $PATH.

Install Flask.

pip install flask --user

Install Jinja2. It's a full-featured template engine for Python.

pip install Jinja2 --user

Install virtualenv. This tool creates isolated Python environments.

pip install virtualenv --user

Install virtualenvwrapper. The idea behind virtualenvwrapper is to ease usage of virtualenv.

pip install virtualenvwrapper --user

Install the requests module. Requests is an Apache2 Licensed HTTP library, written in Python.

pip install requests --user

Install the python-dotenv module. This module reads the key-value pair from the .env file and adds them to the environment variable.

pip install python-dotenv --user

Choose a folder where you want to keep your virtual environments, and run this command:

mkdir ~/.virtualenvs

Use cd to go to the Immersive Reader SDK Python sample application folder.

cd immersive-reader-sdk/js/samples/advanced-python

Make a virtual environment.

mkvirtualenv -p /usr/local/bin/python3 advanced-python

Connect the sample project with the environment. This action maps the newly created virtual environment to the sample project root folder.

setprojectdir .

Activate the virtual environment.

activate

The project should now be active, and you'll see something like (advanced-python) /immersive-reader-sdk/js/samples/advanced-python> in the command prompt.

Deactivate the environment.

deactivate

The (advanced-python) prefix should be gone because the environment is deactivated.

To reactivate the environment, run workon advanced-python from the sample project root folder.

workon advanced-python

Start the Immersive Reader with sample content

When the environment is active, run the sample project by entering flask run from the sample project root folder.

flask run

Open your browser, and go to http://localhost:5000.

Next steps

Prerequisites

Configure authentication credentials

  1. Start Android Studio, and open the project from the immersive-reader-sdk/js/samples/quickstart-java-android directory (Java) or the immersive-reader-sdk/js/samples/quickstart-kotlin directory (Kotlin).

  2. Create a file named env inside the /assets folder. Add the following names and values, and supply values as appropriate. Don't commit this file into source control because it contains secrets that shouldn't be made public.

    TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET=<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>

Start the Immersive Reader with sample content

Choose a device emulator from the AVD Manager, and run the project.

Next steps

Prerequisites

  • Azure subscription - Create one for free
  • An Immersive Reader resource configured for Microsoft Entra authentication. Follow these instructions to get set up. You will need some of the values created here when configuring the environment properties. Save the output of your session into a text file for future reference.
  • macOS.
  • Git.
  • Immersive Reader SDK.
  • Xcode.

Configure authentication credentials

  1. Open Xcode, and open immersive-reader-sdk/js/samples/ios/quickstart-swift/quickstart-swift.xcodeproj.

  2. On the top menu, select Product > Scheme > Edit Scheme.

  3. In the Run view, select the Arguments tab.

  4. In the Environment Variables section, add the following names and values. Supply the values given when you created your Immersive Reader resource.

    TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>

Don't commit this change into source control because it contains secrets that shouldn't be made public.

Start the Immersive Reader with sample content

In Xcode, select Ctrl+R to run the project.

Next steps