Come avviare il Strumento di lettura immersiva

Articolo
07/20/2023

Nella panoramica si è appreso che cos'è lo strumento di lettura immersiva e come questo strumento implementa tecniche comprovate per migliorare la comprensione della lettura per studenti di lingue, lettori emergenti e studenti con differenze nell'apprendimento. Questo articolo illustra come avviare il Strumento di lettura immersiva JavaScript, Python, Android o iOS.

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
Una risorsa Strumento di lettura immersiva configurata per l'autenticazione di Microsoft Entra. Seguire queste istruzioni per configurare l'ambiente. Per la configurazione delle proprietà dell'ambiente, saranno necessari alcuni dei valori creati qui. Salvare l'output della sessione in un file di testo per riferimento futuro.
Node.js e Yarn
Un ambiente di sviluppo integrato, ad esempio Visual Studio Code

Creare un'app Web Node.js con Express

Creare un'app Web Node.js con lo strumento express-generator.

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

Installare le dipendenze di Yarn e aggiungere le dipendenze request e dotenv, che verranno usate più avanti nell'esercitazione.

yarn
yarn add request
yarn add dotenv

Acquisire un token di autenticazione Di Microsoft Entra

Scrivere quindi un'API back-end per recuperare un token di autenticazione di Microsoft Entra.

Per questa parte sono necessari alcuni valori del passaggio precedente dei prerequisiti di configurazione dell'autenticazione di Microsoft Entra. Fare riferimento al file di testo salvato della sessione.

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

Dopo aver recuperato i valori necessari, creare un nuovo file denominato .env e incollare il codice seguente al suo interno, specificando i valori delle proprietà personalizzate dal passaggio precedente. Non includere virgolette o i caratteri "{" e "}".

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

Fare attenzione a non eseguire il commit di questo file nel controllo del codice sorgente, poiché contiene segreti che non devono essere resi pubblici.

Aprire quindi app.js e aggiungere il codice seguente all'inizio del file. Verranno caricate le proprietà definite nel file .env come variabili di ambiente in Node.

require('dotenv').config();

Aprire il file routes\index.js e sostituirne il contenuto con il codice seguente.

Questo codice crea un endpoint API che acquisisce un token di autenticazione Microsoft Entra usando la password dell'entità servizio. e recupera anche il sottodominio, restituendo quindi un oggetto che contiene il token e il sottodominio.

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;

L'endpoint API getimmersivereaderlaunchparams deve essere protetto da qualche forma di autenticazione, ad esempio OAuth, per impedire agli utenti non autorizzati di ottenere token da usare per il servizio Strumento di lettura immersiva e la fatturazione, ma la relativa procedura esula dall'ambito di questa esercitazione.

Avviare lo strumento di lettura immersiva con contenuto di esempio

Aprire views\layout.pug e aggiungere il codice seguente sotto il tag head, prima del tag body. Questi tag script caricano Immersive Reader SDK e 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')

Aprire views\index.pug e sostituirne il contenuto con il codice seguente. Questo codice popola la pagina con contenuto di esempio e aggiunge un pulsante che avvia lo strumento di lettura immersiva.

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

L'app Web è ora pronta. Avviare l'app con il comando seguente:
```
npm start
```
Aprire il browser e passare a http://localhost:3000. Nella pagina verrà visualizzato il contenuto sopra riportato. Selezionare il pulsante Strumento di lettura immersiva per avviare il Strumento di lettura immersiva con il contenuto.

Specificare la lingua del contenuto

Lo strumento di lettura immersiva include il supporto per molte lingue diverse. È possibile specificare la lingua del contenuto seguendo la procedura seguente.

Aprire views\index.pug e inserire il codice seguente sotto il tag p(id=content) aggiunto nel passaggio precedente. Questo codice aggiunge del contenuto in spagnolo alla pagina.

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.

Nel codice JavaScript aggiungere il codice seguente prima della chiamata a ImmersiveReader.launchAsync. Questo codice passa il contenuto in spagnolo allo strumento di lettura immersiva.
```
content.chunks.push({
  content: document.getElementById('content-spanish').innerText + '\n\n',
  lang: 'es'
});
```
Passare di nuovo a http://localhost:3000. Verrà visualizzato il testo spagnolo nella pagina e, quando si seleziona Strumento di lettura immersiva, verrà visualizzato anche nel Strumento di lettura immersiva.

Specificare la lingua dell'interfaccia dello strumento di lettura immersiva

Per impostazione predefinita, la lingua dell'interfaccia dello strumento di lettura immersiva corrisponde a quella definita per il browser. È anche possibile specificare la lingua dell'interfaccia dello strumento di lettura immersiva con il codice seguente.

In views\index.pug sostituire la chiamata a ImmersiveReader.launchAsync(token, subdomain, content) con il codice seguente.
```
const options = {
    uiLang: 'fr',
}
ImmersiveReader.launchAsync(token, subdomain, content, options);
```
Accedere a http://localhost:3000. Quando si avvierà lo strumento di lettura immersiva, l'interfaccia verrà visualizzata in francese.

Avviare lo strumento di lettura immersiva con dati matematici

È possibile includere dati matematici nello strumento di lettura immersiva usando MathML.

Modificare views\index.pug in modo da includere il codice seguente prima della chiamata 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'
});

Accedere a http://localhost:3000. Quando si avvierà lo strumento di lettura immersiva, si noterà la formula matematica alla fine della schermata.

Passaggi successivi

Esplorare Immersive Reader SDK e le informazioni di riferimento su Immersive Reader SDK
Visualizzare gli esempi di codice su GitHub

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
Una risorsa Strumento di lettura immersiva configurata per l'autenticazione di Microsoft Entra. Seguire queste istruzioni per configurare l'ambiente. Per la configurazione delle proprietà dell'ambiente, saranno necessari alcuni dei valori creati qui. Salvare l'output della sessione in un file di testo per riferimento futuro.
Git.
Immersive Reader SDK.
Python e pip. A partire da Python 3,4, pip è incluso per impostazione predefinita con i programmi di installazione binari di Python.
Flask.
Jinja.
virtualenv e virtualenvwrapper-win per Windows o virtualenvwrapper per OSX.
Modulo requests.
Un ambiente di sviluppo integrato, ad esempio Visual Studio Code.

Configurare le credenziali di autenticazione

Creare un nuovo file denominato .enve incollare i nomi e i valori seguenti al suo interno. Specificare i valori forniti quando è stata creata la risorsa dello strumento di lettura immersiva.

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

Non eseguire il commit di questo file nel controllo del codice sorgente, perché contiene segreti che non devono essere resi pubblici.

Proteggere l'endpoint API getimmersivereadertoken tramite una forma di autenticazione, ad esempio OAuth. L'autenticazione impedisce agli utenti non autorizzati di ottenere i token da usare per il servizio di lettura immersiva e la fatturazione, tuttavia questa attività non rientra nell'ambito di questa esercitazione.

Creare un'app Web Python in Windows

Creare un'app Web Python usando flask in Windows.

Installare Git.

Dopo l'installazione di Git, aprire un prompt dei comandi e clonare il repository Git Immersive Reader SDK in una cartella del computer.

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

Installare Python.

Selezionare la casella di controllo Add Python to PATH (Aggiungi Python a PATH).

Python Windows Install dialog step 1

Aggiungere le Funzionalità facoltative selezionando le caselle di controllo, quindi fare clic su Avanti.

Python Windows Install dialog step 2

Scegliere Installazione personalizzata e impostare il percorso di installazione sul percorso della cartella radice, ad esempio C:\Python37-32\. Quindi selezionare Installa.

Python Windows Install dialog step 3

Al termine dell'installazione di Python, aprire un prompt dei comandi e digitare cd per passare alla cartella Scripts di Python.

cd C:\Python37-32\Scripts

Installare Flask.

pip install flask

Installare Jinja2, un motore di modelli completo per Python.

pip install jinja2

Installare virtualenv, uno strumento per creare ambienti Python isolati.

pip install virtualenv

Installare virtualenvwrapper-win. L'idea alla base di virtualenvwrapper è semplificare l'uso di virtualenv.

pip install virtualenvwrapper-win

Installare il modulo requests. Si tratta di una libreria HTTP concessa in licenza da Apache2 e scritta in Python.

pip install requests

Installare il modulo python-dotenv. Questo modulo legge la coppia chiave-valore dal file ENV e la aggiunge alla variabile di ambiente.

pip install python-dotenv

Creare un ambiente virtuale.

mkvirtualenv advanced-python

Digitare cd per passare alla cartella radice del progetto di esempio.

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

Connettere il progetto di esempio all'ambiente. Questa azione esegue il mapping dell'ambiente virtuale appena creato alla cartella radice del progetto di esempio.

setprojectdir .

Attivare l'ambiente virtuale.

activate

Il progetto è ora attivo e verrà visualizzato un testo simile a (advanced-python) C:\immersive-reader-sdk\js\samples\advanced-python> nel prompt dei comandi.

Disattivare l'ambiente.

deactivate

Il prefisso (advanced-python) non sarà più presente, in quanto l'ambiente è ora disattivato.

Per riattivare l'ambiente, eseguire workon advanced-python dalla cartella radice del progetto di esempio.

workon advanced-python

Avviare lo strumento di lettura immersiva con contenuto di esempio

Quando l'ambiente è attivo, eseguire il progetto di esempio immettendo flask run dalla relativa cartella radice.

flask run

Aprire il browser e passare a http://localhost:5000.

Creare un'app Web Python in OSX

Creare un'app Web Python usando flask in OSX.

Installare Git.

Al termine dell'installazione di Git, aprire il terminale e clonare il repository Git Immersive Reader SDK in una cartella del computer.

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

Installare Python.

La cartella radice di Python, ad esempio Python37-32, sarà ora inclusa nella cartella Applicazioni.

Al termine dell'installazione di Python, aprire il terminale e digitare cd per passare alla cartella Scripts di Python.

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

Installare pip.

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

Eseguire quindi il comando seguente per installare pip per l'utente attualmente connesso in modo da evitare problemi relativi alle autorizzazioni.

python get-pip.py --user

sudo nano /etc/paths

Immettere la password quando richiesto.
Aggiungere il percorso dell'installazione di pip alla variabile PATH.
Passare alla parte inferiore del file e immettere il percorso che si vuole aggiungere come ultimo elemento dell'elenco, ad esempio PATH=$PATH:/usr/local/bin.
Selezionare CTRL+X per uscire.
Immettere Y per salvare il buffer modificato.
Ecco fatto! Per testare questi passaggi, in una nuova finestra del terminale digitare echo $PATH.

Installare Flask.

pip install flask --user

Installare Jinja2, un motore di modelli completo per Python.

pip install Jinja2 --user

Installare virtualenv, uno strumento per creare ambienti Python isolati.

pip install virtualenv --user

Installare virtualenvwrapper. L'idea alla base di virtualenvwrapper è semplificare l'uso di virtualenv.

pip install virtualenvwrapper --user

Installare il modulo requests. Si tratta di una libreria HTTP concessa in licenza da Apache2 e scritta in Python.

pip install requests --user

Installare il modulo python-dotenv. Questo modulo legge la coppia chiave-valore dal file ENV e la aggiunge alla variabile di ambiente.

pip install python-dotenv --user

Scegliere una cartella in cui conservare gli ambienti virtuali ed eseguire questo comando:

mkdir ~/.virtualenvs

Digitare cd per passare alla cartella dell'applicazione di esempio Python in Immersive Reader SDK.

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

Creare un ambiente virtuale.

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

Connettere il progetto di esempio all'ambiente. Questa azione esegue il mapping dell'ambiente virtuale appena creato alla cartella radice del progetto di esempio.

setprojectdir .

Attivare l'ambiente virtuale.

activate

Il progetto è ora attivo e verrà visualizzato un testo simile a (advanced-python) /immersive-reader-sdk/js/samples/advanced-python> nel prompt dei comandi.

Disattivare l'ambiente.

deactivate

Il prefisso (advanced-python) non sarà più presente, in quanto l'ambiente è ora disattivato.

Per riattivare l'ambiente, eseguire workon advanced-python dalla cartella radice del progetto di esempio.

workon advanced-python

Avviare lo strumento di lettura immersiva con contenuto di esempio

Quando l'ambiente è attivo, eseguire il progetto di esempio immettendo flask run dalla relativa cartella radice.

flask run

Aprire il browser e passare a http://localhost:5000.

Passaggi successivi

Esplorare Immersive Reader SDK e le informazioni di riferimento su Immersive Reader SDK.
Visualizzare gli esempi di codice in GitHub.

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
Una risorsa Strumento di lettura immersiva configurata per l'autenticazione di Microsoft Entra. Seguire queste istruzioni per configurare l'ambiente. Per la configurazione delle proprietà dell'ambiente, saranno necessari alcuni dei valori creati qui. Salvare l'output della sessione in un file di testo per riferimento futuro.
Git.
Immersive Reader SDK.
Android Studio.

Configurare le credenziali di autenticazione

Avviare Android Studio e aprire il progetto dalla directory immersive-reader-sdk/js/samples/quickstart-java-android (Java) o dalla directory immersive-reader-sdk/js/samples/quickstart-kotlin (Kotlin).
Creare un file denominato env all'interno della cartella /assets. Aggiungere i nomi e i valori seguenti e specificare i valori appropriati. Non eseguire il commit di questo file nel controllo del codice sorgente, perché contiene segreti che non devono essere resi pubblici.
```
TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET=<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>
```

Avviare lo strumento di lettura immersiva con contenuto di esempio

Scegliere un emulatore di dispositivo da AVD Manager ed eseguire il progetto.

Passaggi successivi

Esplorare Immersive Reader SDK e le informazioni di riferimento su Immersive Reader SDK.
Visualizzare gli esempi di codice in GitHub.

Prerequisiti

Sottoscrizione di Azure: creare un account gratuito
Una risorsa Strumento di lettura immersiva configurata per l'autenticazione di Microsoft Entra. Seguire queste istruzioni per configurare l'ambiente. Per la configurazione delle proprietà dell'ambiente, saranno necessari alcuni dei valori creati qui. Salvare l'output della sessione in un file di testo per riferimento futuro.
macOS.
Git.
Immersive Reader SDK.
Xcode.

Configurare le credenziali di autenticazione

In Xcode aprire il progetto immersive-reader-sdk/js/samples/ios/quickstart-swift/quickstart-swift.xcodeproj.
Nel menu in alto selezionare Prodotto>Schema>Modifica schema.
Nella visualizzazione Esegui selezionare la scheda Argomenti.
Nella sezione Variabili di ambiente aggiungere i nomi e i valori seguenti. Specificare i valori forniti quando è stata creata la risorsa dello strumento di lettura immersiva.
```
TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>
```

Non eseguire il commit di questa modifica nel controllo del codice sorgente, perché contiene segreti che non devono essere resi pubblici.

Avviare lo strumento di lettura immersiva con contenuto di esempio

In Xcode premere CTRL+R per eseguire il progetto.

Passaggi successivi

Esplorare Immersive Reader SDK e le informazioni di riferimento su Immersive Reader SDK.
Visualizzare gli esempi di codice in GitHub.

Come avviare il Strumento di lettura immersiva

Prerequisiti

Creare un'app Web Node.js con Express

Acquisire un token di autenticazione Di Microsoft Entra

Avviare lo strumento di lettura immersiva con contenuto di esempio

Specificare la lingua del contenuto

Specificare la lingua dell'interfaccia dello strumento di lettura immersiva

Avviare lo strumento di lettura immersiva con dati matematici

Passaggi successivi

Prerequisiti

Configurare le credenziali di autenticazione

Creare un'app Web Python in Windows

Avviare lo strumento di lettura immersiva con contenuto di esempio

Creare un'app Web Python in OSX

Avviare lo strumento di lettura immersiva con contenuto di esempio

Passaggi successivi

Prerequisiti

Configurare le credenziali di autenticazione

Avviare lo strumento di lettura immersiva con contenuto di esempio

Passaggi successivi

Prerequisiti

Configurare le credenziali di autenticazione

Avviare lo strumento di lettura immersiva con contenuto di esempio

Passaggi successivi

Risorse aggiuntive