Запуск иммерсивного средства чтения

Статья
03/05/2024

В обзоре вы узнали о Иммерсивное средство чтения и о том, как он реализует проверенные методы для улучшения понимания чтения для учащихся языка, новых читателей и учащихся с различиями в обучении. В этой статье показано, как запустить Иммерсивное средство чтения с помощью JavaScript, Python, Android или iOS.

Необходимые компоненты

Подписка Azure. Вы можете создать бесплатную учетную запись.
Ресурс Иммерсивное средство чтения, настроенный для проверки подлинности Microsoft Entra. Инструкции по настройке см. здесь. Сохраните выходные данные сеанса в текстовый файл, чтобы настроить свойства среды.
Node.js и Yarn.
Интегрированная среда разработки, такая как Visual Studio Code.

Создание веб-приложения Node.js с помощью средства Express

Создайте веб-приложение Node.js с помощью средства express-generator.

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

Установите зависимости yarn и добавьте зависимости request и dotenv, которые используются далее в руководстве.

yarn
yarn add request
yarn add dotenv

Установите библиотеки axios и qs, выполнив следующую команду:

npm install axios qs

Настройка проверки подлинности

Затем напишите внутренний API для получения маркера проверки подлинности Microsoft Entra.

Для этой части потребуется несколько значений из шага предварительных требований к настройке проверки подлинности Microsoft Entra. Вернитесь к текстовому файлу, сохраненного из этого сеанса.

TenantId     => Azure subscription TenantId
ClientId     => Microsoft Entra ApplicationId
ClientSecret => Microsoft Entra 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/')

Создайте новый файл с именем .env в корневом каталоге проекта. Вставьте в него следующий код, указав значения, заданные при создании ресурса "Иммерсивное средство чтения". Не включайте кавычки или {} символы.

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

Не зафиксируйте этот файл в системе управления версиями, так как он содержит секреты, которые не должны быть общедоступными.

Затем откройте файл app.js и добавьте следующее в его начало. При этом свойства, определенные в env-файле, загружаются в виде переменных среды в Node.

require('dotenv').config();

Откройте файл routes\index.js и замените имеющееся содержимое приведенным ниже кодом.

Этот код создает конечную точку API, которая получает маркер проверки подлинности Microsoft Entra с помощью пароля субъекта-службы. Кроме того, этот код возвращает дочерний домен, а также объект, содержащий токен и поддомен.

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 getimmersivereaderlaunchparams должна быть защищена с помощью формы проверки подлинности (например, OAuth), чтобы предотвратить получение неавторизованными пользователями токенов для использования относительно службы "Иммерсивное средство чтения" и выставления счетов. Эти сведения выходят за рамки этого руководства.

Запуск иммерсивного средства чтения с примером содержимого

Откройте файл views\layout.pug и добавьте следующий код под тег head перед тегом body. Эти теги script загрузят пакет SDK для иммерсивного средства чтения и 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')
```

Откройте файл views\index.pug и замените его содержимое следующим кодом. Этот код заполнит страницу примером содержимого и добавит кнопку, которая запустит иммерсивное средство чтения.

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

Теперь наше веб-приложение готово. Запустите приложение, выполнив следующую команду:
```
npm start
```
Откройте браузер и перейдите по адресу http://localhost:3000. Вы увидите упомянутое выше содержимое на странице. Нажмите кнопку Иммерсивное средство чтения, чтобы запустить Иммерсивное средство чтения с содержимым.

Указание языка содержимого

Иммерсивное средство чтения поддерживает много различных языков. Вы можете указать язык содержимого, выполнив следующие действия.

Откройте файл views\index.pug и добавьте следующий код ниже тега p(id=content), который был добавлен в предыдущем шаге. Этот код добавляет на вашу страницу содержимое на испанском языке.
```
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.
```
В представлениях\index.pug добавьте следующий код над вызовом ImmersiveReader.launchAsync. Этот код передает содержимое на испанском языке в иммерсивное средство чтения.
```
content.chunks.push({
  content: document.getElementById('content-spanish').innerText + '\n\n',
  lang: 'es'
});
```
Перейдите по адресу http://localhost:3000 еще раз. На странице должен отображаться испанский текст, а при выборе Иммерсивное средство чтения он также отображается в Иммерсивное средство чтения.

Указание языка интерфейса иммерсивного средства чтения

По умолчанию язык интерфейса иммерсивного средства чтения соответствует языковым настройкам браузера. Язык интерфейса этого средства также можно указать с помощью следующего кода.

В представлениях\index.pug замените вызов ImmersiveReader.launchAsync(token, subdomain, content) на следующий код.
```
const options = {
    uiLang: 'fr',
}
ImmersiveReader.launchAsync(token, subdomain, content, options);
```
Перейдите к http://localhost:3000. При запуске Иммерсивное средство чтения интерфейс отображается на французском языке.

Запуск иммерсивного средства чтения с математическим содержимым

Вы можете добавить математические содержимое в иммерсивное средство чтения, используя MathML.

Добавьте в файл views\index.pug следующий код над вызовом 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'
});

Перейдите к http://localhost:3000. Запустив иммерсивное средство чтения и прокрутив вниз страницы, вы увидите математическую формулу.

Следующий шаг

Изучение пакета SDK для Иммерсивное средство чтения

Необходимые компоненты

Подписка Azure. Вы можете создать бесплатную учетную запись.
Ресурс Иммерсивное средство чтения, настроенный для проверки подлинности Microsoft Entra. Инструкции по настройке см. здесь. Сохраните выходные данные сеанса в текстовый файл, чтобы настроить свойства среды.
Интегрированная среда разработки, такая как Visual Studio Code.
Git.
Клонируйте пакет SDK Иммерсивное средство чтения из GitHub.

В этом руководстве можно установить следующие средства.

Python и pip Начиная с Python 3.4, pip включается по умолчанию с двоичными установщиками Python.
Flask
Jinja
virtualenv и virtualenvwrapper-win для Windows или virtualenvwrapper для OSX
Модуль запросов

Определение учетных данных для проверки подлинности

Создайте файл с именем ENV в корневом каталоге проекта. Вставьте в него следующие имена и значения. Укажите значения, заданные при создании ресурса "Иммерсивное средство чтения".

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

Не фиксируйте этот файл в системе управления версиями, так как он содержит секреты, не предназначенные для публикации.

Защитите конечную точку API getimmersivereadertoken за какой-то формой проверки подлинности, например OAuth. Проверка подлинности не позволяет неавторизованным пользователям получать маркеры для использования в службе иммерсивного средства чтения и управления выставлением счетов. Эти действия не рассматриваются в этом руководстве.

Создание веб-приложения Python в Windows

установите Python;

Выберите поле "Добавить Python в PATH проверка" и выберите "Настраиваемая установка".

Screenshot of Install Python step 1 with Add Python to Path checkbox.

Добавьте дополнительные функции, установив нужные флажки, а затем щелкните Далее.

Screenshot of Install Python step 2 with optional features.

В разделе "Дополнительные параметры" задайте путь установки в качестве корневой папки, например C:\Python312. Щелкните Установить.

Совет

При установке пользовательского пути установки переменная PATH может по-прежнему указывать на путь установки по умолчанию. Убедитесь, что PATH указывает на пользовательскую папку.

Screenshot of Install Python step 3 with custom location.

После завершения установки Python откройте командную строку и командой cd перейдите в папку со скриптами Python.

cd C:\Python312\Scripts

Установите Flask.

pip install flask

Установите Jinja2. Это полнофункциональный механизм шаблонов для Python.

pip install jinja2

Установите virtualenv. Это средство для создания изолированных сред Python.

pip install virtualenv

Установите virtualenvwrapper-win. virtualenvwrapper предназначен для упрощения работы с virtualenv.

pip install virtualenvwrapper-win

Установите модуль "requests". Requests (Запросы) содержит лицензированную для Apache2 библиотеку HTTP на языке Python.

pip install requests

Установите модуль python-dotenv. Этот модуль считывает пару "ключ-значение" из env-файла и добавляет их в переменную среды.

pip install python-dotenv

Создайте виртуальную среду.

mkvirtualenv.bat quickstart-python

Командой cd перейдите в корневую папку примера проекта.

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

Подключите пример проекта к этой среде. Это действие сопоставляет новую виртуальную среду с корневой папкой примера проекта.

setprojectdir .

Включите виртуальную среду.

activate

Теперь проект должен стать активным, и в командной строке отобразится примерно следующее: (quickstart-python) C:\immersive-reader-sdk\js\samples\quickstart-python>.

Отключите среду.

deactivate

Префикс (quickstart-python) исчезнет, так как среда отключена.

Чтобы повторно включить среду, выполните команду workon quickstart-python из корневой папки примера проекта.

workon quickstart-python

Запуск иммерсивного средства чтения с примером содержимого

При включенной среде запустите пример проекта, введя команду flask run в корневой папке проекта.

flask run

Откройте браузер и перейдите по адресу http://localhost:5000.

Создание веб-приложения Python в OSX

установите Python;

Корневая папка Python, например Python312, должна находиться в папке Applications. Откройте терминал и перейдите cd в папку Python.

cd Python312

установить pip.

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

Выполните следующий фрагмент кода, чтобы установить pip для активного пользователя, чтобы избежать проблем с разрешениями.

python get-pip.py --user

sudo nano /etc/paths

В ответ на запрос введите свой пароль.
Добавьте расположение установки pip в переменную пути.
Перейдите в нижнюю часть файла и введите путь, который нужно добавить в конец списка, например PATH=$PATH:/usr/local/bin.
Чтобы выйти, нажмите клавиши CTRL+X.
Введите Y для сохранения изменений буфера.

Вот и все! Чтобы проверить установку, в новом окне терминала введите echo $PATH.

Установите Flask.

pip install flask --user

Установите Jinja2. Это полнофункциональный механизм шаблонов для Python.

pip install Jinja2 --user

Установите virtualenv. Это средство для создания изолированных сред Python.

pip install virtualenv --user

Установите virtualenvwrapper. virtualenvwrapper предназначен для упрощения работы с virtualenv.

pip install virtualenvwrapper --user

Установите модуль "requests". Requests (Запросы) содержит лицензированную для Apache2 библиотеку HTTP на языке Python.

pip install requests --user

pip install python-dotenv --user

Выберите папку, в которой вы хотите разместить виртуальные среды, и выполните эту команду:

mkdir ~/.virtualenvs

С помощью cd перейдите в папку примера приложения Python с SDK для иммерсивного средства чтения.

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

Создайте виртуальную среду.

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

setprojectdir .

Включите виртуальную среду.

activate

Теперь проект должен стать активным, и в командной строке отобразится примерно следующее: (quickstart-python) /immersive-reader-sdk/js/samples/quickstart-python>.

Отключите среду.

deactivate

Префикс (quickstart-python) исчезнет, так как среда отключена.

Чтобы повторно включить среду, выполните команду workon quickstart-python из корневой папки примера проекта.

workon quickstart-python

Запуск иммерсивного средства чтения с примером содержимого

При включенной среде запустите пример проекта, введя команду flask run в корневой папке проекта.

flask run

Откройте браузер и перейдите по адресу http://localhost:5000.

Следующий шаг

Ознакомьтесь со справочником по пакету SDK Иммерсивное средство чтения

Необходимые компоненты

Подписка Azure. Вы можете создать бесплатную учетную запись.
Ресурс Иммерсивное средство чтения, настроенный для проверки подлинности Microsoft Entra. Инструкции по настройке см. здесь. Сохраните выходные данные сеанса в текстовый файл, чтобы настроить свойства среды.
Git.
Клонируйте пакет SDK Иммерсивное средство чтения из GitHub.
Android Studio.

Определение учетных данных для проверки подлинности

Запустите Android Studio и откройте проект пакета SDK Иммерсивное средство чтения из иммерсивного пакета sdk-reader/js/samples/quickstart-java-android (Java) или иммерсивного-читателя-sdk/js/samples/quickstart-kotlin directory (Kotlin).

Совет

Возможно, потребуется разрешить системе обновить подключаемые модули Gradle до по крайней мере версии 8.
Чтобы создать новую папку ресурсов, щелкните правой кнопкой мыши приложение и выберите папку "Папка ->Активы" в раскрывающемся списке.
Щелкните правой кнопкой мыши ресурсы и выберите "Создать файл>". Назовите файл env.
Добавьте следующие имена и значения, используя данные о вашей среде. Не фиксируйте этот файл в системе управления версиями, так как он содержит секреты, не предназначенные для публикации.
```
TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET=<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>
```

Запуск иммерсивного средства чтения с примером содержимого

Выберите эмулятор устройства в диспетчере AVD и запустите проект.

Следующие шаги

Изучение пакета SDK для Иммерсивное средство чтения

Необходимые компоненты

Подписка Azure. Вы можете создать бесплатную учетную запись.
Ресурс Иммерсивное средство чтения, настроенный для проверки подлинности Microsoft Entra. Инструкции по настройке см. здесь. Сохраните выходные данные сеанса в текстовый файл, чтобы настроить свойства среды.
macOS и Xcode.
Git.
Клонируйте пакет SDK Иммерсивное средство чтения из GitHub.

Определение учетных данных для проверки подлинности

В Xcode выберите "Открыть существующий проект". Откройте файл immersive-reader-sdk/js/samples/ios/quickstart-swift.xcodeproj.
В верхнем меню выберите Product (Продукт)>Scheme (Схема)>Edit Scheme (Изменить схему).
В представлении Run (Запуск) откройте вкладку Arguments (Аргументы).
В разделе Environment Variables (Переменные среды) добавьте следующие имена и значения. Укажите значения, заданные при создании ресурса "Иммерсивное средство чтения".
```
TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>
```

Не фиксируйте это изменение в системе управления версиями, так как оно содержит секреты, не предназначенные для публикации.

Запуск иммерсивного средства чтения с примером содержимого

В Xcode выберите симулятор устройства, а затем запустите проект из элементов управления или введите CTRL+R.

Следующий шаг

Изучение пакета SDK для Иммерсивное средство чтения

Запуск иммерсивного средства чтения

Необходимые компоненты

Создание веб-приложения Node.js с помощью средства Express

Настройка проверки подлинности

Запуск иммерсивного средства чтения с примером содержимого

Указание языка содержимого

Указание языка интерфейса иммерсивного средства чтения

Запуск иммерсивного средства чтения с математическим содержимым

Следующий шаг

Необходимые компоненты

Определение учетных данных для проверки подлинности

Создание веб-приложения Python в Windows

Запуск иммерсивного средства чтения с примером содержимого

Создание веб-приложения Python в OSX

Запуск иммерсивного средства чтения с примером содержимого

Следующий шаг

Необходимые компоненты

Определение учетных данных для проверки подлинности

Запуск иммерсивного средства чтения с примером содержимого

Следующие шаги

Необходимые компоненты

Определение учетных данных для проверки подлинности

Запуск иммерсивного средства чтения с примером содержимого

Следующий шаг

Дополнительные ресурсы