如何啟動沉浸式閱讀程式

發行項
10/24/2023

在概觀中，您已瞭解沉浸式閱讀程式是什麼，以及如何實作經過實證的技術，以改善語言學習者、新興讀者和具有學習差異的學生閱讀理解。本文示範如何啟動沉浸式閱讀程式 JavaScript、Python、Android 或 iOS。

必要條件

Azure 訂用帳戶 - 免費建立一個訂用帳戶
針對 Microsoft Entra 驗證設定沉浸式閱讀程式資源。請遵循這些指示來設定。設定環境屬性時，您將需要在這裡建立的一些值。將會話的輸出儲存至文字檔，以供日後參考。
Node.js 和 Yarn
IDE，例如 Visual Studio Code

使用 Express 建立 Node.js Web 應用程式

使用 express-generator 工具建立 Node.js Web 應用程式。

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

安裝 yarn 相依性，並新增相依性和 requestdotenv ，稍後將在教學課程中使用。

yarn
yarn add request
yarn add dotenv

取得 Microsoft Entra 驗證權杖

接下來，撰寫後端 API 以擷取 Microsoft Entra 驗證權杖。

您需要上述 Microsoft Entra 驗證設定必要步驟中的一些值，才能完成此部分。回到您儲存該會話的文字檔。

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

取得這些值之後，請建立名為 .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;

getimmersivereaderlaunchparams API 端點應受到某種形式的驗證保護，以防止未經授權的使用者取得權杖以用於您的沉浸式閱讀程式服務和計費;該工作超出本教學課程的範圍。

使用範例內容啟動沉浸式閱讀程式

開啟 views\layout.pug ，並在標記之前 body ，于標籤底下 head 新增下列程式碼。這些 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);
        }

我們的 Web 應用程式現已就緒。執行下列命令以啟動應用程式：
```
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.

在 JavaScript 程式碼中，將下列內容新增至 ImmersiveReader.launchAsync 的呼叫上方。此程式碼會將西班牙文內容傳遞至沉浸式閱讀程式。
```
content.chunks.push({
  content: document.getElementById('content-spanish').innerText + '\n\n',
  lang: 'es'
});
```
再次流覽至 http://localhost:3000 。您應該會在頁面上看到西班牙文文字，當您選取 [沈浸式閱讀程式]，它也會顯示在沈浸式閱讀程式中。

指定沉浸式閱讀程式介面的語言

根據預設，沉浸式閱讀程式介面的語言符合瀏覽器的語言設定。您也可以使用下列程式碼指定沉浸式閱讀程式介面的語言。

在 views\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 和沉浸式閱讀程式 SDK 參考
在 GitHub 上檢視程式碼範例

必要條件

Azure 訂用帳戶 - 免費建立一個訂用帳戶
針對 Microsoft Entra 驗證設定沉浸式閱讀程式資源。請遵循這些指示來設定。設定環境屬性時，您將需要在這裡建立的一些值。將會話的輸出儲存至文字檔，以供日後參考。
Git。
沉浸式閱讀程式 SDK 。
Python 和 pip 。從 Python 3.4 開始，pip 預設會隨附于 Python 二進位安裝程式中。
Flask 。
金賈
適用于 Windows 的 virtualenv 和 virtualenvwrapper-win 或 OSX 的 virtualenvwrapper。
要求模組。
IDE，例如 Visual Studio Code 。

設定驗證認證

建立名為 .env 的新檔案，並將下列名稱和值貼入其中。提供您在建立沉浸式閱讀程式資源時所提供的值。

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

請勿將此檔案認可至原始檔控制，因為它包含不應公開的秘密。

例如，在某種形式的驗證後方保護 getimmersivereadertoken API 端點，例如 OAuth 。驗證可防止未經授權的使用者取得權杖，以用於您的沉浸式閱讀程式服務和計費。這項工作超出本教學課程的範圍。

在 Windows 上建立 Python Web 應用程式

在 flask Windows 上使用建立 Python Web 應用程式。

安裝 Git。

安裝 Git 之後，請開啟命令提示字元，並將沉浸式閱讀程式 SDK Git 存放庫複製到您電腦上的資料夾。

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

安裝 Python 。

選取 [ 將 Python 新增至 PATH ] 核取方塊。

Python Windows Install dialog step 1

選取核取方塊以新增 選擇性功能 ，然後選取 [ 下一步 ]。

Python Windows Install dialog step 2

選取 [ 自訂安裝 ]，並將安裝路徑設定為根資料夾，例如 C:\Python37-32\ 。然後選取 [安裝]。

Python Windows Install dialog step 3

Python 安裝完成之後，請開啟命令提示字元，並使用 cd 移至 [Python 腳本] 資料夾。

cd C:\Python37-32\Scripts

安裝 Flask。

pip install flask

安裝 Jinja2。它是適用于 Python 的完整範本引擎。

pip install jinja2

安裝 virtualenv。此工具會建立隔離的 Python 環境。

pip install virtualenv

安裝 virtualenvwrapper-win。 virtualenvwrapper 背後的概念是簡化 virtualenv 的使用。

pip install virtualenvwrapper-win

安裝要求模組。要求是以 Python 撰寫的 Apache2 授權 HTTP 程式庫。

pip install requests

安裝 python-dotenv 模組。此模組會從 .env 檔案讀取機碼/值組，並將其新增至環境變數。

pip install python-dotenv

建立虛擬環境。

mkvirtualenv advanced-python

使用 cd 移至範例專案根資料夾。

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

使用環境連線範例專案。此動作會將新建立的虛擬環境對應至範例專案根資料夾。

setprojectdir .

啟動虛擬環境。

activate

專案現在應該使用中，而且您會在命令提示字元中看到類似的內容 (advanced-python) C:\immersive-reader-sdk\js\samples\advanced-python> 。

停用環境。

deactivate

前置 (advanced-python) 詞應該消失，因為環境已停用。

若要重新啟用環境，請從範例專案根資料夾執行 workon advanced-python 。

workon advanced-python

使用範例內容啟動沉浸式閱讀程式

當環境處於使用中狀態時，請從範例專案根資料夾輸入 flask run 來執行範例專案。

flask run

開啟瀏覽器並移至 http://localhost:5000.

在 OSX 上建立 Python Web 應用程式

在 flask OSX 上使用建立 Python Web 應用程式。

安裝 Git。

安裝 Git 之後，請開啟終端機，並將沉浸式閱讀程式 SDK Git 存放庫複製到您電腦上的資料夾。

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

安裝 Python 。

例如， Python37-32 Python 根資料夾現在應該位於 [應用程式] 資料夾中。

完成 Python 安裝之後，開啟 [終端機]，並使用 cd 移至 [Python 腳本] 資料夾。

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

安裝 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=$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

安裝要求模組。要求是以 Python 撰寫的 Apache2 授權 HTTP 程式庫。

pip install requests --user

安裝 python-dotenv 模組。此模組會從 .env 檔案讀取機碼/值組，並將其新增至環境變數。

pip install python-dotenv --user

選擇您要保留虛擬環境的資料夾，然後執行此命令：

mkdir ~/.virtualenvs

使用 cd 移至沉浸式閱讀程式 SDK Python 範例應用程式資料夾。

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

建立虛擬環境。

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

使用環境連線範例專案。此動作會將新建立的虛擬環境對應至範例專案根資料夾。

setprojectdir .

啟動虛擬環境。

activate

專案現在應該使用中，而且您會在命令提示字元中看到類似的內容 (advanced-python) /immersive-reader-sdk/js/samples/advanced-python> 。

停用環境。

deactivate

前置 (advanced-python) 詞應該消失，因為環境已停用。

若要重新啟用環境，請從範例專案根資料夾執行 workon advanced-python 。

workon advanced-python

使用範例內容啟動沉浸式閱讀程式

當環境處於使用中狀態時，請從範例專案根資料夾輸入 flask run 來執行範例專案。

flask run

開啟瀏覽器並移至 http://localhost:5000.

下一步

探索沉浸式閱讀程式 SDK 和沉浸式閱讀程式 SDK 參考。
在 GitHub 上檢視程式碼範例。

必要條件

Azure 訂用帳戶 - 免費建立一個訂用帳戶
針對 Microsoft Entra 驗證設定沉浸式閱讀程式資源。請遵循這些指示來設定。設定環境屬性時，您將需要在這裡建立的一些值。將會話的輸出儲存至文字檔，以供日後參考。
Git。
沉浸式閱讀程式 SDK 。
Android Studio 。

設定驗證認證

啟動 Android Studio，然後從 沈浸式閱讀程式 sdk/js/samples/quickstart-java-android 目錄（JAVA）或 沈浸式閱讀程式-sdk/js/samples/quickstart-kotlin 目錄（Kotlin ）開啟專案。
在 /assets 資料夾內建立名為 env 的 檔案。新增下列名稱和值，並視需要提供值。請勿將此檔案認可至原始檔控制，因為它包含不應公開的秘密。
```
TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET=<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>
```

使用範例內容啟動沉浸式閱讀程式

從 AVD 管理員選擇裝置模擬器，然後執行專案。

下一步

探索沉浸式閱讀程式 SDK 和沉浸式閱讀程式 SDK 參考。
在 GitHub 上檢視程式碼範例。

必要條件

Azure 訂用帳戶 - 免費建立一個訂用帳戶
針對 Microsoft Entra 驗證設定沉浸式閱讀程式資源。請遵循這些指示來設定。設定環境屬性時，您將需要在這裡建立的一些值。將會話的輸出儲存至文字檔，以供日後參考。
macOS。
Git。
沉浸式閱讀程式 SDK 。
Xcode 。

設定驗證認證

開啟 Xcode，並開啟 沈浸式閱讀程式-sdk/js/samples/ios/quickstart-swift/quickstart-swift.xcodeproj 。
在頂端功能表上，選取 [產品 > 配置編輯配置]。 >
在 [ 執行 ] 檢視中，選取 [ 引數] 索引標籤 。
在 [ 環境變數] 區段中，新增下列名稱和值。提供您在建立沉浸式閱讀程式資源時所提供的值。
```
TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>
```

請勿將此變更認可至原始檔控制，因為它包含不應公開的秘密。

使用範例內容啟動沉浸式閱讀程式

在 Xcode 中，選取 Ctrl+R 以執行專案。

下一步

探索沉浸式閱讀程式 SDK 和沉浸式閱讀程式 SDK 參考。
在 GitHub 上檢視程式碼範例。

如何啟動沉浸式閱讀程式

必要條件

使用 Express 建立 Node.js Web 應用程式

取得 Microsoft Entra 驗證權杖

使用範例內容啟動沉浸式閱讀程式

指定內容的語言

指定沉浸式閱讀程式介面的語言

使用數學內容啟動沉浸式閱讀程式

下一步

必要條件

設定驗證認證

在 Windows 上建立 Python Web 應用程式

使用範例內容啟動沉浸式閱讀程式

在 OSX 上建立 Python Web 應用程式

使用範例內容啟動沉浸式閱讀程式

下一步

必要條件

設定驗證認證

使用範例內容啟動沉浸式閱讀程式

下一步

必要條件

設定驗證認證

使用範例內容啟動沉浸式閱讀程式

下一步

其他資源