Så här startar du Avancerad läsare

  • Artikel
  • 10 minuter för att läsa

I översiktenhar du lärt dig om vad Avancerad läsare är och hur den implementerar beprövade tekniker för att förbättra läsförståelse för språkinlärare, nya läsare och studenter med inlärningsskillnader. Den här artikeln visar hur du startar Avancerad läsare JavaScript, Python, Android eller iOS.

Förutsättningar

  • Azure-prenumeration – Skapa en utan kostnad
  • En Avancerad läsare resurs konfigurerad för Azure Active Directory autentisering. Följ de här anvisningarna för att komma igång. Du behöver några av de värden som skapas här när du konfigurerar miljöegenskaperna. Spara sessionens utdata i en textfil för framtida bruk.
  • Node.js och Yarn
  • En IDE som Visual Studio Code

Skapa en Node.js-webbapp med Express

Skapa en Node.js-webbapp med express-generator verktyget .

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

Installera Yarn-beroenden och lägg till beroenden request och , som ska användas senare i dotenv självstudien.

yarn
yarn add request
yarn add dotenv

Hämta en Azure AD-autentiseringstoken

Skriv sedan ett server-API för att hämta en Azure AD-autentiseringstoken.

Du behöver vissa värden från förhandssteget för Azure AD-autentiseringskonfiguration ovan för den här delen. Gå tillbaka till textfilen som du sparade i sessionen.

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

När du har dessa värden skapar du en ny fil med namnet .env och klistrar in följande kod i den och anger dina anpassade egenskapsvärden ovan. Ta inte med citattecken eller "{" och "}"-tecken.

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

Se till att du inte genomför den här filen i källkontrollen eftersom den innehåller hemligheter som inte ska göras offentliga.

Öppna sedan app.js och lägg till följande överst i filen. Då läses egenskaperna som definierats i .env-filen in som miljövariabler till Node.

require('dotenv').config();

Öppna filen routes\index.js och ersätt dess innehåll med följande kod.

Den här koden skapar en API-slutpunkt som hämtar en Azure AD-autentiseringstoken med hjälp av ditt lösenord för tjänstens huvudnamn. Den hämtar även underdomänen. Den returnerar sedan ett objekt som innehåller token och underdomänen.

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;

API-slutpunkten getivereaderlaunchparams bör skyddas bakom någon form av autentisering (till exempel OAuth) för att förhindra att obehöriga användare hämtar token som ska användas mot din Avancerad läsare-tjänst och fakturering; att arbetet ligger utanför omfånget för den här självstudien.

Starta Avancerad läsare med exempelinnehåll

  1. Öppna views\layout.pug och lägg till följande kod under head taggen före body taggen . De script här taggarna läser Avancerad läsare SDK och 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. Öppna views\index.pug och ersätt dess innehåll med följande kod. Den här koden fyller sidan med exempelinnehåll och lägger till en knapp som startar Avancerad läsare.

    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. Vår webbapp är nu klar. Starta appen genom att köra:

    npm start

  4. Öppna webbläsaren och gå till http://localhost:3000 . Du bör se ovanstående innehåll på sidan. Klicka på Avancerad läsare för att starta Avancerad läsare med ditt innehåll.

Ange språket för ditt innehåll

Den Avancerad läsare har stöd för många olika språk. Du kan ange språket för ditt innehåll genom att följa stegen nedan.

  1. Öppna views\index.pug och lägg till följande kod under p(id=content) taggen som du lade till i föregående steg. Den här koden lägger till innehåll på sidan med spanska innehåll.

    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. I JavaScript-koden lägger du till följande ovanför anropet till ImmersiveReader.launchAsync . Den här koden skickar det spanska innehållet till Avancerad läsare.

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

  3. Gå till http://localhost:3000 igen. Du bör se den spanska texten på sidan och när du klickar på Avancerad läsare visas den i Avancerad läsare också.

Ange språket för Avancerad läsare gränssnittet

Som standard matchar språket i Avancerad läsare-gränssnittet webbläsarens språkinställningar. Du kan också ange språket i Avancerad läsare gränssnittet med följande kod.

  1. I views\index.pug ersätter du ImmersiveReader.launchAsync(token, subdomain, content) anropet till med koden nedan.

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

  2. Gå till http://localhost:3000 . När du startar Avancerad läsare visas gränssnittet på franska.

Starta Avancerad läsare med matematikinnehåll

Du kan inkludera matematikinnehåll i Avancerad läsare hjälp av MathML.

  1. Ändra views\index.pug så att den inkluderar följande kod ovanför anropet till 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. Gå till http://localhost:3000 . När du startar Avancerad läsare och bläddrar längst ned ser du matematikformeln.

Nästa steg

Förutsättningar

Konfigurera autentiseringsuppgifter

Skapa en ny fil med namnet .env och klistra in följande namn och värden i den. Ange de värden som du fick när du skapade Avancerad läsare resurs.

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

Genomför inte den här filen i källkontrollen eftersom den innehåller hemligheter som inte bör göras offentliga.

Skydda api-slutpunkten get autentiseradreadertoken bakom någon form av autentisering, till exempel OAuth. Autentisering hindrar obehöriga användare från att hämta token som ska användas mot din Avancerad läsare och fakturering. Det arbetet ligger utanför omfånget för den här självstudien.

Skapa en Python-webbapp på Windows

Skapa en Python-webbapp med hjälp flask av på Windows.

Installera Git.

När Git har installerats öppnar du en kommandotolk och klonar Avancerad läsare SDK Git-lagringsplatsen till en mapp på datorn.

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

Installera Python.

Markera kryssrutan Lägg till Python i PATH.

Python Windows installera dialogruta steg 1

Lägg till valfria funktioner genom att markera kryssrutorna och välj sedan Nästa.

Python Windows installera dialogruta steg 2

Välj Anpassad installation och ange installationssökvägen som rotmapp, till exempel C:\Python37-32\ . Välj sedan Installera.

Python Windows installera dialogruta steg 3

När Python-installationen är klar öppnar du en kommandotolk och använder cd för att gå till mappen Python-skript.

cd C:\Python37-32\Scripts

Installera Flask.

pip install flask

Installera Jinja2. Det är en komplett mallmotor för Python.

pip install jinja2

Installera virtualenv. Det här verktyget skapar isolerade Python-miljöer.

pip install virtualenv

Installera virtualenvwrapper-win. Idén bakom virtualenvwrapper är att underlätta användningen av virtualenv.

pip install virtualenvwrapper-win

Installera modulen requests. Begäranden är ett Apache2-licensierat HTTP-bibliotek som skrivits i Python.

pip install requests

Installera modulen python-dotenv. Den här modulen läser nyckel/värde-paret från .env-filen och lägger till dem i miljövariabeln.

pip install python-dotenv

Skapa en virtuell miljö.

mkvirtualenv advanced-python

Använd cd för att gå till exempelprojektets rotmapp.

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

Anslut exempelprojektet med miljön. Den här åtgärden mappar den nyligen skapade virtuella miljön till exempelprojektets rotmapp.

setprojectdir .

Aktivera den virtuella miljön.

activate

Projektet bör nu vara aktivt och du ser något som liknar det (advanced-python) C:\immersive-reader-sdk\js\samples\advanced-python> i kommandotolken.

Inaktivera miljön.

deactivate

Prefixet (advanced-python) bör vara borta eftersom miljön är inaktiverad.

Om du vill återaktivera miljön kör du workon advanced-python från exempelprojektets rotmapp.

workon advanced-python

Starta Avancerad läsare med exempelinnehåll

När miljön är aktiv kör du exempelprojektet genom att ange från flask run exempelprojektets rotmapp.

flask run

Öppna webbläsaren och gå till http://localhost:5000 .

Skapa en Python-webbapp i OSX

Skapa en Python-webbapp med hjälp flask av i OSX.

Installera Git.

När Git har installerats öppnar du Terminal och klonar Avancerad läsare SDK Git-lagringsplatsen till en mapp på datorn.

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

Installera Python.

Python-rotmappen, till exempel Python37-32 , bör nu finnas i mappen Program.

När Python-installationen är klar öppnar du Terminal och använder cd för att gå till mappen Python-skript.

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

Installera pip.

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

Kör följande kod för att installera pip för den inloggade användaren för att undvika behörighetsproblem.

python get-pip.py --user

sudo nano /etc/paths
  • Ange ditt lösenord när du uppmanas att göra det.
  • Lägg till sökvägen till pip-installationen i path-variabeln.
  • Gå längst ned i filen och ange den sökväg som du vill lägga till som det sista objektet i listan, till exempel PATH=$PATH:/usr/local/bin .
  • Välj CTRL +X för att avsluta.
  • Ange Y för att spara den ändrade bufferten.
  • Klart! Testa det genom att ange i ett nytt echo $PATH terminalfönster.

Installera Flask.

pip install flask --user

Installera Jinja2. Det är en komplett mallmotor för Python.

pip install Jinja2 --user

Installera virtualenv. Det här verktyget skapar isolerade Python-miljöer.

pip install virtualenv --user

Installera virtualenvwrapper. Idén bakom virtualenvwrapper är att underlätta användningen av virtualenv.

pip install virtualenvwrapper --user

Installera modulen requests. Begäranden är ett Apache2-licensierat HTTP-bibliotek som skrivits i Python.

pip install requests --user

Installera modulen python-dotenv. Den här modulen läser nyckel/värde-paret från .env-filen och lägger till dem i miljövariabeln.

pip install python-dotenv --user

Välj en mapp där du vill behålla dina virtuella miljöer och kör det här kommandot:

mkdir ~/.virtualenvs

Använd cd för att gå till Avancerad läsare SDK Python-exempelprogrammappen.

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

Skapa en virtuell miljö.

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

Anslut exempelprojektet med miljön. Den här åtgärden mappar den nyligen skapade virtuella miljön till exempelprojektets rotmapp.

setprojectdir .

Aktivera den virtuella miljön.

activate

Projektet bör nu vara aktivt och du ser något som liknar det (advanced-python) /immersive-reader-sdk/js/samples/advanced-python> i kommandotolken.

Inaktivera miljön.

deactivate

Prefixet (advanced-python) bör vara borta eftersom miljön är inaktiverad.

Om du vill återaktivera miljön kör du workon advanced-python från exempelprojektets rotmapp.

workon advanced-python

Starta Avancerad läsare med exempelinnehåll

När miljön är aktiv kör du exempelprojektet genom att ange från flask run exempelprojektets rotmapp.

flask run

Öppna webbläsaren och gå till http://localhost:5000 .

Nästa steg

Förutsättningar

Konfigurera autentiseringsuppgifter

  1. Starta Android Studio och öppna projektet från katalogen immersive-reader-sdk/js/samples/quickstart-java-android (Java) eller katalogen immersive-reader-sdk/js/samples/quickstart-kotlin (Kotlin).

  2. Skapa en fil med namnet env i mappen /assets. Lägg till följande namn och värden och ange värden efter behov. Genomför inte den här filen i källkontrollen eftersom den innehåller hemligheter som inte bör göras offentliga.

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

Starta Avancerad läsare med exempelinnehåll

Välj en enhetsemulator från AVD Manager och kör projektet.

Nästa steg

Förutsättningar

Konfigurera autentiseringsuppgifter

  1. Öppna Xcode och öppna immersive-reader-sdk/js/samples/ios/quickstart-swift/quickstart-swift.xcodeproj.

  2. Välj Redigera schema för produktschema > på den översta > menyn.

  3. I vyn Kör väljer du fliken Argument.

  4. I avsnittet Miljövariabler lägger du till följande namn och värden. Ange de värden som du fick när du skapade Avancerad läsare resurs.

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

Genomför inte den här ändringen i källkontrollen eftersom den innehåller hemligheter som inte bör göras offentliga.

Starta Avancerad läsare med exempelinnehåll

I Xcode väljer du Ctrl+R för att köra projektet.

Nästa steg