مستودع الويب

باستخدام "مهام التطبيقات"، يمكن للمستخدمين الانتقال مباشرةً إلى محتوى تطبيقك بقول عبارات مثل "Ok Google، أريد الاطّلاع على قائمة 3 Dot Cafe على ExampleApp". تُسمّى هذه الوظيفة الربط بصفحة معيّنة، ويمكنها أن تسهّل على المستخدمين تنفيذ مهامهم باستخدام تطبيقك.

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

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

المزايا

يقدم مستودع الإعلانات على الويب مزايا للتطبيقات التي تحتوي على قوائم كبيرة ومحدثة بانتظام بالعناصر التي يشاهدها المستخدمون أو يطلبونها في التطبيق:

  • تتوفّر بيانات المستودع على الويب في موقعك الإلكتروني، على عكس بيانات المستودع المضمّن التي تخزِّن قوائم العناصر في تطبيقك. ويؤدي السماح لخدمة "مساعد Google" بالوصول إلى بيانات الويب إلى تجنُّب خطر بيانات المستودع المضمّنة القديمة التي لا يمكن تعديلها إلا من خلال نشر إصدار جديد من التطبيق.

  • تقتصر المستودعات المضمّنة على 1,000 سلعة. وعلى النقيض من ذلك، لا يوجد لمستودع الويب حد لعدد العناصر، ويمكن أن ينمو وفقًا لاحتياجاتك.

  • يمكن لمستودع الإعلانات على الويب تبسيط منطق التطبيق من خلال السماح لعملية تنفيذ الطلبات بمعالجة عناوين URL للمحتوى الذي يمكن توقّعه فقط والتي تم استردادها من موقعك الإلكتروني. في المقابل، في حال عدم إعداد المستودع، ينشئ "مساعد Google" روابط لصفحات معيّنة في التطبيق من خلال ربط معلَمات الغرض بالمتغيّرات في نموذج عنوان URL. بعد ذلك، يجب تحليل عنوان URL الذي يتم إنشاؤه ديناميكيًا لتحديد ما إذا كان المستخدم قد طلب كيانًا متوافقًا في تطبيقك.

طريقة العمل

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

تتوفر ثلاث طرق لإنشاء روابط لصفحات في التطبيق من أجل التنفيذ:

  • ربط المَعلمات: معلَمات الغرض من ربط العناصر النائبة في نموذج عنوان URL للتنفيذ.
  • المستودع المضمّن: يطابق مَعلمات الأهداف مع قائمة entities المتوافقة المحدّدة في التطبيق.
  • المستودع على الويب: يطابق معلَمات النية مع المحتوى الموجود في فهرس "بحث Google" الخاص بالموقع الإلكتروني.

مستودع الويب هو نمط عنوان URL للموقع الإلكتروني يحدده المطوّر، مثل https://www.exampleapp.com/restaurants/.*، ويمثّل مجموعة كيانات متوافقة مع أحد التطبيقات.

في حال ضبط معلَمة BII لمستودع على الويب، يطلب "مساعد Google" من الموقع الإلكتروني لإجراء مطابقة كيان مع طلب بحث المستخدم. بعد ذلك، يمرِّر "مساعد Google" نتائج عناوين URL المطابقة لنمط عنوان URL الذي تم ضبطه، مثل https://www.exampleapp.com/restaurants/three-dot-cafe، إلى عملية التنفيذ.

الشكل 1. مثال على طلب بحث "مساعد Google" باستخدام المستودع على الويب لاسترداد عنصر من كيان المطعم.

الأغراض المضمَّنة المتاحة

يتم دعم مستودع الويب، لمعلمات أهداف معيّنة، من خلال مؤشرات BII التالية:

  • [actions.intent.CREATE_REVIEW]
  • [actions.intent.GET_NEWS_ARTICLE]
  • [actions.intent.GET_REVIEW]
  • [actions.intent.GET_THING]
  • [actions.intent.ORDER_MENU_ITEM]
  • [actions.intent.GET_EXERCISE_PLAN]
  • [actions.intent.GET_DIGITAL_DOCUMENT]
  • [actions.intent.GET_ITEM_LIST]
  • [actions.intent.GET_OFFER]
  • [actions.intent.CREATE_OFFER]
  • [actions.intent.GET_PRODUCT]
  • [actions.intent.UPDATE_CART]
  • [actions.intent.CREATE_SOCIAL_MEDIA_CONNECTION]
  • [actions.intent.GET_IMAGE_OBJECT]
  • [actions.intent.GET_SOCIAL_MEDIA_POSTING]
  • [actions.intent.GET_SOCIAL_MEDIA_PROFILE]
  • [actions.intent.CREATE_TAXI_RESERVATION]
  • [actions.intent.CREATE_FLIGHT_RESERVATION]
  • [actions.intent.CREATE_LODGING_RESERVATION]
  • [actions.intent.GET_LOCAL_BUSINESS]
  • [actions.intent.GET_RESERVATION]
  • [actions.intent.UPDATE_RESERVATION]

إضافة مستودع على الويب

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

لاستخدام مستودع على الويب في BII معتمد، اتبع الخطوات التالية:

  1. في ملف shortcuts.xml لتطبيقك، أضِف علامة <capability> مع ضبط السمة android:name على اسم مؤشر BII يتم التعامل معه باستخدام مستودع الإعلانات على الويب، مثل actions.intent.ORDER_MENU_ITEM.

  2. في العلامة <capability>، أضِف علامة <intent> مع ضبط السمة android:action على اسم العرض ليتم تفعيله باستخدام هذا الغرض.

  3. في علامة <intent> نفسها، أضِف علامة <parameter> واضبط السمة android:name الخاصة بها على معلَمة BII الأكثر تطابقًا مع الكيان الذي تعرضه صفحاتك على الويب. على سبيل المثال، عند تقديم مستودع على الويب للسمة ORDER_MENU_ITEM، عليك ربط صفحات القائمة بـ menuItem.name.

  4. في العلامة <parameter> الجديدة، يجب إضافة علامة <data> وضبط السمة android:pathPattern الخاصة بها على نمط عنوان URL للمسار الذي تريد استخدامه للمستودع على الويب.

عند ضبط shortcuts.xml باتّباع هذه الخطوات، سيكون بإمكان "مساعد Google" استرداد محتوى الويب من فهرس "بحث Google" لنمط عنوان URL الذي قدّمته في السمة android:pathPattern. بعد ذلك، يقدّم "مساعد Google" قيمة عنوان URL لعملية التنفيذ باستخدام النتائج التي تتطابق مع نمط مسار عنوان URL الذي حدّدته. بعد ذلك، يوجّه التطبيق المستخدم إلى مكان محدّد في التطبيق استنادًا إلى بيانات عنوان URL التي يوفّرها "مساعد Google".

على سبيل المثال، يحتوي موقعك الإلكتروني على بيانات منتجات تستخدم مسار عنوان URL يبدأ بـ https://www.examplecafe.com/items/. تستخدم https://www.examplecafe.com/items/.* القيمة pathPattern، ويستخدم "مساعد Google" نمط عنوان URL هذا في بحث الويب للعثور على عنوان URL لتوفير الطلبات، مثل https://www.examplecafe.com/items/item123.

إذا عثر "مساعد Google" على عنوان URL مطابق لمستودع الويب، سيقدّم عنوان URL في الحقل <data> من نية تنفيذ الطلب، كما لو كان رابطًا لصفحة في التطبيق. استخدِم الإجراء getData() للهدف للحصول على عنوان URL ككائن Uri. ويكون النشاط على التطبيق الذي يتلقّى الغرض مسؤولاً عن تفسير عنوان URL وتفعيل واجهة المستخدم المناسبة للتطبيق.

مثال على ملف shortcuts.xml

يحدّد النموذج التالي نموذج ORDER_MENU_ITEM BII يوفّر مستودعًا على الويب لعرض نتائج عناوين URL للطلبات التي تحتوي على معلَمة menuItem.name BII:

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.ORDER_MENU_ITEM">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.OrderMenuItemActivity">
      <!-- Define URL match pattern in the pathPattern data field -->
      <parameter android:name="menuItem.name">
        <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
      </parameter>
    </intent>
  </capability>
</shortcuts>

في النموذج أعلاه، تم تحديد pathPattern للسمة menuItem.name، ما يؤدي إلى توجيه "مساعد Google" إلى عرض عناوين URL التي تتطابق فقط مع نمط عنوان URL: https://www.examplecafe.com/items/.*

تتوفّر المزيد من أمثلة shortcuts.xml على BII التي تتوافق مع المستودع على الويب في المستندات المرجعية.

معالجة الإجراء الاحتياطي للنتائج المفقودة

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

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

يمكنك التعامل مع قيم المَعلمات المفقودة من خلال تحديد عناصر <intent> متعددة لإحدى الإمكانيات. وإذا لم يتمكّن "مساعد Google" من تحقيق الغرض الأول، يعود إلى الغرض التالي، وهكذا.

يجب ألا تتطلب الأغراض الاحتياطية معلَمات. بدلاً من ذلك، يجب أن تتضمن هذه الإمكانية رابطًا عامًا أكثر عمومية لصفحة في التطبيق، مثل عرض نتائج البحث لطلب بحث المستخدم.

في نموذج shortcuts.xml التالي، يحدّد ORDER_MENU_ITEM BII عمليتَي تنفيذ: الأول يتوقع عنوان URL من المعلَمة menuItem.name. أما الطريقة الثانية فلا تتطلب أي معلمات، وهي توجيه المستخدم إلى صفحة تعرض جميع عناصر القائمة.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
    </parameter>
  </intent>
  <!-- Fallback intent with no required parameters -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ViewMenuActivity">
    <url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
  </intent>
</capability>

في الحالات التي لا يتم فيها عرض عنوان URL لمستودع الويب، قد يستمر استخدام محتوى طلب بحث المستخدم لأغراض احتياطية، مثل عرض نتائج البحث.

في نموذج shortcuts.xml التالي، تم تعريف عنصرَي هدف:

  1. يتطلب الأول رابطًا لموضع معيّن لمستودع الويب من المعلمة menuItem.name.
  2. إذا لم يتم عرض رابط لصفحة في التطبيق، سيعرض الغرض الثاني نتائج البحث، باستخدام طلب بحث المستخدم من menuItem.name، في حال توفّره.
<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- Fallback intent displaying search results, using "menuItem.name" -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.SearchMenuActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

إضافة البحث داخل التطبيق باستخدام مستودع الويب

يمكنك السماح للمستخدمين بالبحث عن محتوى الويب في تطبيقك من خلال الجمع بين المستودع الإعلاني على الويب وتطبيق actions.intent.GET\_THING BII.

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

بالنسبة إلى نماذج المستودع على الويب shortcuts.xml، يمكنك الاطّلاع على مرجع GET\_THING BII.

اختبار مستودع الويب

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

في النموذج التالي من ORDER_MENU_ITEM BII، ينشئ "مساعد Google" روابط تنفيذ مستودع على الويب تتطابق مع نمط urlFilter المحدّد في المَعلمة menuItem.name، على سبيل المثال: https://www.examplecafe.com/items/nuggets. يستخدم الغرض الثاني قيمة menuItem.name ويُجري بحثًا إذا تعذّر تطابق الغرض الأول مع نمط عنوان URL.

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <!-- web inventory fulfillment -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- search intent -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MenuSearchActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

استخدِم أداة اختبار الإجراءات في التطبيقات لاختبار مستودع المواقع الإلكترونية على جهاز فعلي أو افتراضي.

لاستخدام أداة الاختبار، يُرجى اتباع الخطوات التالية:

  1. عليك ربط جهاز الاختبار بتطبيقك قيد التشغيل.
  2. في "استوديو Android"، انتقِل إلى الأدوات > الإجراءات في التطبيقات > أداة اختبار الإجراءات في التطبيقات.
  3. انقر على إنشاء معاينة.
  4. في "استوديو Android"، شغِّل تطبيقك على جهاز الاختبار.
  5. استخدِم تطبيق "مساعد Google" على جهاز الاختبار لاختبار "مهمتك في التطبيق". على سبيل المثال، يمكنك أن تقول شيئًا مثل "Ok Google، أريد طلب قطعة ناجتس على ExampleCafe".
  6. راقِب سلوك تطبيقك أو استخدِم برنامج تصحيح الأخطاء في "استوديو Android" للتحقّق من نتيجة الإجراء المطلوبة.