إنشاءshortcut.xml

بعد تحديد الوظيفة داخل التطبيق والقصد المضمّن المرتبط بها (BII) المطلوب تنفيذه، عليك الإفصاح عن الوظائف المضمّنة التي تتيحها الوظيفة من خلال تعريف عنصر capability في ملف موارد shortcuts.xml. يؤدي تحديد عنصر BII كcapability إلى تسجيل توفّر هذا الإجراء الدلالي في تطبيقك، ويؤدي إلى تفعيل تنفيذ الطلب الصوتي من خلال "مساعد Google".

يستخدم "مساعد Google" معالجة اللغات الطبيعية لاستخراج المَعلمات من طلبات بحث المستخدِم. يسرد مرجع الأهداف المضمّنة الحقول التي يمكن لكلّ هدف مضمّن في النص (BII) استخراجها من طلب بحث مرتبط بالمستخدم. على سبيل المثال، إذا استخدَم مستخدم إمكانية [actions.intent.GET_FOOD_OBSERVATION][] في تطبيقك من خلال قول "Ok Google، أريد أن أسأل تطبيق ExampleApp ما الذي أكلته في الغداء يوم الجمعة الماضي"، يستخرج "مساعد Google" مَعلمات BII التالية من طلب المستخدم:

  • foodObservation.forMeal = "https://schema.googleapis.com/MealTypeLunch"
  • foodObservation.startTime = "2024-09-06T00:00:00"
  • foodObservation.endTime = "2024-09-06T23:59:59"

يُرسِل المساعد مَعلمات BII إلى intent التسليم المحدّد في capability. يمكن تعريف عنصر intent واحد أو أكثر في إحدى الإمكانات للتمكّن من مراعاة الطرق المختلفة التي قد يستخدِم بها المستخدم واجهة برمجة التطبيقات لخدمات الويب. على سبيل المثال، يمكنك تعريف عملية تنفيذ intent تتطلّب مَعلمتَي BII في المثال أعلاه. يمكنك بعد ذلك تحديد نية ثانية تتطلّب مَعلمة BII واحدة، foodObservation.forMeal، تُبلغ عن جميع الوجبات في يوم معيّن، مثل "Ok Google، أريد أن أسأل تطبيق ExampleApp ما الذي أكلته في الغداء".

نظرة عامة

يمكنك ضبط "إجراءات التطبيق" باستخدام ملف shortcuts.xml يتم وضعه في دليل res/xml لمشروع تطبيقك، ثم إنشاء إشارة إلى shortcuts.xml في بيان تطبيقك. أضِف إشارة إلى shortcuts.xml في بيان تطبيقك من خلال اتّباع الخطوات التالية:

  1. في ملف بيان تطبيقك (AndroidManifest.xml)، ابحث عن نشاط تم ضبط فلاتر أهدافه على الإجراء android.intent.action.MAIN والفئة android.intent.category.LAUNCHER.

  2. أضِف إشارة إلى shortcuts.xml في AndroidManifest.xml باستخدام علامة <meta-data> في Activity التي تحتوي على فلاتر النيّة لكلّ من MAIN وLAUNCHER، على النحو التالي:

    <meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

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

يجب توفُّر مكتبة Jetpack androidx.core:core:1.6.0 (أو إصدار أحدث) في مشروع Android لتجنُّب أخطاء الترجمة compiling عند تحديد إمكانات "إجراءات التطبيق" في shortcuts.xml. للتعرّف على التفاصيل، يُرجى الاطّلاع على مقالة البدء في استخدام Android Jetpack.

الاختصارات الثابتة

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

يمكنك تفعيل وظائف "إجراءات التطبيق" التالية باستخدام اختصارات ثابتة:

  • اختصارات الإمكانات: أنشئ اختصارات لتشغيل مثيل من capability يحتوي على قيم مُحدَّدة مسبقًا للمَعلمة intent. على سبيل المثال، يمكنك تحديد اختصار تطبيق "بدء جولة ركض" الذي يستدعي ميزة BII في START_EXERCISE تطبيق اللياقة البدنية.

    تحتوي هذه الاختصارات على سمات intent وshortLabel وlongLabel، مما يجعلها مؤهَّلة للاقتراح وعرضها كشرائح في مساحات الشاشة التفاعلية، مثل "مساعد Google" أو عند الضغط مع الاستمرار على رمز تطبيق على مشغّلات التطبيقات في Android. يمكن أن يعمل اختصار الإجراء أيضًا كاختصار كيان، كما هو موضّح أدناه، من خلال ربطه بعنصر capability باستخدام علامة <capability-binding>.

  • اختصارات الكيانات: توفّر اختصارات الكيانات قائمة بقيم المَعلمات المتوافقة لاستيفاء طلبات البحث الصوتية عن capability. على سبيل المثال، اختصار كيان يتضمّن قائمة بأنواع التمارين ("المشي لمسافات طويلة" و"الجري" وما إلى ذلك) مرتبطًا بالمَعلمة exercise.name BII لميزة START_EXERCISE إذا تطابقت عبارة المستخدِم مع عنصر، يتم تمرير معرّف shortcutId إلى النية بدلاً من قيمة طلب المستخدِم الأوّلية.

    لا تحدّد اختصارات Entity سمات intent أو shortLabel أو longLabel ، وبالتالي لا يتم اقتراحها على مساحات العرض الاستباقية. للاطّلاع على التفاصيل، يُرجى الاطّلاع على مستودع إعلانات مضمّنة لإجراءات التطبيقات.

مخطّط الإمكانات

يوضّح الجدول التالي مخطّط "إجراءات التطبيقات" لعناصر capability في shortcuts.xml. عند تضمين علامة، تكون جميع سماتها مطلوبة ما لم يتم وضع علامة "اختيارية" عليها.

علامة Shortcuts.xml مضمّنة في السمات
<capability> <shortcuts>

android:name

app:queryPatterns (لا ينطبق إلا على الجمهور المخصّص حسب النية بالشراء)
<intent> <capability>

android:action (اختياري)

android:targetClass (اختياري)

android:targetPackage (اختياري)

android:data (اختياري)
<url-template> <intent>

android:value
<extra> <intent>

android:key

android:value

لا ينطبق إلا على تشغيل التطبيقات في المقدّمة
<parameter> <intent>

android:name

android:key

android:mimeType (لا ينطبق إلا على الجمهور المخصّص حسب النية بالشراء)

android:required (اختياري)

app:shortcutMatchRequired (اختياري)
<shortcut-fulfillment> <capability> لا ينطبق إلا على المستودع الإعلاني المضمّن
<parameter> <shortcut-fulfillment> android:name
<slice> <capability>

لا ينطبق إلا على Android Slices

وصف مخطّط القدرات

يصف هذا القسم عناصر مخطّط capability.

<capability>

capability يحدّد هدف "إجراء التطبيق" الذي يتوافق معه تطبيقك يجب أن يقدّم كل عنصر <capability> في ملف shortcuts.xml عنصر <intent> واحدًا على الأقل لمعالجة تنفيذ الإجراء.

السمات:

  • android:name: رقم تعريف إجراء النيّة المضمّنة (على سبيل المثال، [actions.intent.GET_FOOD_OBSERVATION][]). للحصول على قائمة بالنيّات المضمّنة المتوافقة، اطّلِع على مرجع النيّة المضمّنة.
  • app:queryPatterns: مورد مصفوفة سلاسل من طلبات البحث المتوقّعة من العميل لطلب البحث هذا. لا تنطبق هذه السمة إلا على المقصودات المخصّصة، لأنّ طلبات البحث عن المعلومات تتضمّن حاليًا نماذج للطرق الشائعة التي يعبّر بها المستخدمون عن المهام التي يحاولون تنفيذها أو المعلومات التي يبحثون عنها.

<intent>

عنصر intent في Android الذي يحدِّد كيفية معالجة طلب بحث المستخدِم باستخدام الوظائف داخل التطبيق يمكن للمطوّرين تقديم علامات <intent> متعدّدة في capability. يحاول "مساعد Google" تنفيذ طلب بحث من المستخدِم باستخدام <intent> الأولى في capability التي تم توفير جميع المَعلمات المطلوبة لها.

السمات:

  • ‫android:action: نوع النية Action الإعداد التلقائي هو ACTION_VIEW.
  • android:targetClass: فئة النشاط المستهدَف، على سبيل المثال: "com.example.exercise.ExerciseActivity"
  • ‫android:targetPackage: الحزمة التي تحتوي على فئة النشاط المستهدَف، على سبيل المثال: "com.example.exercise
  • android:data: يتم استبدال هذا الحقل بـ <url-template> إذا تمّ الإعلان عن هذه العلامة في intent.

<url-template>

قالب لإنشاء معرّف URI لرابط لصفحة في التطبيق لفتح التطبيق على الجهاز يمكن توسيع النماذج باستخدام مَعلمات اتّجاه مدمجة إذا كانت جميع المَعلمات المطلوبة للنماذج متاحة. للحصول على أمثلة على نموذج عنوان URL المستخدِم بروتوكول HTTP، اطّلِع على مقالة Wikipedia عن نماذج عناوين URL. يتّبع تنسيق ال نموذج مواصفات نموذج معرّف الموارد المنتظم RFC6570.

في ما يلي بعض الأمثلة على قيم نماذج عناوين URL:

النموذج القيم القيمة الموسّعة
https://example.com/test{?foo,bar} "foo": "123"

"bar": "456"

https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar} "foo": "123"

"bar": "456"

https://example.com/test?utm_campaign=appactions&foo=123&bar=456
https://example.com/test?utm_campaign=appactions{#foo} "foo": "123" https://example.com/test?utm_campaign=appactions#foo=123
myapp://example/{foo} "foo": "123" myapp://example/123

لمزيد من المعلومات عن ضبط نماذج عناوين URL، يُرجى الاطّلاع على مقالة نماذج عناوين URL في مرحلة التسليم.

<extra>

تُحدِّد بيانات إضافية لعنصر intent. بالنسبة إلى إجراءات التطبيقات، لا يُستخدَم هذا الحقل إلا ل تفعيل [invocation of foreground app][] لcapability.

<parameter>

تربط مَعلمة BII بقيم مَعلمات النية. لمزيد من المعلومات، اطّلِع على بيانات المَعلمات والمطابقة.

السمات:

  • android:name: اسم مَعلمة BII المطلوب ربطها بهذه المَعلمة intent. يجب أن يكون الاسم حقلًا من المستوى السفلي لمَعلمة BII (مثلfoodObservation.aboutFood.name).
  • android:key: مفتاح يحدّده المطوّر لقيمة مَعلمة BII. على سبيل المثال، يمكنك تحديد contact_name للمَعلمة message.recipient.name BII.
  • android:mimeType: mimeType للمَعلمة، مثل text/*. هذا الحقل مطلوب فقط لمَعلمات المقصودات المخصّصة.
  • ‫android:required: يُستخدَم للإشارة إلى ما إذا كان طلب بحث المستخدِم يجب أن يتضمّن هذه المَعلمة لاستخدام هذا النيّة في العرض. إذا لم تكن المَعلمة متوفرة، يحاول "مساعد Google" تنفيذ طلب بحث المستخدم باستخدام القيمة التالية لintent المحدَّدة للعنصر capability.

<shortcut-fulfillment>

تُحدِّد هذه السمة أنّه يجب استخدام intent محدّد في اختصار مستودع مضمّن لمَعلمة محدّدة من أجل التسليم. لمعرفة التفاصيل، يُرجى الاطّلاع على الاستجابة باستخدام نوايا الاختصار.

<parameter> (بالنسبة إلى <shortcut-fulfillment>)

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

السمة:

  • android:name: اسم مَعلمة BII لربطها بميزة تنفيذ اختصار المستودع الإعلاني المضمّن. يجب أن يكون الاسم حقلًا من المستوى السفلي للمَعلمة BII (على سبيل المثال، menuItem.name).

<slice>

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

مخطّط الاختصار

يوضّح الجدول التالي سمات عناصر shortcut التي تُستخدَم ل تفعيل وظائف "إجراءات التطبيقات". عند تضمين علامة، يجب إدخال جميع سماتها ما لم يتم وضع علامة "اختيارية" عليها.

علامة Shortcuts.xml مضمّنة في السمات
<shortcut> <shortcuts>

android:shortcutId

android:shortcutShortLabel

android:shortcutLongLabel (اختياري)

android:icon (اختياري)
<intent> <shortcut>

android:action

android:targetClass (اختياري)

android:targetPackage (اختياري)

android:data (اختياري)
<capability-binding> <shortcut>

android:key
<parameter-binding> <capability-binding>

android:key (اختياري)

android:value
<extra> <shortcut>

android:name (اختياري)

android:value

لا ينطبق إلا على مطابقة مَعلمات Enum.

وصف مخطّط الاختصار

يصف هذا القسم عناصر مخطّط shortcut.

<shortcut>

<shortcut> لنظام التشغيل Android تمّ تحديده في shortcuts.xml مع سمات معيّنة تكون ذات صلة بإجراءات التطبيق تتم الإشارة إلى قيم السلاسل للحقول shortcutShortLabel وshortcutLongLabel من خلال موارد السلاسل في حزمة APK.

السمات:

  • android:shortcutId: معرّف هذا الاختصار
  • android:shortcutShortLabel: مرجع سلسلة يمثّل عبارة اختصار مختصرة. على سبيل المثال، "@string/callDavidShort" يمثّل القيمة "الاتصال بشمس".
  • android:shortcutLongLabel: مورد سلسلة يمثّل عبارة اختصار طويلة. على سبيل المثال، "@string/callDavidLong" يمثّل القيمة "إجراء مكالمة صوتية مع داوود".

<intent>

نية Android المرتبطة بهذا الاختصار يتم تنفيذ intent هذا عندما يشغِّل المستخدم هذا الاختصار باستخدام الصوت أو اللمس.

سمات shortcut intent مطابقة لسمات capability intent.

<capability-binding>

ربط shortcut بأحد capability "المهام في التطبيقات" تؤدي إضافة هذا العنصر إلى shortcut إلى تفعيله للعرض الصوتي باستخدام Assistant.

السمات:

  • android:key: سمة android:name لعنصر capability الذي shortcut مرتبط به. على سبيل المثال، actions.intent.START_EXERCISE.

<parameter-binding>

سمة اختيارية تربط shortcut بمَعلمة واحدة من capability إجراءات التطبيق. إذا تمّ تحديد parameter-binding لـ shortcut، يمكن استخدام الرمز المختصر لتقديم عنصر مستودع إعلاني مضمّن لمَعلمة BII. لمزيد من التفاصيل، يُرجى الاطّلاع على المستودع الإعلاني المضمّن لميزة "المهام مع مساعد Google".

السمات:

  • android:key: اسم مَعلمة BII‏ capability لربط هذا الاختصار بها. على سبيل المثال، exercise.name.
  • android:value: قيمة entity يمكن أن يكون هذا entity واحدًا أو قائمة موارد.

<extra>

extra حِزمة بيانات الاختصار. sameAs هي البيانات الوحيدة ذات الصلة بعناصر shortcut "إجراءات التطبيق". يشير عنوان URL sameAs إلى صفحة ويب مرجعية تحدِّد الكيان بوضوح. تُستخدَم لتحديد قيمة تصنيف إذا كان نوع مَعلمة النيّة هو نوع فرعي من schema.org/Enumeration فقط. وهو مطلوب لحقول المَعلمات التي تكون أنواعها أنواعًا فرعية من schema.org/Enumeration (على سبيل المثال: MealTypeBreakfast).

السمات:

  • android:key: القيمة المسموح بها لإجراءات التطبيق هي: sameAs
  • android:value: قيمة عنوان URL sameAs

لمزيد من التفاصيل، يُرجى الاطّلاع على مطابقة قيم المَعلمات المُدرَجة.

خيارات تلبية النية

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

تتوفّر خيارات التسليم التالية:

  • المقصودات الصريحة: يمكنك تشغيل مكوّن تطبيق معيّن من خلال تحديد سمتَي targetClass وtargetPackage للعنصر intent. هذه هي طريقة الوفاء المُقترَحة للمهام في التطبيق.

  • الروابط لصفحات في التطبيق: يمكنك إطلاق وجهات التطبيق باستخدام روابط لصفحات في التطبيق على Android من خلال تحديد علامة <url-template> ضمن العنصر intent. تكون هذه المحاولة مفيدة إذا كان تنقّل تطبيقك يعتمد على الروابط لصفحات في التطبيق.

  • بيانات الطلب: يمكنك تقديم عنوان URL للتسليم في سمة intent android:data. يتم استبدال هذا الحقل ببيانات <url-template> إذا تم تحديد هذه العلامة أيضًا ضمن intent.

بيانات المَعلمات والمطابقة

يُرسِل "مساعد Google" تلقائيًا مَعلمات BII المستخرَجة من طلب المستخدم إلى تطبيقك كبيانات extra لتطبيق Android intent المحدَّدة في capability.

بدلاً من ذلك، يمكنك تحديد علامة <url-template> في capability تحتوي على عناصر نائبة للمَعلمات الديناميكية. يتم ربط هذا النموذج بأحد أنشطة Android باستخدام عنوان URL لرابط تطبيق أو مخطّط مخصّص أو عنوان URL مستند إلى النية.

استخدام "إضافات النيّة"

يوضّح المثال التالي نية صريحة محدّدة لعملية capability تنفيذ:

<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>

استنادًا إلى العيّنة أعلاه، إذا أدخل المستخدم طلب بحث مثل "Ok Google، أريد بدء الركض"، يتلقّى التطبيق طلبًا من النوع intent يستدعي المكوّن: targetPackage، targetClass. يتلقّى المكوّن قيمة إضافية باستخدام key = "exercise" وvalue = "Running".

إذا كان تطبيقك قادرًا على معالجة عناوين URL المرتبطة بالتطبيق، باستخدام مَعلمات ديناميكية، يمكنك تحديد <url-template> في intent لإنشاء Android روابط لصفحات في التطبيق لإكمال عملية الشراء. يحدِّد العيّنة التالية <url-template>:

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

استنادًا إلى العيّنة أعلاه، إذا أدخل المستخدم طلب بحث مثل "Ok Google، أريد بدء الركض"، يتلقّى التطبيق عنوان URL الذي تم إنشاؤه: "myapp://start?exercise=Running".

لربط مَعلمة BII بموضع في عنوان URL، استخدِم سمة android:name لعلامة <parameter>. تتوافق هذه السمة مع القيمة android:key في نموذج عنوان URL الذي تريد استبداله بمعلومات من المستخدِم. يجب أن تكون قيمة android:key متوفّرة في <url-template> وأن تكون محاطة بقوسين معقوفين ({}).

مطابقة قيم المَعلمات المُدرَجة

توفّر بعض مَعلمات BII قيمًا مُدرَجة لهدف التسليم، على سبيل المثال، القيم النصية المتوافقة لمَعلمة BII‏ RECORD_FOOD_OBSERVATION. بالنسبة إلى هذه المَعلمات، يطابق "مساعد Google" طلب بحث المستخدم ("فطور") بأحد الكيانات التي تتطابق قيمة sameAs الخاصة بها مع عنوان URL لنموذج التعداد (https://schema.googleapis.com/MealTypeBreakfast). ولربط entity بقيم التعداد المتوافقة، عليك الإفصاح عن عملية ربط sameAs في shortcut. يوضّح المثال التالي عملية ربط sameAs لاختصار كيان مضمّن:

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

في المثال أعلاه، إذا أدّت ميزة RECORD_FOOD_OBSERVATION إلى بدء عملية مطابقة لنوع الوجبة "فطور"، يتم إرسال العنصر الإضافي التالي مع العنصر الذي يمثّل المنتج intent:

  • key = "for_meal"
  • value = "meal_breakfast"

الميزات

تتوفّر ميزات "مهام في التطبيقات" التالية في shortcuts.xml.

المستودع الإعلاني المضمّن لميزة "مهام في التطبيقات"

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

شرائح الجمهور المخصّصة حسب النية بالشراء

يمكن الإفصاح عن النوايا المخصّصة في shortcuts.xml لتفعيل الميزات التي لا تتطابق مع معرّفات BIIs المتاحة في تطبيقك باستخدام الصوت. على الرغم من أنّها مشابهة في وظيفتها لتعريف BII، تتطلّب النوايا المخصّصة سمتَين إضافيتَين في shortcuts.xml:

  • ‫app:queryPatterns: مورد مصفوفة يعرِض أنماط طلبات البحث المختلفة لهدف مخصّص.

  • android:mimeType: نوع مَعلمة الجمهور المخصّص حسب النية بالشراء. هذا الحقل غير مطلوب لـ BIIs، حيث يكون نوع المَعلمة معروفًا. بالنسبة إلى مَعلمات الأهداف المخصّصة، يجب تحديد نوع دلالة متوافق.

لمزيد من التفاصيل، يُرجى الاطّلاع على المقصودات المخصّصة.