توسيع نطاق وصول تطبيق Android ليشمل "مساعد Google" باستخدام ميزة "مهامّ في التطبيقات" (المستوى 2)

1. نظرة عامة

تتيح "إجراءات التطبيقات" للمستخدمين تشغيل ميزات معيّنة في التطبيق مباشرةً من "مساعد Google" لمساعدتك في توسيع نطاق وصول تطبيق Android. بصفتك مطوّر تطبيقات Android، يمكنك تنفيذ إمكانات تتيح لـ "مساعد Google" معرفة نوع الوظائف المتاحة للمستخدمين وكيفية تنفيذ هذه الطلبات.

في أول درس تطبيقي حول "مهامّ في التطبيقات"، تعلّمت كيفية توسيع نطاق "مساعد Google" ليشمل تطبيقًا تجريبيًا للياقة البدنية من خلال تنفيذ الأهداف المضمّنة (BII) من فئة الأهداف المضمّنة المتعلقة بالصحة واللياقة البدنية. يتم تنظيم BII في فئات تمثّل أنواع المهام التي يطلب المستخدمون غالبًا من "مساعد Google" تنفيذها.

في هذا الدرس التطبيقي حول الترميز، ستتعلّم كيفية إضافة "مهامّ في التطبيقات" إلى تطبيق باستخدام واجهات BII من فئة واجهات BII "الشائعة"، والتي تمثّل مهام التطبيقات الشائعة التي يمكن لأي تطبيق Android تقريبًا تنفيذها.

يتناول هذا الدرس التطبيقي حول الترميز مفاهيم متوسّطة المستوى للتطوير باستخدام "مهامّ في التطبيقات". يجب أن يكون لديك خبرة سابقة في تطوير تطبيقات Android وتنفيذ أغراض Android.

ما ستنشئه

في هذا الدرس التطبيقي حول الترميز، ستضيف واجهتَي برمجة تطبيقات شائعتَين مدمجتَين (BII) إلى نموذج تطبيق "قائمة المهام"، ما يتيح للمستخدمين أن يطلبوا من "مساعد Google" إجراء ما يلي:

ثلاث شاشات متتالية يعرض فيها "مساعد Google" المهام النشطة في أحد التطبيقات

الشكل 1: ثلاث شاشات متتالية يعرض فيها "مساعد Google" المهام النشطة في أحد التطبيقات

أهداف الدورة التعليمية

ستتعلّم كيفية استخدام نوايا الشراء المضمّنة في الفئة "شائعة" لتوسيع نطاق استخدام "مساعد Google" ليشمل معظم تطبيقات Android. ستتعرّف أيضًا على كيفية اختبار واجهات BII الشائعة باستخدام المكوّن الإضافي لـ "مساعد Google" في "استوديو Android".

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

في هذا الدرس التطبيقي حول الترميز، ستستخدم جهاز Android (فعليًا أو افتراضيًا) لاختبار إجراءاتك. في حال استخدام جهاز فعلي، تأكَّد من أنّه متصل بجهاز التطوير المحلي. يجب أيضًا تسجيل الدخول إلى تطبيق Google على الجهاز، وتسجيل الدخول إلى "استوديو Android" باستخدام حساب Google نفسه. يجب أيضًا أن يكون تطبيق "مساعد Google" مثبَّتًا على الجهاز.

2. التعرّف على طريقة العمل

تربط "مهامّ في التطبيقات" المستخدمين من "مساعد Google" بتطبيق Android، ولكن كيف تعمل؟

عندما يطلب المستخدم من "مساعد Google" استخدام تطبيقك، يبحث "مساعد Google" عن مهامّ في التطبيقات المسجّلة في تطبيقك من ملف shortcuts.xml. يحتوي هذا الملف على إمكانات التطبيق التي تربط هدفًا مضمّنًا أو مخصّصًا في "مساعد Google" بغرض Android أو رابط لصفحة في التطبيق.

عندما يوجّه المستخدم طلب بحث إلى "مساعد Google"، يحلّل "المساعد" إدخال المستخدم ويطابقه مع هدف "مهامّ في التطبيقات" (في هذا الدرس التطبيقي حول الترميز، سيكون هدفًا مضمّنًا). يعرف "مساعد Google" الإمكانات التي يتيحها تطبيقك من خلال ملف shortcuts.xml في تطبيق Android. وعند مطابقة الغرض، تحتوي الإمكانية التي تتضمّن واجهة BII على الطريقة التي تريد بها تنفيذ هذا الطلب. في هذا الدرس التطبيقي حول الترميز، يكون التنفيذ عبارة عن هدف Android يطلق نشاطًا في تطبيقك.

يوضّح المخطّط البياني التالي مسار "مساعد Google" هذا:

مخطط يوضّح كيفية معالجة "مساعد Google" لطلب بحث صوتي من المستخدمالشكل 2. مخطط يوضّح كيفية معالجة "مساعد Google" لطلب بحث صوتي

يحتوي ملف shortcuts.xml المشروع على المعلومات التالية لكل "إجراء تطبيق":

  • النية المضمّنة أو النية المخصّصة التي يستخدمها "إجراء التطبيق"
  • نشاط Android أو الرابط لصفحة في التطبيق الذي يجب تقديمه للمستخدم
  • كيفية ربط مَعلمات خريطة الأهداف المضمّنة بالمعلومات التي يقدّمها المستخدم إلى "مساعد Google"

بعد ذلك، يتم فلترة نشاط Android والتعامل مع هدف Android أو الرابط لصفحة في التطبيق المقدَّمَين لتزويد المستخدم بالوظيفة المطلوبة. والنتيجة هي تجربة مستخدم يستدعي فيها "مساعد Google" وظائف تطبيقك استجابةً لطلب المستخدم.

3- إعداد بيئة التطوير

يستخدم هذا الدرس التطبيقي حول الترميز تطبيق قائمة المهام النموذجية لنظام التشغيل Android. يمكن لنموذج التطبيق هذا إضافة عناصر إلى قوائم المهام والبحث عن عناصر حسب الفئة وعرض معلومات حول المهام المكتملة.

تنزيل ملفاتك الأساسية

نفِّذ الأمر التالي لاستنساخ مستودع GitHub الخاص بالتطبيق النموذجي:

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

بعد استنساخ المستودع، اتّبِع الخطوات التالية لفتحه في استوديو Android:

  1. في مربّع الحوار مرحبًا بك في "استوديو Android"، انقر على استيراد مشروع.
  2. ابحث عن المجلد الذي نسخت المستودع فيه واختَره.

للاطّلاع على إصدار من التطبيق يمثّل درسًا تطبيقيًا حول الترميز مكتملًا، استنسِخ مستودع نموذج التطبيق باستخدام العلامة --branch master.

تعديل معرّف تطبيق Android

يؤدي تعديل معرّف التطبيق إلى تحديد التطبيق بشكلٍ فريد على جهاز الاختبار وتجنُّب الخطأ "اسم حزمة مكرّر" في حال تحميل التطبيق إلى Play Console. لتعديل معرّف التطبيق، افتح app/build.gradle:

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

استبدِل "MYUNIQUENAME" في الحقل applicationId باسم فريد خاص بك.

اختبار التطبيق على جهازك

قبل إجراء المزيد من التغييرات على التطبيق، من المفيد التعرّف على إمكانات التطبيق النموذجي. لتشغيل التطبيق على المحاكي، اتّبِع الخطوات التالية:

  1. في "استوديو Android"، اختَر تشغيل > تشغيل التطبيق أو انقر على تشغيل في شريط الأدوات.
  2. في مربّع الحوار اختيار هدف النشر، اختَر جهازًا وانقر على حسنًا. إصدار نظام التشغيل Android 10 (المستوى 30 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث هو الإصدار المُوصى به، على الرغم من أنّ "الإجراءات" تعمل على الأجهزة التي تعمل بالإصدار Android 5 (المستوى 21 لواجهة برمجة التطبيقات).
  3. اضغط مع الاستمرار على زر الشاشة الرئيسية لإعداد "مساعد Google" والتأكّد من عمله. عليك تسجيل الدخول إلى "مساعد Google" على جهازك إذا لم يسبق لك ذلك.

لمزيد من المعلومات حول الأجهزة الافتراضية التي تعمل بنظام التشغيل Android، يُرجى الاطّلاع على إنشاء الأجهزة الافتراضية وإدارتها.

صورة متحركة توضّح نموذج تطبيق Todo list

الشكل 3: صورة متحركة توضّح نموذج تطبيق "قائمة المهام".

استكشِف التطبيق سريعًا لمعرفة إمكاناته. يؤدي النقر على رمز علامة الجمع إلى إنشاء عنصر مهمة جديد، وتتيح لك عناصر القائمة في أعلى يسار الشاشة البحث عن عناصر المهام وفلترتها حسب حالة الإكمال.

تثبيت المكوّن الإضافي التجريبي

تتيح لك إضافة "مساعد Google" اختبار "مهامّ في التطبيقات" على جهاز اختباري. إذا لم تكن لديك أداة الاختبار، ثبِّتها باتّباع الخطوات التالية:

  1. انتقِل إلى ملف > الإعدادات (استوديو Android > الإعدادات المفضّلة على نظام التشغيل MacOS).
  2. في قسم "المكوّنات الإضافية"، انتقِل إلى Marketplace وابحث عن "مساعد Google".يمكنك أيضًا تنزيل أداة الاختبار وتثبيتها يدويًا.
  3. ثبِّت الأداة وأعِد تشغيل "استوديو Android".

4. إضافة إمكانية Get Thing BII

توسّع actions.intent.GET_THING ميزة "البحث داخل التطبيق" لتشمل "مساعد Google". في هذه الخطوة، ستنفّذ GET_THING BII وتختبرها، ما يتيح للمستخدمين البحث عن مهام معيّنة في نموذج التطبيق.

تحديد إمكانية "الحصول على عنصر"

أثناء "إجراء التطبيق" المرتبط بالبحث، يستخرج "مساعد Google" عبارات البحث من طلب المستخدم إلى المَعلمة thing.name BII، ثم يمرّر هذه القيمة إلى تطبيق Android.

لإضافة GET_THING BII إلى تطبيقك، عدِّل shortcuts.xml، الذي يقع في دليل مشروع نموذج app/src/main/res/xml، باستخدام عنصر <capability> ضمن علامة <shortcuts> ذات المستوى الأعلى:

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

الإعدادات أعلاه:

  1. توضّح هذه السمة أنّ التطبيق يستجيب إلى GET_THING BII.
  2. تحدّد هذه السمة كيفية إنشاء هدف Android يؤدي إلى تشغيل التطبيق استجابةً لواجهة BII هذه.
    • يتم تحديد النشاط باستخدام targetPackage وtargetClass.
    • يتم ربط المَعلمة thing.name الخاصة بواجهة BII بالـ Extra في Intent الذي يحمل الاسم q.

يجب أن يكون النشاط المُسمّى متوفّرًا في بيان التطبيق وتم تصديره.

يحتوي تطبيق Android المقدَّم على بيانات وصفية، لذا فإنّ ملف AndroidManifest على دراية بملف shortcuts.xml:

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

اختبار "إجراء التطبيق"

لاختبار ميزة البحث داخل التطبيق من "مساعد Google"، اتّبِع الخطوات التالية:

  1. تأكَّد من اتصال جهاز Android.
  2. انتقِل إلى الأدوات > "مساعد Google" > "أداة اختبار مهامّ في التطبيقات".
  3. انقر على إنشاء معاينة لقبول القيم التلقائية لكلّ من اسم التطبيق واللغة. راجِع سياسات وبنود خدمة "مهامّ في التطبيقات" واقبلها إذا طُلب منك ذلك.
  4. في الخطوة الأولى التي تطلب منك فيها الأداة اختيار معلومات بناء الهوية (BII) وإعدادها، انقر على actions.intent.GET_THING. غيِّر قيمة name من running shoes إلى milk.
  5. انقر على تنفيذ إجراء التطبيق.

في هذا الاختبار، تستخدم GET_THING واجهة BII السمة name للبحث في التطبيق عن مهام تتضمّن كلمة "حليب". كما هو الحال مع "إجراء التطبيق" السابق، يمكنك اختبار الإجراء باستخدام أداة الاختبار، أو يمكنك ببساطة قول "Ok Google، ابحث عن خليط الكيك في قائمة المهام" أو عبارات بحث أخرى على جهاز الاختبار.

5- إضافة إمكانية BII لميزة "فتح التطبيق"

في هذه الخطوة، عليك تنفيذ واجهة BII الخاصة بميزة "فتح التطبيق"، ما يتيح للمستخدمين عرض مهامهم النشطة والمكتملة باستخدام "مساعد Google". لإجراء ذلك، أكمِل إمكانية shortcuts.xml التي تحتوي على معلومات حول كيفية تشغيل الإمكانية وكيفية تمرير المَعلمات وعناصر Android التي يجب استدعاؤها. في هذا الدرس التطبيقي، ستستخدم OPEN_APP_FEATURE BII. بعد تنفيذ هذه النية المضمّنة، اختبِر الإجراء على جهازك.

إضافة إمكانية ميزة "فتح التطبيق"

أضِف إمكانية ثانية لميزة "فتح التطبيق" في shortcuts.xml أسفل عنصر Get Thing Capability:

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

تربط هذه الإمكانية بين BII الخاصة بميزة "فتح التطبيق" وAndroid intent، وبالتالي عند تفعيل ميزة "فتح التطبيق"، سيتم تفعيل Android intent.

قبل بدء تنفيذ Android intent، يتم استخراج المَعلمات المتوافقة من إدخال المستخدم. تتيح OPEN_APP_FEATURE BII مَعلمة واحدة، feature، تمثّل ميزة التطبيق المستخرَجة من طلب بحث المستخدِم. هناك نوعان من الميزات التي سيتيحها هذا التطبيق: "المَهمّة النشطة" و"المَهمّة المكتملة". تتيح هذه الميزات للمستخدمين فتح التطبيق مع عرض مُصفّى لقائمة المهام. يجب استخدام المستودع الإعلاني المضمّن للاستفادة من هذه الميزات.

التعامل مع مَعلمات الغرض باستخدام المستودع الإعلاني المضمّن

تمثّل مَعلمات النية العناصر المستخرَجة من طلب بحث المستخدم. على سبيل المثال، إذا قال المستخدم عبارة مثل "Ok Google، أريد طلب بيتزا من ExampleApp"، يستخرج "مساعد Google" كلمة "بيتزا" إلى مَعلمة هدف food.item schema.org، ويمرّر المَعلمة إلى الإجراء الذي تتخذه للتعامل معها.

تتيح ميزة "فتح التطبيق" في BII مَعلمة واحدة، وهي feature، تمثّل ميزة التطبيق المستخرَجة من طلب بحث المستخدم. يجب توفير مستودع إعلاني مضمّن لهذه المَعلمة، ما يوفّر لمساعد Google مجموعة من أسماء ميزات التطبيق المتوافقة لمطابقة قيمة المَعلمة.

للتعامل مع مَعلمة الغرض feature، أضِف اختصارًا إلى shortcuts.xml باستخدام الرمز التالي فوق إمكانية ميزة "فتح التطبيق":

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

في الرمز أعلاه، حدّدت مستودعًا إعلانيًا مضمّنًا، يتم تمثيله كعناصر shortcut مع إمكانية ربط المَعلمات. يمكن استخدام الاختصارات كمستودع لمعلَمات BII. يطابق "مساعد Google" طلب المستخدم مع القيم في ربط المَعلمات في "الاختصارات". بالنسبة إلى قيمة مَعلمة مطابِقة، ستتم إضافة shortcutId إلى نية التنفيذ. عندما يفعّل المستخدم OPEN_APP_FEATURE BII بطلب، يطابق "مساعد Google" قيمة مَعلمة الميزة مع سمة القيمة الخاصة بالاختصار، وينقل القيمة إلى targetClass كـ parameter في Extra.

على سبيل المثال، إذا قال المستخدم "Ok Google، اعرض لي المهام المكتملة في ExampleApp"، يطابق "مساعد Google" قيمة مَعلمة الغرض من الميزة، أي "المهام المكتملة"، مع اختصار المستودع المطابق، والذي ينقل هذه القيمة إلى إمكانية OPEN_APP_FEATURE. بعد ذلك، يفعّل "مساعد Google" هدف Android.

اختبار "إجراء التطبيق"

أثناء عملية التطوير والاختبار، يمكنك استخدام المكوّن الإضافي "مساعد Google" لمعاينة "إجراءات التطبيق" باستخدام "مساعد Google" على جهاز اختبار. يمكنك أيضًا استخدام الأداة لتعديل مَعلمات النية الخاصة بـ "إجراء في التطبيق"، وذلك لاختبار كيفية تعامل الإجراء مع الطرق المختلفة التي قد يطلب بها المستخدم من "مساعد Google" تنفيذه.

لاختبار "إجراءات التطبيق" باستخدام أداة الاختبار، اتّبِع الخطوات التالية:

  1. توصيل جهاز اختبار Android الفعلي أو بدء محاكي Android
  2. إذا لم تكن أداة الاختبار ظاهرة، افتحها من خلال الانتقال إلى الأدوات > "مساعد Google" > "أداة اختبار مهامّ في التطبيقات".
  3. انقر على الزر تعديل لإعادة تحميل المعاينة.
  4. في الخطوة الأولى التي تطلب منك فيها الأداة اختيار معلومات بناء الهوية (BII) وإعدادها، انقر على actions.intent.OPEN_APP_FEATURE.
  5. في مربّع الميزة، عدِّل القيمة التلقائية History إلى Completed tasks.
  6. انقر على تنفيذ إجراء التطبيق.

كحلّ بديل، يمكنك استخدام اسم الاستدعاء مباشرةً في تطبيق "مساعد Google" على جهازك لتجربة "إجراء التطبيق". على سبيل المثال، يمكنك قول "Ok Google، أريد عرض المهام المكتملة في قائمة المهام".

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

تهانينا!

يمكنك الآن تفعيل أي تطبيق Android تقريبًا للعمل مع "مساعد Google" باستخدام واجهات BII الشائعة.

المواضيع التي تناولناها

في هذا الدرس التطبيقي حول الترميز، تعلّمت ما يلي:

  • كيفية السماح للمستخدمين بالتعمّق في ميزات معيّنة في التطبيق باستخدام "مساعد Google"
  • كيف يمكن للمستخدمين الوصول إلى ميزة البحث داخل التطبيق من "مساعد Google"؟
  • كيفية اختبار BII الشائعة باستخدام المكوّن الإضافي لـ "مساعد Google"

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

من هنا، يمكنك محاولة إجراء المزيد من التحسينات على تطبيق "قائمة المهام". وللاطّلاع على المشروع المكتمل، راجِع مستودع الفرع الرئيسي على GitHub.

في ما يلي بعض الاقتراحات لمزيد من المعلومات حول توسيع نطاق هذا التطبيق باستخدام "مهام في التطبيقات":

لمواصلة رحلتك في "إجراءات Google"، يمكنك الاطّلاع على المراجع التالية:

تابِعنا على Twitter ‎@ActionsOnGoogle للاطّلاع على آخر إشعاراتنا، وغرِّد باستخدام ‎#AoGDevs لمشاركة ما أنشأته.

استطلاع لجمع الملاحظات

أخيرًا، يُرجى ملء هذا الاستطلاع لتقديم ملاحظات حول تجربتك مع هذا الدرس العملي.