Cara meluncurkan Immersive Reader

  • Artikel

Dalam gambaran umum, Anda belajar tentang Pembaca Imersif dan bagaimana hal itu menerapkan teknik yang terbukti untuk meningkatkan pemahaman membaca bagi pelajar bahasa, pembaca yang muncul, dan siswa dengan perbedaan pembelajaran. Artikel ini menunjukkan cara meluncurkan Pembaca Imersif menggunakan JavaScript, Python, Android, atau iOS.

Prasyarat

  • Langganan Azure. Anda dapat membuatnya secara gratis.
  • Sumber daya Pembaca Imersif dikonfigurasi untuk autentikasi Microsoft Entra. Ikuti petunjuk ini untuk menyiapkannya. Simpan output sesi Anda ke dalam file teks sehingga Anda dapat mengonfigurasi properti lingkungan.
  • Node.js dan Yarn.
  • IDE seperti Visual Studio Code.

Membuat aplikasi web Node.js dengan Ekspres

Membuat aplikasi web Node.js dengan alat express-generator.

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

Instal dependensi yarn, dan tambahkan dependensi request dan dotenv, yang digunakan nanti dalam tutorial.

yarn
yarn add request
yarn add dotenv

Pasang pustaka axios dan qs dengan perintah berikut:

npm install axios qs

Mengonfigurasikan autentikasi

Selanjutnya, tulis API backend untuk mengambil token autentikasi Microsoft Entra.

Anda memerlukan beberapa nilai dari langkah prasyarat konfigurasi autentikasi Microsoft Entra untuk bagian ini. Lihat kembali file teks yang Anda simpan dari sesi tersebut.

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

Buat file baru yang disebut .env di akar proyek Anda. Tempelkan kode berikut ke dalamnya, berikan nilai yang diberikan saat Anda membuat sumber daya Pembaca Imersif Anda. Jangan sertakan tanda kutip atau { karakter dan } .

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

Pastikan untuk tidak menerapkan file ini ke dalam kontrol sumber, karena berisi rahasia yang seharusnya tidak diumumkan ke publik.

Selanjutnya, buka app.js dan tambahkan yang berikut ini ke bagian atas file. Ini memuat properti yang ditentukan dalam file .env sebagai variabel lingkungan ke dalam Node.

require('dotenv').config();

Buka file routes\index.js dan ganti kontennya dengan kode berikut.

Kode ini membuat titik akhir API yang memperoleh token autentikasi Microsoft Entra menggunakan kata sandi perwakilan layanan Anda. Ini juga mengambil subdomain. Kemudian menampilkan objek yang berisi token dan subdomain.

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;

Titik akhir API getimmersivereaderlaunchparams harus diamankan mnggunakan beberapa bentuk autentikasi (misalnya, OAuth) untuk mencegah pengguna yang tidak sah mendapatkan token untuk digunakan terhadap layanan dan penagihan Immersive Reader Anda; pekerjaan itu berada di luar cakupan tutorial ini.

Meluncurkan Immersive Reader dengan konten sampel

  1. Buka views\layout.pug, dan tambahkan kode berikut di bawah tag head, sebelum tag body. Tag script ini memuat SDK Immersive Reader dan 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. Buka views\index.pug, dan ganti kontennya dengan kode berikut. Kode ini mengisi halaman dengan beberapa contoh konten, dan menambahkan tombol yang meluncurkan Immersive Reader.

    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. Aplikasi web kami sekarang siap. Mulai aplikasi dengan menjalankan:

    npm start

  4. Buka browser Anda dan buka http://localhost:3000. Anda akan melihat konten di atas pada halaman. Pilih tombol Pembaca Imersif untuk meluncurkan Pembaca Imersif dengan konten Anda.

Menentukan bahasa konten Anda

Immersive Reader memiliki dukungan untuk berbagai bahasa. Anda dapat menentukan bahasa konten Anda dengan mengikuti langkah-langkah ini.

  1. Buka views\index.pug dan tambahkan kode berikut di bawah tag p(id=content) yang Anda tambahkan pada langkah sebelumnya. Kode ini menambahkan beberapa konten bahasa Spanyol ke halaman Anda.

    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. Dalam views\index.pug, tambahkan kode berikut di atas panggilan ke ImmersiveReader.launchAsync. Kode ini meneruskan konten bahasa Spanyol ke Immersive Reader.

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

  3. Buka http://localhost:3000 lagi. Anda akan melihat teks Spanyol di halaman, dan saat Anda memilih Pembaca Imersif, teks tersebut juga muncul di Pembaca Imersif.

Menentukan bahasa antarmuka Immersive Reader

Secara default, bahasa antarmuka Immersive Reader cocok dengan pengaturan bahasa browser. Anda juga dapat menentukan bahasa antarmuka Immersive Reader dengan kode berikut.

  1. Di views\index.pug, ganti panggilan ke ImmersiveReader.launchAsync(token, subdomain, content) dengan kode berikut.

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

  2. Buka http://localhost:3000. Saat Anda meluncurkan Pembaca Imersif, antarmuka ditampilkan dalam bahasa Prancis.

Meluncurkan Immersive Reader dengan konten matematika

Anda dapat menyertakan konten matematika di Immersive Reader dengan menggunakan MathML.

  1. Ubah views\index.pug untuk menyertakan kode berikut di atas panggilan ke 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. Buka http://localhost:3000. Saat meluncurkan Immersive Reader dan menggulir ke bawah, Anda akan melihat rumus matematika.

Langkah selanjutnya

Menjelajahi SDK Pembaca Imersif

Prasyarat

  • Langganan Azure. Anda dapat membuatnya secara gratis.
  • Sumber daya Pembaca Imersif dikonfigurasi untuk autentikasi Microsoft Entra. Ikuti petunjuk ini untuk menyiapkannya. Simpan output sesi Anda ke dalam file teks sehingga Anda dapat mengonfigurasi properti lingkungan.
  • IDE seperti Visual Studio Code.
  • Git.
  • Kloning SDK Pembaca Imersif dari GitHub.

Anda dapat menginstal alat berikut sebagai bagian dari instruksi dalam panduan ini:

Konfigurasikan info masuk autentikasi

Buat file baru bernama .env di direktori akar proyek Anda. Tempelkan nama dan nilai berikut ke dalamnya. Berikan nilai yang diberikan saat Anda membuat sumber daya Immersive Reader Anda.

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

Jangan terapkan file ini ke dalam kontrol sumber karena berisi rahasia yang tidak boleh dipublikasikan.

Amankan titik akhir API getimmersivereadertoken di balik beberapa bentuk autentikasi, seperti OAuth. Autentikasi mencegah pengguna yang tidak sah mendapatkan token untuk digunakan terhadap layanan dan tagihan Immersive Reader Anda. Pekerjaan tersebut berada di luar cakupan tutorial ini.

Membuat aplikasi web Python di Windows

Pasang Python.

Pilih kotak centang Tambahkan Python ke PATH , dan pilih Penginstalan kustom.

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

Tambahkan Fitur Opsional dengan memilih kotak centang, lalu pilih Berikutnya.

Screenshot of Install Python step 2 with optional features.

Di bawah Opsi Tingkat Lanjut, atur jalur penginstalan sebagai folder akar Anda, misalnya, C:\Python312. Lalu pilih Pasang.

Tip

Saat Anda mengatur jalur penginstalan kustom, variabel PATH mungkin masih menunjuk ke jalur penginstalan default. Verifikasi bahwa PATH menunjuk ke folder kustom.

Screenshot of Install Python step 3 with custom location.

Setelah penginstalan Python selesai, buka perintah dan gunakan cd untuk membuka folder Skrip Python.

cd C:\Python312\Scripts

Pasang Flask.

pip install flask

Pasang Jinja2. Ini adalah mesin templat berfitur lengkap untuk Python.

pip install jinja2

Pasang virtualenv. Alat ini membuat lingkungan Python yang terisolasi.

pip install virtualenv

Pasang virtualenvwrapper-win. Ide di balik virtualenvwrapper adalah untuk memudahkan penggunaan virtualenv.

pip install virtualenvwrapper-win

Pasang modul permintaan. Permintaan adalah pustaka HTTP Berlisensi Apache2, yang ditulis dalam Python.

pip install requests

Pasang modul python-dotenv. Modul ini membaca pasangan kunci-nilai dari file .env dan menambahkannya ke variabel lingkungan.

pip install python-dotenv

Buat lingkungan virtual.

mkvirtualenv.bat quickstart-python

Gunakan cd untuk membuka folder akar proyek sampel.

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

Sambungkan proyek sampel dengan lingkungan. Tindakan ini memetakan lingkungan virtual yang baru dibuat ke folder akar proyek sampel.

setprojectdir .

Aktifkan lingkungan virtual.

activate

Proyek sekarang seharusnya aktif, dan Anda akan melihat sesuatu seperti (quickstart-python) C:\immersive-reader-sdk\js\samples\quickstart-python> di perintah.

Nonaktifkan lingkungan.

deactivate

Awalan (quickstart-python) seharusnya hilang karena lingkungan dinonaktifkan.

Untuk mengaktifkan ulang lingkungan, jalankan workon quickstart-python dari folder akar proyek sampel.

workon quickstart-python

Memulai Immersive Reader dengan sampel konten

Saat lingkungan aktif, jalankan proyek sampel dengan memasukkan flask run dari folder akar proyek sampel.

flask run

Buka browser Anda, dan buka http://localhost:5000.

Membuat aplikasi web Python di OSX

Pasang Python.

Folder akar Python, misalnya, Python312, sekarang seharusnya ada di folder Aplikasi. Buka Terminal dan gunakan cd untuk masuk ke folder Python.

cd Python312

Pasang pip.

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

Jalankan kode berikut untuk memasang pip bagi pengguna yang saat ini masuk untuk menghindari masalah izin.

python get-pip.py --user

sudo nano /etc/paths
  • Masukkan kata sandi Anda, saat diminta.
  • Tambahkan jalur penginstalan pip Anda ke variabel PATH.
  • Buka bagian bawah file, dan masukkan jalur yang ingin Anda tambahkan sebagai item terakhir dari daftar, misalnya, PATH=$PATH:/usr/local/bin.
  • Pilih CTRL+X untuk keluar.
  • Masukkan Y untuk menyimpan buffer yang diubah.

Itu saja! Untuk mengujinya, di jendela Terminal baru, masukkan echo $PATH.

Pasang Flask.

pip install flask --user

Pasang Jinja2. Ini adalah mesin templat berfitur lengkap untuk Python.

pip install Jinja2 --user

Pasang virtualenv. Alat ini membuat lingkungan Python yang terisolasi.

pip install virtualenv --user

Pasang virtualenvwrapper. Ide di balik virtualenvwrapper adalah untuk memudahkan penggunaan virtualenv.

pip install virtualenvwrapper --user

Pasang modul permintaan. Permintaan adalah pustaka HTTP Berlisensi Apache2, yang ditulis dalam Python.

pip install requests --user

Pasang modul python-dotenv. Modul ini membaca pasangan kunci-nilai dari file .env dan menambahkannya ke variabel lingkungan.

pip install python-dotenv --user

Pilih folder tempat Anda ingin menyimpan lingkungan virtual Anda, dan jalankan perintah ini:

mkdir ~/.virtualenvs

Gunakan cd untuk membuka folder aplikasi contoh Python SDK Immersive Reader.

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

Buat lingkungan virtual.

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

Sambungkan proyek sampel dengan lingkungan. Tindakan ini memetakan lingkungan virtual yang baru dibuat ke folder akar proyek sampel.

setprojectdir .

Aktifkan lingkungan virtual.

activate

Proyek sekarang seharusnya aktif, dan Anda akan melihat sesuatu seperti (quickstart-python) /immersive-reader-sdk/js/samples/quickstart-python> di perintah.

Nonaktifkan lingkungan.

deactivate

Awalan (quickstart-python) seharusnya hilang karena lingkungan dinonaktifkan.

Untuk mengaktifkan ulang lingkungan, jalankan workon quickstart-python dari folder akar proyek sampel.

workon quickstart-python

Memulai Immersive Reader dengan sampel konten

Saat lingkungan aktif, jalankan proyek sampel dengan memasukkan flask run dari folder akar proyek sampel.

flask run

Buka browser Anda, dan buka http://localhost:5000.

Langkah selanjutnya

Menjelajahi referensi SDK Pembaca Imersif

Prasyarat

  • Langganan Azure. Anda dapat membuatnya secara gratis.
  • Sumber daya Pembaca Imersif dikonfigurasi untuk autentikasi Microsoft Entra. Ikuti petunjuk ini untuk menyiapkannya. Simpan output sesi Anda ke dalam file teks sehingga Anda dapat mengonfigurasi properti lingkungan.
  • Git.
  • Kloning SDK Pembaca Imersif dari GitHub.
  • Android Studio.

Konfigurasikan info masuk autentikasi

  1. Mulai Android Studio, dan buka proyek SDK Pembaca Imersif dari direktori immersive-reader-sdk/js/samples/quickstart-java-android (Java) atau immersive-reader-sdk/js/samples/quickstart-kotlin (Kotlin).

    Tip

    Anda mungkin perlu membiarkan sistem memperbarui plugin Gradle ke setidaknya versi 8.

  2. Untuk membuat folder aset baru, klik kanan pada aplikasi dan pilih Folder ->Assets Folder dari menu dropdown.

    Screenshot of the Assets folder option.

  3. Klik kanan pada aset dan pilih Baru ->File. Beri nama file env.

    Screenshot of name input field to create the env file.

  4. Tambahkan nama dan nilai berikut, dan berikan nilai sebagaimana mestinya. Jangan terapkan file ini ke dalam kontrol sumber karena berisi rahasia yang tidak boleh dipublikasikan.

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

Memulai Immersive Reader dengan sampel konten

Pilih emulator perangkat dari AVD Manager, dan jalankan proyek.

Langkah berikutnya

Menjelajahi SDK Pembaca Imersif

Prasyarat

  • Langganan Azure. Anda dapat membuatnya secara gratis.
  • Sumber daya Pembaca Imersif dikonfigurasi untuk autentikasi Microsoft Entra. Ikuti petunjuk ini untuk menyiapkannya. Simpan output sesi Anda ke dalam file teks sehingga Anda dapat mengonfigurasi properti lingkungan.
  • macOS dan Xcode.
  • Git.
  • Kloning SDK Pembaca Imersif dari GitHub.

Konfigurasikan info masuk autentikasi

  1. Di Xcode, pilih Buka Proyek yang Ada. Buka file immersive-reader-sdk/js/samples/ios/quickstart-swift.xcodeproj.

  2. Pada menu atas, pilih Skema>Produk>Edit Skema.

  3. Dalam tampilan Jalankan, pilih tab Argumen.

  4. Di bagian Variabel Lingkungan, tambahkan nama dan nilai berikut ini. Berikan nilai yang diberikan saat Anda membuat sumber daya Immersive Reader Anda.

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

Jangan tetapkan perubahan ini ke dalam kontrol sumber karena berisi rahasia yang seharusnya tidak dipublikasikan.

Memulai Immersive Reader dengan sampel konten

Di Xcode, pilih simulator perangkat, lalu jalankan proyek dari kontrol atau masukkan Ctrl+R.

Langkah selanjutnya

Menjelajahi SDK Pembaca Imersif