如何啟動沈浸式閱讀程式

發行項
10/16/2024

在概觀中，您會了解什麼是沈浸式閱讀程式，及其如何實作經實證的技術，針對語言學習者、沈浸式讀者及存在學習差異的學生改善其閱讀理解程度。本文示範如何使用 JavaScript、Python、Android 或 iOS 啟動沈浸式閱讀程式。

必要條件

Azure 訂用帳戶。您可以免費建立一個訂用帳戶。
為 Microsoft Entra 驗證所設定的沈浸式閱讀程式資源。遵循這些指引來設定。將工作階段輸出儲存到文字檔中以設定環境屬性。
Node.js 和 Yarn。
整合式開發環境，例如 Visual Studio Code。

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

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

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;

getimmersivereaderlaunchparams API 端點在某種形式的驗證 (例如 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);
        }

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.

在 views\index.pug 於 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

必要條件

Azure 訂用帳戶。您可以免費建立一個訂用帳戶。
為 Microsoft Entra 驗證所設定的沈浸式閱讀程式資源。遵循這些指引來設定。將工作階段輸出儲存到文字檔中以設定環境屬性。
整合式開發環境，例如 Visual Studio Code。
Git。
複製 GitHub 的沈浸式閱讀程式 SDK。

您可以安裝下列工具作為本指南指令的一部分：

Python 和 pip。從 Python 3.4 開始，Python 二進位安裝程式依預設會包含 pip。
Flask
Jinja
virtualenv 和 virtualenvwrapper-win for Windows 或 virtualenvwrapper for OSX
要求模組

設定驗證認證

在專案的根目錄中，建立名為 .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 應用程式

安裝 Python。

選取 [新增 Python 至 PATH] 核取方塊，然後選取 [自訂安裝]。

以 [新增 Python 至 Path] 核取方塊安裝 Python 步驟 1 的螢幕擷取畫面。

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

以選用功能安裝 Python 步驟 2 的螢幕擷取畫面。

在 [進階選項] 之下將安裝路徑設定為根資料夾，例如 C:\Python312。然後選取 [安裝]。

提示

您設定自訂安裝路徑時，PATH 變數可能仍指向預設安裝路徑。請驗證 PATH 指向自訂資料夾。

以自訂位置安裝 Python 步驟 3 的螢幕擷取畫面。

在 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

安裝要求模組。「要求」是 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。

在 OSX 上建立 Python Web 應用程式

安裝 Python。

Python 根資料夾 (例如 Python312) 現在應位於 [應用程式] 資料夾中。開啟 [終端] 並使用 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=$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

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

pip install requests --user

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

pip install python-dotenv --user

選擇要用來保存虛擬環境的資料夾，並執行下列命令：

mkdir ~/.virtualenvs

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

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。
複製 GitHub 的沈浸式閱讀程式 SDK。
Android Studio.

設定驗證認證

啟動 Android Studio，然後從 immersive-reader-sdk/js/samples/quickstart-java-android 目錄 (JAVA) 或 immersive-reader-sdk/js/samples/quickstart-kotlin 目錄 (Kotlin) 中開啟沈浸式閱讀程式 SDK 專案。

提示

您可能需要讓系統將 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。
複製 GitHub 的沈浸式閱讀程式 SDK。

設定驗證認證

在 Xcode 中選取 [開啟現有專案]。開啟檔案 immersive-reader-sdk/js/samples/ios/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

共用方式為

如何啟動沈浸式閱讀程式

必要條件

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

設定驗證

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

指定內容的語言

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

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

後續步驟

必要條件

設定驗證認證

在 Windows 上建立 Python Web 應用程式

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

在 OSX 上建立 Python Web 應用程式

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

後續步驟

必要條件

設定驗證認證

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

下一步

必要條件

設定驗證認證

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

後續步驟

意見反應

其他資源