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

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

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

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

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

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

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

الشكل 1. رسم بياني للتدفق لإحدى الميزات START_EXERCISE التي تستخدم مستودع مضمّن لتفسير أسماء التمارين المقدَّمة من المستخدم للمعايير المتاحة أنواع التمارين الرياضية في التطبيق.

ملاحظة: تتم إتاحة المستودع المضمّن من خلال مَعلمات محدَّدة. وBII. لمعرفة التفاصيل، يُرجى الرجوع إلى "المستودع الإعلاني" لكل برنامج BII مدى التوفّر حسب الحقل" في مرجع BII.

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

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

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

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

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

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

إنشاء مستودع مضمّن

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

• Ok Google، أريد بدء تمرين الجري على Example App.
• Ok Google، أريد بدء ركض خفيف على تطبيق Example.

في اختصار المستودع المضمّن، يمكنك ضبط shortcutId على "CARDIO_RUN"، معرِّف التمرين المتوقع من تطبيقك. ثم تحدد "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

ملاحظة: يتيح المستودع المضمّن استخدام parameter واحدة كحد أقصى لكل طريقة توفّر. العنصر intent في capability.

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

يوفّر الاختصار تلقائيًا 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 للاختصار المرتبط في التنفيذ.

ملاحظة: كل مستودع إعلاني مضمّن <shortcut> مخصّص لتنفيذ الاختصارات. يجب أن يحتوي على طريقة تنفيذ <intent>. لتجنُّب الأخطاء في توصيل الطلبات، عدم استخدام اختصارات لا تحتوي على عناصر intent للاختصار توصيل الطلبات.

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

على الرغم من أنّ المستودع المضمّن هو بشكل عام إمكانية اختيارية لمعرّفات BII التي التي تدعمها، فهي مطلوبة لمعرّفات BII معيّنة، مثل OPEN_APP_FEATURE. هذا النمط يتيح BII الشائعة الاستخدام للمستخدمين إنشاء روابط تؤدي إلى ميزات محددة في التطبيق باستخدام "مساعد 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" تنفيذ مجموعة متنوعة من العبارات الخاصة بالميزة نفسها:

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

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

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

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

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

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