إرسال الاختصارات الديناميكية إلى "مساعد Google"

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

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

عند استخدام مكتبة تكامل "اختصارات Google" في تطبيقك، تكون الاختصارات الديناميكية التي ترسلها إلى Google مرئية للمستخدمين كاقتراحات لاختصارات صوتية في تطبيق "مساعد Google". يمكنك توجيه عدد غير محدود من الاختصارات الديناميكية إلى "مساعد Google" باستخدام طريقة pushDynamicShortcut() في مكتبة ShortcutManagerCompat.

إعداد مشروع التطوير

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

لإضافة مكتبة Jetpack هذه وإعداد مشروعك، اتّبِع الخطوات التالية:

  1. عليك تعديل ملف gradle.properties للتعامل مع مكتبات Jetpack:

    grale.properties

    android.useAndroidX=true
    # Automatically convert third-party libraries to use AndroidX
    android.enableJetifier=true
    
  2. أضِف تبعيات مكتبة Jetpack إلى build.gradle:

    app/build.grale

    dependencies {
     implementation "androidx.core:core:1.6.0"
     implementation "androidx.core:core-google-shortcuts:1.0.1"
     ...
    }
    

    في نموذج التعليمات البرمجية السابق، عليك إدراج مكتبتَي Jetpack كتبعيات. تحتوي مكتبة androidx.core:core:1.6.0 على الصف ShortcutManagerCompat الذي تستخدمه لإرسال الاختصارات الديناميكية إلى Google.

    androidx.core:core-google-shortcuts:1.0.1 هي مكتبة دمج "اختصارات Google". لا تحتوي هذه المكتبة على واجهة برمجة تطبيقات يواجهها المطورون. من خلال إضافة هذه الكلمات كتبعية، يمكنك السماح لخدمة "مساعد Google" باستخدام الاختصارات الديناميكية التي تستخدمها في الصف ShortcutManagerCompat.

دفع الاختصارات الديناميكية

لنشر الاختصارات الديناميكية المؤهّلة للعرض على "مساعد Google"، عليك أولاً إنشاء الاختصار باستخدام الفئة ShortcutInfoCompat.Builder().

بعد ذلك، ادفع الاختصار باستخدام طريقة ShortcutManagerCompat.pushDynamicShortcut(). يتم الدفع باختصارات كلما أكمل المستخدم إجراءً ذا صلة في تطبيقك. يؤدي نموذج الرمز التالي إلى دفع اختصار في كل مرة يقدّم فيها المستخدم طلبًا في تطبيق توصيل الطعام:

مثال حول الطلب

Kotlin

// Define the dynamic shortcut for a menu item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
        "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino")
    )
    .setIntent(intent) // Push the shortcut
    .build()

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo)

Java

// Define the dynamic shortcut for a menu item
Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
      "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino"))
    .setIntent(intent)
    .build();

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

تحدّد السمة id المُشار إليها في الطريقة ShortcutInfoCompat.Builder في الرمز النموذجي السابق shortcutId لكائن الاختصار الناتج. يجب أن تكون قيمة id هذه عبارة عن سلسلة فريدة حرفية. للحصول على التفاصيل، راجِع مستندات اختصارات Android.

في المثال السابق، تربط الطريقة addCapabilityBinding الاختصار الديناميكي بالاختصار capability android:name نفسها التي تم تحديدها في shortcuts.xml. تتيح لك هذه الطريقة ربط الاختصار بمَعلمة Intent مضمّن (BII) دلالية.

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

Kotlin

var intent: Intent = Intent(context, DisplayOrderActivity::class.java)
intent.setPackage(this, "com.sample.app")
intent.setAction(Intent.ACTION_VIEW)

var shortcutInfo: ShortcutInfoCompat = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Order coffee")
    .setLongLabel("Order a cup of coffee")
    .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
    .setIntent(intent)
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Java

Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setPackage(this, "com.sample.app");
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
  .setShortLabel("Order coffee")
  .setLongLabel("Order a cup of coffee")
  .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

اختبار الاختصارات الديناميكية باستخدام "مساعد Google"

عند استخدام "مساعد Google" لاختصار ديناميكي من تطبيقك بنجاح، يصبح الاختصار مؤهلاً ليظهر كاقتراح اختصار صوتي في تطبيق "مساعد Google" على Android. ويقترح تطبيق "مساعد Google" أحدث الاختصارات التي أدخلها تطبيقك.

لاختبار الاختصارات الديناميكية باستخدام "مساعد Google"، يُرجى اتّباع الخطوات التالية:

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