طريقة تشغيل القارئ الشامل

مقالة
02/28/2024

في النظرة العامة، تعرفت على القارئ الشامل وكيفية تنفيذ التقنيات المثبتة لتحسين فهم القراءة لمتعلمي اللغة والقراء الناشئين والطلاب الذين لديهم اختلافات في التعلم. توضح هذه المقالة كيفية تشغيل القارئ الشامل باستخدام JavaScript أو Python أو Android أو iOS.

المتطلبات الأساسية

اشتراك Azure. يمكنك إنشاء حسابًا مجانيًا.
مورد القارئ الشامل تم تكوينه لمصادقة Microsoft Entra. اتبع هذه التعليمات لضبط الإعدادات. احفظ إخراج جلسة العمل في ملف نصي حتى تتمكن من تكوين خصائص البيئة.
Node.js و(غزل)
بيئة تطوير متكامل، مثل Visual Studio Code.

أنشئ تطبيق ويب Node.js باستخدام Express

إنشاء تطبيق ويب Node.js باستخدام express-generator الأداة.

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

تثبيت تبعيات الغزل، وإضافة التبعيات request و dotenv، والتي يتم استخدامها لاحقا في البرنامج التعليمي.

yarn
yarn add request
yarn add dotenv

قم بتثبيت مكتبات axios وqs باستخدام الأمر التالي:

npm install axios qs

إعداد المصادقة

بعد ذلك، اكتب واجهة برمجة تطبيقات خلفية لاسترداد رمز مصادقة Microsoft Entra المميز.

تحتاج إلى بعض القيم من خطوة المتطلبات الأساسية لتكوين Microsoft Entra auth لهذا الجزء. ارجع إلى الملف النصي الذي حفظته من جلسة العمل هذه.

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 في جذر مشروعك. ألصق التعليمات البرمجية التالية فيه، مع تضمين القيم المتوفرة عند إنشاء مورد Immersive Reader لديك. لا تقم بتضمين علامات الاقتباس أو الأحرف { و } .

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;

يجب تأمين نقطة نهاية واجهة برمجة التطبيقات getimmersivereRlaunchparams باستخدام شكل من أشكال المصادقة (على سبيل المثال: OAuth) لمنع المستخدمين غير المصرح لهم من الحصول على الرموز المميزة لاستخدامها على خدمة القارئ الشامل والفواتير لديك؛ وهذا العمل يتجاوز نطاق هذا البرنامج التعليمي.

تشغيل القارئ الشامل مع عينة محتوى

افتح views\layout.pug، وأضف التعليمة البرمجية التالية ضمن العلامة head، قبل العلامة body. تعمل علامات script هذه على تحميل عدة تطوير برامج القارئ الشامل و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.
```
في 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.
استنساخ القارئ الشامل SDK من GitHub.

يمكنك تثبيت الأدوات التالية كجزء من الإرشادات الواردة في هذا الدليل:

Python ونظام pip. بدءاً من الإصدار Python 3.4، يتم تضمين pip بشكل افتراضي مع مثبّتات Python الثنائية.
قاروره
جينجا
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}

لا تثبّت هذا الملف في عنصر التحكم في المصدر، لأنه يتضمن أسراراً يجب ألا يُعلن عنها.

تأمين نقطة نهاية واجهة برمجة تطبيقات 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

ثبّت الوحدة النمطية للطلبات. يُقصد بالطلبات مكتبة HTTP مُرخصة من Apache2، مكتوبة بلغة 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 مثلاً، في مجلد "التطبيقات" الآن. افتح Terminal واستخدم 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 في نافذة Terminal جديدة.

ثبّت Flask.

pip install flask --user

ثبّت Jinja2. يمثل محرك قالب كامل الميزات لـ Python.

pip install Jinja2 --user

ثبّت virtualenv. تنشئ هذه الأداة بيئات Python المعزولة.

pip install virtualenv --user

ثبّت virtualenvwrapper. الغرض من virtualenvwrapper تيسير استخدام virtualenv.

pip install virtualenvwrapper --user

ثبّت الوحدة النمطية للطلبات. يُقصد بالطلبات مكتبة HTTP مُرخصة من Apache2، مكتوبة بلغة Python.

pip install requests --user

ثبّت الوحدة النمطية python-dotenv. تقرأ هذه الوحدة زوج قيم المفاتيح من ملف .env وتضيفها إلى متغير البيئة.

pip install python-dotenv --user

اختر مجلداً تريد الاحتفاظ ببيئاتك الظاهرية فيه، ثم شغّل هذا الأمر:

mkdir ~/.virtualenvs

استخدم cd للانتقال إلى مجلد عينة تطبيق 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.
استنساخ القارئ الشامل SDK من GitHub.
Android Studio.

تكوين بيانات اعتماد المصادقة

ابدأ تشغيل Android Studio، وافتح مشروع القارئ الشامل SDK من الدليل immersive-reader-sdk/js/samples/quickstart-java-android (Java) أو الدليل immersive-reader-sdk/js/samples/quickstart-kotlin (Kotlin).

تلميح

قد تحتاج إلى السماح للنظام بتحديث المكونات الإضافية Gradle إلى الإصدار 8 على الأقل.
لإنشاء مجلد أصول جديد، انقر بزر الماوس الأيمن فوق التطبيق وحدد المجلد ->مجلد الأصول من القائمة المنسدلة.
انقر بزر الماوس الأيمن فوق assets وحدد New ->File. قم بتسمية الملف env.
أضف الأسماء والقيم التالية، وقيم العرض حسب الاقتضاء. لا تثبّت هذا الملف في عنصر التحكم في المصدر، لأنه يتضمن أسراراً يجب ألا يُعلن عنها.
```
TENANT_ID=<YOUR_TENANT_ID>
CLIENT_ID=<YOUR_CLIENT_ID>
CLIENT_SECRET=<YOUR_CLIENT_SECRET>
SUBDOMAIN=<YOUR_SUBDOMAIN>
```

بدء تشغيل القارئ الشامل بعينة محتوى

اختر محاكي جهاز من AVD Manager، ثم شغّل المشروع.

الخطوات التالية

استكشاف القارئ الشامل SDK

المتطلبات الأساسية

اشتراك Azure. يمكنك إنشاء حسابًا مجانيًا.
مورد القارئ الشامل تم تكوينه لمصادقة Microsoft Entra. اتبع هذه التعليمات لضبط الإعدادات. احفظ إخراج جلسة العمل في ملف نصي حتى تتمكن من تكوين خصائص البيئة.
macOS وXcode.
Git.
استنساخ القارئ الشامل SDK من GitHub.

تكوين بيانات اعتماد المصادقة

في Xcode، حدد Open Existing Project. افتح الملف 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

Share via

طريقة تشغيل القارئ الشامل

المتطلبات الأساسية

أنشئ تطبيق ويب Node.js باستخدام Express

إعداد المصادقة

تشغيل القارئ الشامل مع عينة محتوى

تحديد لغة محتواك

تحديد لغة واجهة القارئ الشامل

تشغيل القارئ الشامل بمحتوى رياضيات

الخطوة التالية

المتطلبات الأساسية

تكوين بيانات اعتماد المصادقة

إنشاء تطبيق ويب Python على Windows

بدء تشغيل القارئ الشامل بعينة محتوى

أنشئ تطبيق ويب Python على OSX

بدء تشغيل القارئ الشامل بعينة محتوى

الخطوة التالية

المتطلبات الأساسية

تكوين بيانات اعتماد المصادقة

بدء تشغيل القارئ الشامل بعينة محتوى

الخطوات التالية

المتطلبات الأساسية

تكوين بيانات اعتماد المصادقة

بدء تشغيل القارئ الشامل بعينة محتوى

الخطوة التالية

الموارد الإضافية