تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

المستودع المضمّن

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

يتطلب تحقيق هذا الهدف مطابقة طلب منطقك للتعامل مع كل نوع من التمارين، بما في ذلك أشكال مثل "ركض" أو "سباق" أو "سباق". وسرعان ما يصبح هذا المنطق مرهقًا مع زيادة التمارين المتوافقة.

بالنسبة إلى معرّفات BII المتوافقة، مثل START_EXERCISE، يمكنك تجنُّب منطق المطابقة المعقد هذا باستخدام مستودع مضمَّن. المستودع المضمَّن هو مجموعة من اختصارات Android الثابتة المحدّدة في shortcuts.xml والتي تمثّل الميزات والمحتوى المتوفّر في تطبيقك.

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

يتيح المستودع المضمّن لـ "مساعد Google" تبسيط قيم معلَمات BII التي يتم تقديمها إلى تطبيقك أثناء استدعاءات "إجراءات التطبيق".

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

مخطط بياني لتدفق مستخدم المستودع المضمّن — **الشكل 1.** مخطَّط انسيابي لإمكانات `START_EXERCISE` يستخدم مستودعًا مضمّنًا لتفسير أسماء التمارين التي يقدّمها المستخدمون لأنواع التمارين الرياضية المتوافقة في التطبيق

القيود والبدائل

تخضع اختصارات المستودع المضمّنة للقيود التالية:

حد الاختصارات: يمكن تحديد 1,000 اختصار من اختصارات المستودع المضمّن بحد أقصى لكل تطبيق.
الحدّ الأقصى للمرادفات: يمكن أن يحتوي كل اختصار للمستودع المضمّن على 20 قيمة مرادفة كحدّ أقصى.
التعريف الثابت: يتم تعريف اختصارات المستودع المضمّنة بشكل ثابت في shortcuts.xml ولا يمكن تعديلها للمستخدمين إلا من خلال نشر إصدار جديد من تطبيقك.

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

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

إنشاء مخزون مضمَّن

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

Ok Google، أريد بدء التشغيل على Example App.
Ok Google، أريد الجري على تطبيق "مثال".

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

وينفِّذ المقتطف التالي من نموذج ملف app/res/shortcuts.xml هذه الحالة:

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

في النموذج السابق، يعلن المستودع المضمّن shortcut عن علامة <parameter-binding> داخل عنصر <capability-binding>، لربطها بالمَعلمة exercise.name BII المحدّدة في <capability>.

يحدّد مورد مصفوفة السلاسل النصية @array/run_names قائمة بالمرادفات في res/values/arrays.xml التي يتعرّف عليها "مساعد Google" ويربطها بمعرّف عنصر "CARDIO_RUN":

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

عند توفير <url-template> للإمكانية، يتم إدراج shortcutId لقيمة مطابقة في عنوان URL الذي تم إنشاؤه في العنصر النائب المقابل للمَعلمة. وينفِّذ الرمز التالي من نموذج app/res/shortcuts.xml هذه الحالة:

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://workout{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

في النموذج السابق، يُنشئ "مساعد Google" الرابط لصفحة في التطبيق الخاص بالتنفيذ myapp://workout?exercise=CARDIO_RUN.

تنفيذ الطلب باستخدام أهداف الاختصارات

يوفّر الاختصار تلقائيًا shortcutId لقيمة مستودع مضمّنة متطابقة مع intent من capability الذي يرتبط به الاختصار، كما هو موضّح في علامة الاختصار <capability-binding>. يمكنك بدلاً من ذلك تحديد intent الذي تم تحديده في الاختصار نفسه لتنفيذه عن طريق إضافة علامة <shortcut-fulfillment> إلى capability.

ينفِّذ الرمز التالي من نموذج ملف app/res/shortcuts.xml تنفيذ الاختصار:

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

في النموذج السابق، إذا تطابق طلب بحث المستخدم مع قيمة مستودع مضمَّنة للمَعلمة exercise.name، تحدد العلامة <shortcut-fulfillment> أنّه يتم استخدام intent للاختصار المرتبط في التنفيذ.

مستودع مضمّن لميزة التطبيق المفتوح BII

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

ينفِّذ الرمز التالي من نموذج ملف app/res/shortcuts.xml عملية BII هذه من خلال اختصار واحد يمثّل ميزة حالة طلب التطبيق:

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

تحدّد موارد مصفوفة السلاسل في res/values/arrays.xml، @array/order_status_names، قائمة بمرادفات هذه الميزة:

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

مع توفّر الإمكانية السابقة في "مساعد Google"، يستطيع "مساعد Google" تنفيذ مجموعة متنوّعة من العبارات للميزة نفسها:

"Ok Google، أريد عرض حالة طلبي على تطبيق Example App".
"Ok Google، أريد عرض طلباتي على تطبيق Example App".
"Ok Google، أريد عرض سجلّ طلباتي على تطبيق "مثال".

اختبار المستودع المضمّن

اختبِر المستودع عن طريق فحص قيم مَعلمات BII التي يقدّمها "مساعد Google" لتطبيقك وتنفيذ إمكانات الإجراءات في التطبيق ذات الصلة. يعمل المستودع المضمّن عن طريق استبدال القيمة التي يقدّمها المستخدم لمَعلمة BII مرتبطة بالمستودع بالقيمة shortcutId لاختصار مطابق للمستودع المضمّن.

على سبيل المثال، قد تستخدم إمكانية START_EXERCISE BII مستودعًا مضمّنًا لترجمة معلَمة BII التي يقدّمها المستخدم "run" إلى رقم تعريف التمرين المقابل لها، "CARDIO_RUN".

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

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