Inicio del Lector inmersivo

  • Artículo
  • 12 minutos para leer

En la introducción, se indica lo que es el Lector inmersivo y cómo implementa técnicas demostradas para mejorar la comprensión lectora de nuevos lectores, alumnos de idiomas y alumnos con diferencias de aprendizaje. En este artículo se muestra cómo iniciar el Lector inmersivo en JavaScript, Python, Android o iOS.

Prerrequisitos

  • Una suscripción a Azure: cree una cuenta gratuita
  • Un recurso del Lector inmersivo configurado para la autenticación de Azure Active Directory. Siga estas instrucciones para realizar la configuración. Necesitará algunos de los valores que se crean aquí cuando configure las propiedades del entorno. Guarde la salida de la sesión en un archivo de texto para futuras referencias.
  • Node.js y Yarn
  • Un IDE como Visual Studio Code

Crear una aplicación web de Node.js con Express

Cree una aplicación web de Node.js con la herramienta express-generator.

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

Instale las dependencias de yarn y agregue las dependencias request y dotenv, que se utilizarán más adelante en el tutorial.

yarn
yarn add request
yarn add dotenv

Adquisición de un token de autenticación de Azure AD

Después, escriba una API de back-end para recuperar un token de autenticación de Azure AD.

Necesita algunos valores del paso del requisito previo de configuración de la autenticación de Azure AD para esta parte. Vuelva a consultar el archivo de texto que ha guardado de esa sesión.

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/')

Una vez que tenga estos valores, cree un nuevo archivo llamado .env y pegue el siguiente código en él, proporcionando sus valores de propiedad personalizados desde arriba. No incluya comillas ni los caracteres "{" y "}".

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

Asegúrese de no confirmar este archivo en el control de código fuente, ya que contiene secretos que no deben hacerse públicos.

Después, abra el archivo app.js y agregue lo siente en la parte superior. Esto carga las propiedades definidas en el archivo .env como variables de entorno en el nodo.

require('dotenv').config();

Abra el archivo routes\index.js y reemplace su contenido por el código siguiente.

Este código crea un punto de conexión de la API que adquiere un token de autenticación de Azure AD mediante la contraseña de la entidad de servicio. También recupera el subdominio. Luego, devuelve un objeto que contiene el token y el subdominio.

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;

El punto de conexión de la API getimmersivereaderlaunchparams debe estar protegido mediante algún tipo de autenticación (por ejemplo, OAuth) para evitar que usuarios no autorizados obtengan tokens para utilizarlos contra el servicio Lector inmersivo y su facturación; este trabajo está fuera del ámbito de este tutorial.

Iniciar el Lector inmersivo con contenido de muestra

  1. Abra views\layout.pug y agregue el siguiente código bajo la etiqueta head, antes de la etiqueta body. Estas etiquetas script cargan el DSK de Lector inmersivo y jQuery.

    script(src='https://contentstorage.onenote.office.net/onenoteltir/immersivereadersdk/immersive-reader-sdk.0.0.2.js')
script(src='https://code.jquery.com/jquery-3.3.1.min.js')

  2. Abra el archivo views\index.pug y reemplace el contenido por el código siguiente. Este código rellena la página con algún contenido de muestra y agrega un botón que inicia el Lector inmersivo.

    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. Nuestra aplicación web ya está lista. Inicie la aplicación; para ello, ejecute:

    npm start

  4. Abra el explorador web y vaya a http://localhost:3000 . Debería ver el contenido anterior en la página. Haga clic en el botón Lector inmersivo para iniciar el Lector inmersivo con su contenido.

Especificar el idioma del contenido

El Lector inmersivo es compatible con numerosos lenguajes diferentes. Para especificar el idioma del contenido, puede seguir estos pasos.

  1. Abra views\index.pug y agregue el código siguiente bajo la etiqueta p(id=content) que agregó en el paso anterior. Este código agrega contenido en español a la página.

    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. En el código JavaScript, agregue lo siguiente encima de la llamada a ImmersiveReader.launchAsync. Este código pasa el contenido en español al Lector inmersivo.

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

  3. Vaya de nuevo a http://localhost:3000 . Debería ver el texto en español en la página y, al hacer clic en Lector inmersivo, se mostrará en el Lector inmersivo también.

Especificar el idioma de la interfaz del Lector inmersivo

De forma predeterminada, el idioma de la interfaz del Lector inmersivo coincide con la configuración de idioma del explorador. También puede especificar el idioma de la interfaz del Lector inmersivo con el código siguiente.

  1. En views\index.pug, reemplace la llamada a ImmersiveReader.launchAsync(token, subdomain, content) por el código siguiente.

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

  2. Vaya a http://localhost:3000. Al iniciar el Lector inmersivo, se mostrará la interfaz en francés.

Iniciar el Lector inmersivo con contenido de matemáticas

Puede incluir contenido de matemáticas en el Lector inmersivo mediante MathML.

  1. Modifique views\index.pug para incluir el código siguiente encima de la llamada a 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. Vaya a http://localhost:3000. Al iniciar el Lector inmersivo y desplazarse hasta la parte inferior, verá la fórmula matemática.

Pasos siguientes

Prerrequisitos

Configuración de las credenciales de autenticación

Cree un archivo denominado .env y pegue en él los siguientes nombres y valores. Proporcione los valores especificados al crear el recurso del Lector inmersivo.

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

No confirme este archivo en el control de código fuente, ya que contiene secretos que no deben hacerse públicos.

Proteja el punto de conexión de la API getimmersivereadertoken mediante algún tipo de autenticación, por ejemplo, OAuth. La autenticación impide que usuarios no autorizados obtengan tokens para usarlos en el servicio de Lector inmersivo y su facturación. Este escenario queda fuera del alcance de este tutorial.

Creación de una aplicación web de Python en Windows

Cree una aplicación web de Python con flask en Windows.

Instale Git.

Una vez instalado Git, abra un símbolo del sistema y clone el repositorio Git del SDK del Lector inmersivo en una carpeta del equipo.

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

Instale Python.

Seleccione la casilla Add Python to PATH (Agregar Python a PATH).

Cuadro de diálogo de instalación de Python en Windows, paso 1

Seleccione las casillas correspondientes para agregar Características opcionales y seleccione Siguiente.

Cuadro de diálogo de instalación de Python en Windows, paso 2

Seleccione Custom installation (Instalación personalizada) y establezca la ruta de acceso de instalación como carpeta raíz (por ejemplo, C:\Python37-32\). A continuación, seleccione Instalar.

Cuadro de diálogo de instalación de Python en Windows, paso 3

Una vez finalizada la instalación de Python, abra un símbolo del sistema y use cd para ir a la carpeta Scripts de Python.

cd C:\Python37-32\Scripts

Instale Flask.

pip install flask

Instale Jinja2. Se trata de un motor de plantillas completo para Python.

pip install jinja2

Instale virtualenv. Se trata de una herramienta para crear entornos de Python aislados.

pip install virtualenv

Instale virtualenvwrapper-win. Con virtualenvwrapper se quiere facilitar el uso de virtualenv.

pip install virtualenvwrapper-win

Instale el módulo requests. Requests es una biblioteca HTTP con licencia de Apache2, escrita en Python.

pip install requests

Instale el módulo python-dotenv. Este módulo lee el par clave-valor del archivo .env y lo agrega a la variable de entorno.

pip install python-dotenv

Cree un entorno virtual.

mkvirtualenv advanced-python

Use cd para ir a la carpeta raíz del proyecto de ejemplo.

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

Conecte el proyecto de ejemplo con el entorno. De este modo se asigna el entorno virtual recién creado a la carpeta raíz del proyecto de ejemplo.

setprojectdir .

Active el entorno virtual.

activate

Ahora el proyecto debe estar activo; verá algo parecido a (advanced-python) C:\immersive-reader-sdk\js\samples\advanced-python> en el símbolo del sistema.

Desactive el entorno.

deactivate

El prefijo (advanced-python) habrá desaparecido, ya que el entorno se ha desactivado.

Para volver a activar el entorno, ejecute workon advanced-python desde la carpeta raíz del proyecto de ejemplo.

workon advanced-python

Inicio del Lector inmersivo con contenido de ejemplo

Cuando el entorno esté activo, ejecute el proyecto de ejemplo escribiendo flask run en la carpeta raíz del proyecto de ejemplo.

flask run

Abra el explorador web y vaya a http://localhost:5000.

Creación de una aplicación web de Python en OSX

Cree una aplicación web de Python con flask en OSX.

Instale Git.

Una vez instalado Git, abra el terminal y clone el repositorio Git del SDK del Lector inmersivo en una carpeta del equipo.

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

Instale Python.

La carpeta raíz de Python, Python37-32, por ejemplo, debe estar ahora en la carpeta de aplicaciones.

Una vez finalizada la instalación de Python, abra el terminal y use cd para ir a la carpeta Scripts de Python.

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

Instale PIP.

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

Ejecute el código siguiente para instalar pip para el usuario que tiene actualmente iniciada la sesión para evitar problemas de permisos.

python get-pip.py --user

sudo nano /etc/paths
  • Escriba la contraseña cuando se le solicite.
  • Agregue la ruta de acceso de la instalación de pip a la variable PATH.
  • Vaya al final del archivo y escriba la ruta de acceso que desea agregar como último elemento de la lista, por ejemplo, PATH=$PATH:/usr/local/bin.
  • Seleccione CTRL + X para salir.
  • Escriba Y para guardar el búfer modificado.
  • Eso es todo. Para probarlo, escriba echo $PATH en una nueva ventana del terminal.

Instale Flask.

pip install flask --user

Instale Jinja2. Se trata de un motor de plantillas completo para Python.

pip install Jinja2 --user

Instale virtualenv. Se trata de una herramienta para crear entornos de Python aislados.

pip install virtualenv --user

Instale virtualenvwrapper. Con virtualenvwrapper se quiere facilitar el uso de virtualenv.

pip install virtualenvwrapper --user

Instale el módulo requests. Requests es una biblioteca HTTP con licencia de Apache2, escrita en Python.

pip install requests --user

Instale el módulo python-dotenv. Este módulo lee el par clave-valor del archivo .env y lo agrega a la variable de entorno.

pip install python-dotenv --user

Elija la carpeta donde desea conservar los entornos virtuales y ejecute este comando:

mkdir ~/.virtualenvs

Use cd para ir a la carpeta de aplicación de ejemplo de Python del SDK del Lector inmersivo.

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

Cree un entorno virtual.

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

Conecte el proyecto de ejemplo con el entorno. De este modo se asigna el entorno virtual recién creado a la carpeta raíz del proyecto de ejemplo.

setprojectdir .

Active el entorno virtual.

activate

Ahora el proyecto debe estar activo; verá algo parecido a (advanced-python) /immersive-reader-sdk/js/samples/advanced-python> en el símbolo del sistema.

Desactive el entorno.

deactivate

El prefijo (advanced-python) habrá desaparecido, ya que el entorno se ha desactivado.

Para volver a activar el entorno, ejecute workon advanced-python desde la carpeta raíz del proyecto de ejemplo.

workon advanced-python

Inicio del Lector inmersivo con contenido de ejemplo

Cuando el entorno esté activo, ejecute el proyecto de ejemplo escribiendo flask run en la carpeta raíz del proyecto de ejemplo.

flask run

Abra el explorador web y vaya a http://localhost:5000.

Pasos siguientes

Prerrequisitos

  • Una suscripción a Azure: cree una cuenta gratuita
  • Un recurso del Lector inmersivo configurado para la autenticación de Azure Active Directory. Siga estas instrucciones para realizar la configuración. Necesitará algunos de los valores que se crean aquí cuando configure las propiedades del entorno. Guarde la salida de la sesión en un archivo de texto para futuras referencias.
  • Git.
  • SDK del Lector inmersivo.
  • Android Studio.

Configuración de las credenciales de autenticación

  1. Inicie Android Studio y abra el proyecto desde el directorio immersive-reader-sdk/js/samples/quickstart-java-android (Java) o immersive-reader-sdk/js/samples/quickstart-kotlin (Kotlin).

  2. Cree un archivo denominado env dentro de la carpeta /assets. Agregue los siguientes nombres y valores y proporcione los valores según corresponda. No confirme este archivo en el control de código fuente, ya que contiene secretos que no deben hacerse públicos.

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

Inicio del Lector inmersivo con contenido de ejemplo

Elija un emulador de dispositivos de AVD Manager y ejecute el proyecto.

Pasos siguientes

Prerrequisitos

  • Una suscripción a Azure: cree una cuenta gratuita
  • Un recurso del Lector inmersivo configurado para la autenticación de Azure Active Directory. Siga estas instrucciones para realizar la configuración. Necesitará algunos de los valores que se crean aquí cuando configure las propiedades del entorno. Guarde la salida de la sesión en un archivo de texto para futuras referencias.
  • macOS.
  • Git.
  • SDK del Lector inmersivo.
  • Xcode.

Configuración de las credenciales de autenticación

  1. Abra Xcode y abra immersive-reader-sdk/js/samples/ios/quickstart-swift/quickstart-swift.xcodeproj.

  2. En el menú superior, seleccione Product > Scheme > Edit Scheme (Producto > Esquema > Editar esquema).

  3. En la vista Run (Ejecutar), seleccione la pestaña Arguments (Argumentos).

  4. En la sección Environment Variables (Variables de entorno), agregue los siguientes nombres y valores. Proporcione los valores especificados al crear el recurso del Lector inmersivo.

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

No confirme este cambio en el control de código fuente, ya que contiene secretos que no deben hacerse públicos.

Inicio del Lector inmersivo con contenido de ejemplo

En Xcode, seleccione Ctrl+R para ejecutar el proyecto.

Pasos siguientes