عند تنفيذ "إجراءات في التطبيق" على تطبيق Android الخاص بك، قد تجد نفسك مضطرًا
إلى التعامل مع الطلبات المشتمِلة على أشكال مختلفة من مظهرك. على سبيل المثال، لنفترض أنّ
تطبيق اللياقة البدنية ينفّذ هدف START_EXERCISE
المضمَّن (BII) للسماح للمستخدمين ببدء مجموعة واسعة من التمارين، وذلك من خلال توجيه طلبات إلى "مساعد Google"، مثل
"Ok Google، أريد بدء الجري على Example App".
يتطلب تحقيق هذا الهدف مطابقة طلب منطقك للتعامل مع كل نوع من التمارين، بما في ذلك أشكال مثل "ركض" أو "سباق" أو "سباق". وسرعان ما يصبح هذا المنطق مرهقًا مع زيادة التمارين المتوافقة.
بالنسبة إلى معرّفات BII المتوافقة، مثل START_EXERCISE
، يمكنك تجنُّب منطق المطابقة المعقد هذا باستخدام مستودع مضمَّن. المستودع المضمَّن هو مجموعة من اختصارات Android الثابتة المحدّدة في shortcuts.xml
والتي تمثّل الميزات والمحتوى المتوفّر في تطبيقك.
يحتوي كل اختصار على معرّف عنصر وقائمة من المرادفات التي تمثل صيغًا مختلفة في الطريقة التي قد يشير بها المستخدمون إلى العنصر. أثناء الاستدعاء، تقارن BII معلمة BII التي يقدمها المستخدم بقائمة المرادفات. عند العثور على تطابق، يتم تحديث معلمة BII إلى معرّف عنصر الاختصار المطابق.
يتيح المستودع المضمّن لـ "مساعد Google" تبسيط قيم معلَمات BII التي يتم تقديمها إلى تطبيقك أثناء استدعاءات "إجراءات التطبيق".
دالة المستودعات المضمّنة مثل جداول البحث عن معلَمات BII، مع توضيح مجموعة متنوعة من الطرق التي يشير بها المستخدمون إلى ميزات أو محتوى في تطبيقك باستخدام معرّفات السلع التي تحدّدها. إنها تبسط منطق مطابقة طلبات تطبيقك عن طريق السماح لعمليات التنفيذ بتوقع معرفات العناصر من معلمات BII.
![مخطط بياني لتدفق مستخدم المستودع المضمّن](https://developer.android.com/static/guide/app-actions/images/appactions-inline-inventory-flow.png?authuser=7&hl=ar)
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" لتطبيقك أثناء تنفيذ "المهام في التطبيقات".