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

1. نظرة عامة

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

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

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

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

ما الذي ستقوم ببنائه

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

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

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

ما ستتعرَّف عليه

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

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

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

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

تتيح ميزة "مهامّ في التطبيقات" ربط المستخدمين من "مساعد Google" بتطبيقك على Android. ولكن كيف تعمل؟

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

عندما يقول المستخدم طلبًا إلى "مساعد Google"، يُجري "مساعد Google" تحليلاً لإدخال المستخدم ويطابقه مع الغرض من "المهام مع مساعد 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 الافتراضية، يُرجى الاطّلاع على مقالة إنشاء الأجهزة الافتراضية وإدارتها.

صورة متحركة تعرض نموذجًا لتطبيق قائمة المهام

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

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

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

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

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

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

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

تحديد إمكانية Get Thing

أثناء تنفيذ إجراء مرتبط بالبحث، يستخلص "مساعد 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 intent يؤدي إلى تشغيل التطبيق استجابةً لمؤشر BII.
    • ويتم تحديد النشاط باستخدام targetPackage وtargetClass.
    • تم ربط مَعلمة BII thing.name بعنصر Intent Extra باسم 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 في هذا الدرس التطبيقي. بعد تنفيذ نموذج 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 معًا، لذلك عند تفعيل ميزة "فتح التطبيق"، سيتم تفعيل هدف Android.

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

التعامل مع مَعلمات الأهداف باستخدام المستودع المضمّن

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

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

للتعامل مع معلَمة intent 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 intent.

اختبار إجراء تطبيقك

أثناء عملية التطوير والاختبار، يمكنك استخدام مكوّن "مساعد Google" الإضافي لمعاينة "مهمة التطبيق" باستخدام "مساعد Google" على جهاز اختبار. ويمكنك أيضًا استخدام الأداة لتعديل مَعلمات intent لإجراء تطبيق من أجل اختبار طريقة تعامل هذا الإجراء مع الطرق المختلفة التي قد يطلب المستخدم من "مساعد 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 لمشاركة ما أنجزته.

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

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