Como lançar o Leitura Avançada

Na visão geral, aprendeu sobre o que é o Leitura Avançada e como implementa técnicas comprovadas para melhorar a compreensão da leitura para os alunos de línguas, leitores emergentes e alunos com diferenças de aprendizagem. Este artigo demonstra como lançar o Leitura Avançada JavaScript, Python, Android ou iOS.

Pré-requisitos

  • Subscrição Azure - Crie uma gratuitamente
  • Um recurso Leitura Avançada configurado para a autenticação do Azure Ative Directory. Siga estas instruções para se preparar. Você precisará de alguns dos valores criados aqui ao configurar as propriedades ambientais. Guarde a saída da sua sessão num ficheiro de texto para referência futura.
  • Node.js e Fios
  • Um IDE como Código de Estúdio Visual

Crie uma Node.js web app com o Express

Crie uma aplicação web Node.js com a express-generator ferramenta.

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

Instale dependências de fios e adicione dependências e dotenv, que serão usadas request mais tarde no tutorial.

yarn
yarn add request
yarn add dotenv

Adquirir um token de autenticação Azure AD

Em seguida, escreva uma API backend para recuperar um token de autenticação Azure AD.

Você precisa de alguns valores da configuração Azure AD auth pré-requisito passo acima para esta parte. Consulte de volta o ficheiro de texto que guardou nessa sessão.

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

Assim que tiver estes valores, crie um novo ficheiro chamado .env e cole-o o seguinte código, fornecendo os valores de propriedade personalizados de cima. Não inclua aspas ou os caracteres "{" e "}".

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

Certifique-se de não comprometer este ficheiro em controlo de origem, pois contém segredos que não devem ser tornados públicos.

Em seguida, abra app.js e adicione o seguinte à parte superior do ficheiro. Isto carrega as propriedades definidas no ficheiro .env como variáveis ambientais em Nó.

require('dotenv').config();

Abra o ficheiro routes\index.js e substitua o seu conteúdo pelo seguinte código.

Este código cria um ponto final da API que adquire um token de autenticação Azure AD usando a sua senha principal de serviço. Também recupera o subdomínio. Em seguida, devolve um objeto contendo o símbolo e o subdomínio.

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;

O ponto final da API para obter leituras getimmersivereaderlaunchams deve ser protegido por trás de alguma forma de autenticação (por exemplo, OAuth) para impedir que utilizadores não autorizados obtenham tokens para usar contra o seu serviço de Leitura Avançada e faturação; esse trabalho está fora do âmbito deste tutorial.

Lançar o Leitura Avançada com conteúdo de amostra

  1. Abra as vistas\layout.pug e adicione o seguinte código na head etiqueta, antes da body etiqueta. Estas script etiquetas carregam o Leitura Avançada 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')
    
  2. Vistas abertas\index.pug e substitua o seu conteúdo pelo seguinte código. Este código povoa a página com algum conteúdo da amostra e adiciona um botão que lança o Leitura Avançada.

    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. A nossa aplicação web está agora pronta. Inicie a aplicação executando:

    npm start
    
  4. Abra o seu navegador e navegue para http://localhost:3000. Deve ver o conteúdo acima na página. Clique no botão Leitura Avançada para lançar o Leitura Avançada com o seu conteúdo.

Especificar o idioma do seu conteúdo

O Leitura Avançada tem apoio para muitas línguas diferentes. Pode especificar o idioma do seu conteúdo seguindo os passos abaixo.

  1. Abra as vistas\index.pug e adicione o seguinte código abaixo da p(id=content) etiqueta que adicionou no passo anterior. Este código adiciona alguns conteúdos em espanhol à sua 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. No código JavaScript, adicione o seguinte acima da chamada para ImmersiveReader.launchAsync. Este código transmite o conteúdo espanhol para o Leitura Avançada.

    content.chunks.push({
      content: document.getElementById('content-spanish').innerText + '\n\n',
      lang: 'es'
    });
    
  3. Navegue novamente até http://localhost:3000. Você deve ver o texto espanhol na página, e quando clicar em Leitura Avançada, ele também vai aparecer no Leitura Avançada.

Especificar o idioma da interface Leitura Avançada

Por padrão, o idioma da interface Leitura Avançada corresponde às definições de idioma do navegador. Também pode especificar o idioma da interface Leitura Avançada com o seguinte código.

  1. Em pontos de vista\index.pug, substitua a ImmersiveReader.launchAsync(token, subdomain, content) chamada para o código abaixo.

    const options = {
        uiLang: 'fr',
    }
    ImmersiveReader.launchAsync(token, subdomain, content, options);
    
  2. Navegue para http://localhost:3000. Quando lançar o Leitura Avançada, a interface será mostrada em francês.

Lançar o Leitura Avançada com conteúdo matemático

Pode incluir conteúdo de matemática no Leitura Avançada utilizando MathML.

  1. Modificar pontos de vista\index.pug para incluir o seguinte código acima da chamada para 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. Navegue para http://localhost:3000. Quando lançares o Leitura Avançada e rolares até ao fundo, verás a fórmula matemática.

Passos seguintes

Pré-requisitos

Configure credenciais de autenticação

Crie um novo ficheiro chamado .env e cole-o os seguintes nomes e valores. Forneça os valores dados quando criou o seu recurso Leitura Avançada.

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

Não comprometa este ficheiro em controlo de fontes porque contém segredos que não devem ser tornados públicos.

Fixe o ponto final getimmersivereadertoken API por trás de alguma forma de autenticação, por exemplo, OAuth. A autenticação impede que os utilizadores não autorizados obtenham fichas para usar contra o seu serviço de Leitura Avançada e faturação. Este trabalho está fora do âmbito deste tutorial.

Crie uma aplicação web Python no Windows

Crie uma aplicação web Python utilizando flask no Windows.

Instale Git.

Depois de o Git ser instalado, abra um pedido de comando e clone o repositório SDK Git Leitura Avançada para uma pasta no seu computador.

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

Instale Python.

Selecione a caixa de verificação Add Python para o PATH .

Pitões Windows Instale o passo de diálogo 1

Adicione funcionalidades opcionais selecionando caixas de verificação e, em seguida, selecione Seguinte.

Pitões Windows Instale o passo de diálogo 2

Selecione a instalação personalizada e desacorra o caminho de instalação como pasta de raiz, por exemplo, C:\Python37-32\. Em seguida, selecione Instalar.

Pitões Windows Instale o passo de diálogo 3

Depois de terminar a instalação Python, abra um pedido de comando e use cd para ir à pasta Python Scripts.

cd C:\Python37-32\Scripts

Instale o Balão.

pip install flask

Instale Jinja2. É um motor de modelo completo para Python.

pip install jinja2

Instale virtualenv. Esta ferramenta cria ambientes Python isolados.

pip install virtualenv

Instale virtualenvwrapper-win. A ideia por trás do virtualenvwrapper é facilitar o uso do virtualenv.

pip install virtualenvwrapper-win

Instale o módulo de pedidos. Os pedidos são uma biblioteca HTTP licenciada Apache2, escrita em Python.

pip install requests

Instale o módulo python-dotenv. Este módulo lê o par de valores-chave a partir do ficheiro .env e adiciona-os à variável ambiente.

pip install python-dotenv

Faça um ambiente virtual.

mkvirtualenv advanced-python

Utilize cd para ir à pasta raiz do projeto de amostra.

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

Ligue o projeto da amostra ao ambiente. Esta ação mapeia o ambiente virtual recém-criado para a pasta raiz do projeto de amostra.

setprojectdir .

Ativar o ambiente virtual.

activate

O projeto deve agora estar ativo, e verá algo como (advanced-python) C:\immersive-reader-sdk\js\samples\advanced-python> na ordem do comando.

Desativar o ambiente.

deactivate

O (advanced-python) prefixo deve desaparecer porque o ambiente está desativado.

Para reativar o ambiente, corra workon advanced-python a partir da pasta raiz do projeto de amostra.

workon advanced-python

Inicie o Leitura Avançada com o conteúdo da amostra

Quando o ambiente estiver ativo, executar o projeto de amostra entrando flask run na pasta raiz do projeto de amostra.

flask run

Abra o seu navegador, e vá para http://localhost:5000.

Crie uma aplicação web Python no OSX

Crie uma aplicação web Python utilizando flask o OSX.

Instale Git.

Depois de o Git ser instalado, abra o Terminal e clone o repositório SDK Git Leitura Avançada para uma pasta no seu computador.

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

Instale Python.

A pasta raiz Python, por exemplo, Python37-32deve agora estar na pasta Aplicações.

Depois de terminada a instalação Python, abra o Terminal e use-o cd para ir à pasta Python Scripts.

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

Instale o pip.

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

Executar o seguinte código para instalar pip para o utilizador atualmente inscrito para evitar problemas de permissões.

python get-pip.py --user
sudo nano /etc/paths
  • Insira a sua palavra-passe, quando solicitado.
  • Adicione o caminho da sua instalação do pip à variável PATH.
  • Vá para a parte inferior do ficheiro e introduza o caminho que pretende adicionar como o último item da lista, por exemplo, PATH=$PATH:/usr/local/bin.
  • Selecione CTRL+X para desistir.
  • Introduza Y para guardar o tampão modificado.
  • Já está! Para testá-lo, numa nova janela do Terminal, entre echo $PATH.

Instale o Balão.

pip install flask --user

Instale Jinja2. É um motor de modelo completo para Python.

pip install Jinja2 --user

Instale virtualenv. Esta ferramenta cria ambientes Python isolados.

pip install virtualenv --user

Instale virtualenvwrapper. A ideia por trás do virtualenvwrapper é facilitar o uso do virtualenv.

pip install virtualenvwrapper --user

Instale o módulo de pedidos. Os pedidos são uma biblioteca HTTP licenciada Apache2, escrita em Python.

pip install requests --user

Instale o módulo python-dotenv. Este módulo lê o par de valores-chave a partir do ficheiro .env e adiciona-os à variável ambiente.

pip install python-dotenv --user

Escolha uma pasta onde pretende manter os seus ambientes virtuais e execute este comando:

mkdir ~/.virtualenvs

Utilize cd para ir à pasta de aplicação de amostra SDK Python Leitura Avançada.

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

Faça um ambiente virtual.

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

Ligue o projeto da amostra ao ambiente. Esta ação mapeia o ambiente virtual recém-criado para a pasta raiz do projeto de amostra.

setprojectdir .

Ativar o ambiente virtual.

activate

O projeto deve agora estar ativo, e verá algo como (advanced-python) /immersive-reader-sdk/js/samples/advanced-python> na ordem do comando.

Desativar o ambiente.

deactivate

O (advanced-python) prefixo deve desaparecer porque o ambiente está desativado.

Para reativar o ambiente, corra workon advanced-python a partir da pasta raiz do projeto de amostra.

workon advanced-python

Inicie o Leitura Avançada com o conteúdo da amostra

Quando o ambiente estiver ativo, executar o projeto de amostra entrando flask run na pasta raiz do projeto de amostra.

flask run

Abra o seu navegador, e vá para http://localhost:5000.

Passos seguintes

Pré-requisitos

Configure credenciais de autenticação

  1. Inicie o Android Studio e abra o projeto a partir do diretório imersivo-leitor-sdk/js/samples/quickstart-java-android (Java) ou do imersivo-reader-sdk/js/samples/quickstart-kotlin diretório (Kotlin).

  2. Crie um ficheiro nomeado env dentro da pasta /ativos . Adicione os seguintes nomes e valores e valores de fornecimento conforme apropriado. Não comprometa este ficheiro em controlo de fontes porque contém segredos que não devem ser tornados públicos.

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

Inicie o Leitura Avançada com o conteúdo da amostra

Escolha um emulador de dispositivo do Gestor AVD e execute o projeto.

Passos seguintes

Pré-requisitos

  • Subscrição Azure - Crie uma gratuitamente
  • Um recurso Leitura Avançada configurado para a autenticação do Azure Ative Directory. Siga estas instruções para se preparar. Você precisará de alguns dos valores criados aqui ao configurar as propriedades ambientais. Guarde a saída da sua sessão num ficheiro de texto para referência futura.
  • macOS.
  • O Git.
  • Leitura Avançada SDK.
  • O Xcode.

Configure credenciais de autenticação

  1. Abra o Xcode e abra o imersivo-reader-sdk/js/samples/ios/quickstart-swift/quickstart-swift.xcodeproj.

  2. No menu superior, selecione Esquemade Ediçãode Esquema> de Produto>.

  3. Na vista Executar , selecione o separador Argumentos .

  4. Na secção Variáveis Ambientais , adicione os seguintes nomes e valores. Forneça os valores dados quando criou o seu recurso Leitura Avançada.

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

Não comprometas esta mudança no controlo de fontes porque contém segredos que não devem ser tornados públicos.

Inicie o Leitura Avançada com o conteúdo da amostra

Em Xcode, selecione Ctrl+R para executar o projeto.

Passos seguintes