إدارة الاختصارات

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

تصف هذه الصفحة هذه الاختصارات والعديد من الطرق الشائعة الأخرى لإدارة الاختصارات.

سلوك الاختصارات

تحتوي الأقسام التالية على معلومات عامة حول سلوك الاختصار، بما في ذلك مستوى الرؤية وترتيب العرض والترتيب.

مستوى رؤية الاختصارات

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

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

توفر الفئة LauncherApps واجهات برمجة تطبيقات لتطبيقات مشغّل التطبيقات للوصول إلى الاختصارات.

وتكون الاختصارات المثبَّتة ظاهرة في مشغّل التطبيقات نفسه، وتكون مرئية دائمًا. لا تتم إزالة الاختصار المثبَّت من مشغِّل التطبيقات إلا في الحالات التالية:

• يزيل المستخدم هذه البيانات.
• يتم إلغاء تثبيت التطبيق المرتبط بالاختصار.
• يمحو المستخدم بيانات التطبيق من خلال الانتقال إلى الإعدادات > التطبيقات والإشعارات، واختيار التطبيق ثم النقر على مساحة التخزين > محو مساحة التخزين.

مشاركة الاستهدافات هي مجموعة فرعية من الاختصارات الديناميكية التي تظهر في صف المشاركة المباشرة في صفحة المشاركة في Android.

الشكل 1. ورقة مشاركة Android. تظهر استهدافات المشاركة المباشرة في الصف الأول، تليها التطبيقات المرتَّبة ثم قوائم "التطبيقات".

ترتيب عرض الاختصار

عندما يعرض المشغّل اختصارات أحد التطبيقات، يجب أن تظهر بالترتيب التالي:

1. الاختصارات الثابتة: الاختصارات التي تعرض طريقة isDeclaredInManifest() الخاصة بها true.
2. الاختصارات الديناميكية: الاختصارات التي تعرض طريقتها ShortcutInfo.isDynamic() true.

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

وتكون الترتيبات أعدادًا صحيحة متسلسلة غير سالبة. يتم ترتيب الاختصارات الثابتة من الأول إلى الأخير بالترتيب الذي تظهر به في ملف shortcuts.xml. بالنسبة إلى الاختصارات الديناميكية، يمكنك تعديل ترتيب الاختصارات الحالية عند استدعاء updateShortcuts(Context, List) أو addDynamicShortcuts(Context, List) أو pushDynamicShortcut(Context, ShortcutInfoCompat) أو setDynamicShortcuts(Context, List).

يستند ترتيب أهداف المشاركة إلى عوامل مختلفة، بما في ذلك سجل المستخدم السابق، ومدى الحداثة، ومعدل التكرار، وتلميح الترتيب، واستخدام التطبيق، والأولوية المحددة للمحادثة المرتبطة باختصار مشاركة. إنّ مشاركة الأهداف التي تم إنشاؤها باستخدام Shared Shortcuts API تُعطى الأولوية على أهداف المشاركة التي تم إنتاجها من خلال ChooserTargetService التي تم إيقافها في نظام التشغيل Android 11. في نظام التشغيل Android 12 والإصدارات الأحدث، لن تظهر أهداف المشاركة التي تم إنشاؤها بواسطة سياسة ChooserTargetService المتوقّفة نهائيًا في صفحة المشاركة.

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

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

إدارة أغراض وأنشطة متعددة

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

تحديد أغراض متعددة

عند إنشاء اختصار باستخدام ShortcutInfoCompat.Builder، يمكنك استخدام setIntents() بدلاً من setIntent(). من خلال الاتصال بـ setIntents()، يمكنك تشغيل أنشطة متعددة في التطبيق عندما يختار المستخدم اختصارًا، مع وضع كل الأنشطة باستثناء النشاط الأخير في القائمة على المكدس الخلفي. إذا نقر المستخدم بعد ذلك على زر الرجوع في الجهاز، فسيظهر له نشاط آخر في تطبيقك بدلاً من العودة إلى مشغّل الجهاز.

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

بدء نشاط من نشاط آخر

لا يمكن أن تحتوي الاختصارات الثابتة على علامات مخصّصة حسب النيّة بالشراء. يكون الغرض الأول من الاختصار الثابت دائمًا هو Intent.FLAG_ACTIVITY_NEW_TASK وIntent.FLAG_ACTIVITY_CLEAR_TASK ضبط. وهذا يعني أنّه عند تشغيل تطبيقك، سيتم محو جميع الأنشطة الحالية في التطبيق عند تشغيل اختصار ثابت. إذا كنت لا تريد هذا السلوك، يمكنك استخدام نشاط الترامبولين، وهو نشاط غير مرئي يبدأ نشاطًا آخر، في Activity.onCreate(Bundle) الذي يستدعي Activity.finish():

1. في ملف AndroidManifest.xml، عليك تضمين السمة المخصّصة android:taskAffinity="" في نشاط الترامبولين.
2. في ملف مورد الاختصارات، أشِر إلى نشاط الترامبولين في الغرض داخل الاختصار الثابت.

لمزيد من المعلومات حول أنشطة الترامبولين، راجع بدء نشاط من نشاط آخر.

ضبط علامات النية

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

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

تعديل الاختصارات

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

عندما يتم تثبيت اختصار ديناميكي، حتى عندما يزيله الناشر كاختصار ديناميكي، يظل الاختصار المثبَّت مرئيًا وقابلاً للتشغيل. يؤدّي ذلك إلى توفّر أكثر من getMaxShortcutCountPerActivity() من الاختصارات للتطبيق.

بالنظر إلى المثال التالي، الذي يفترض أن القيمة التي تعرضها getMaxShortcutCountPerActivity() هي 4:

1. ينشر تطبيق دردشة أربعة اختصارات ديناميكية، تمثل أحدث أربع محادثات: c1 وc2 وc3 وc4.
2. يثبّت المستخدم الاختصارات الأربعة جميعها.
3. لاحقًا، يبدأ المستخدم ثلاث محادثات إضافية: c5 وc6 وc7. يعيد تطبيق الناشر نشر اختصاراته الديناميكية قائمة الاختصارات الديناميكية الجديدة هي: c4 وc5 وc6 وc7.

يجب أن يزيل التطبيق c1 وc2 وc3، لأنه لا يمكنه عرض أكثر من أربعة اختصارات ديناميكية. ومع ذلك، لا تزال c1 وc2 وc3 اختصارات مثبتة يمكن للمستخدم الوصول إليها وتشغيلها.

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

1. يمكن للتطبيق استخدام updateShortcuts(Context, List) لتحديث أي من الاختصارات السبعة الحالية. على سبيل المثال، يمكنك تحديث هذه المجموعة من الاختصارات عندما تتغير أيقونات أقران الدردشة.
2. يمكنك استخدام طريقتَي addDynamicShortcuts(Context, List) وsetDynamicShortcuts(Context, List) لتعديل الاختصارات الحالية بالمعرّفات نفسها. ومع ذلك، لا يمكنك استخدامها لتحديث الاختصارات غير الديناميكية المثبَّتة، لأن هاتين الطريقتين تحاولان تحويل قوائم الاختصارات المحددة إلى اختصارات ديناميكية.

وما من حدّ أقصى لعدد الاختصارات التي يمكن إرسالها لعرضها في تطبيقات المساعد مثل "مساعد Google". استخدِم الطريقة pushDynamicShortcut() في مكتبة Jetpack ShortcutManagerCompat لإنشاء اختصارات وتعديلها لاستخدامها في التطبيقات المساعِدة. أضِف أيضًا مكتبة تكامل اختصارات Google إلى تطبيقك لجعل الروابط الديناميكية مؤهَّلة للظهور على "مساعد Google".

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

التعامل مع تغييرات لغة النظام

يجب أن تعدِّل التطبيقات الاختصارات الديناميكية والاختصارات المثبَّتة عند تلقّي بث Intent.ACTION_LOCALE_CHANGED الذي يشير إلى تغيير في لغة النظام.

تتبُّع استخدام الاختصارات

لتحديد المواقف التي تظهر فيها الاختصارات الثابتة والديناميكية، يفحص مشغّل التطبيقات سجلّ تفعيل الاختصارات. بالنسبة إلى الاختصارات الثابتة، يمكنك تتبُّع الوقت الذي يكمل فيه المستخدمون إجراءات محدّدة داخل تطبيقك عن طريق استدعاء طريقة reportShortcutUsed() وتمرير رقم تعريف الاختصار لها عند وقوع أي من الحدثَين التاليَين:

• ويختار المستخدم الاختصار الذي يتضمّن رقم التعريف المحدّد.
• داخل التطبيق، يُكمل المستخدم يدويًا الإجراء المقابل للاختصار نفسه.

يتتبّع تطبيقك استخدام الاختصارات الديناميكية من خلال استدعاء طريقة pushDynamicShortcut() وتمرير رقم تعريف الاختصار لها عند وقوع حدث ذي صلة. يسمح الدفع باستخدام الاختصارات الديناميكية من خلال هذه الطريقة للتطبيقات المساعِدة، مثل "مساعد Google"، باقتراح اختصارات ذات صلة للمستخدمين. بما أنّ الطريقة pushDynamicShortcut() تُبلغ عن الاستخدام عند طلبها، لا تستدعي الطريقة reportShortcutUsed() مع الاختصارات نفسها.

بالنسبة إلى الاختصارات المتعلقة بالمحادثة، من المهم تتبع استخدام الرسائل الصادرة والواردة. للحصول على التفاصيل، راجع أفضل الممارسات للأشخاص والمحادثات.

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

إيقاف الاختصارات

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

ملاحظة: في حال إزالة بعض الاختصارات الثابتة لتطبيقك عند تحديث التطبيق، يوقف النظام هذه الاختصارات تلقائيًا.

تقييد المعدّل

عند استخدام الطريقتين setDynamicShortcuts(), addDynamicShortcuts() أو updateShortcuts()، قد تتمكن فقط من استدعاء هاتين الطريقتين لعدد معيّن من المرات في تطبيق الخلفية، وهو تطبيق لا يشتمل على أنشطة أو خدمات في المقدّمة. ويُطلق على الحد الأقصى لعدد المرات التي يمكنك فيها استدعاء هذه الطرق اسم تحديد السعر. تمنع هذه الميزة ShortcutManagerCompat من استهلاك موارد الجهاز بشكل مفرط.

عندما يكون تحديد المعدّل مفعَّلاً، تعرض isRateLimitingActive() القيمة "صحيح". ومع ذلك، تتم إعادة ضبط الحدّ الأقصى لمعدّل الاستخدام خلال أحداث معيّنة، وبالتالي يمكن للتطبيقات التي تعمل في الخلفية طلب طُرق ShortcutManager إلى أن يتم الوصول مرة أخرى إلى الحدّ الأقصى لمعدّل الزحف. وتشمل هذه الفعاليات ما يلي:

• يظهر التطبيق في المقدّمة.
• تتغير لغة النظام.
• ينفِّذ المستخدم إجراء الرد المضمّن على الإشعار.

إذا كنت تواجه معدّلاً مخفّضًا للمعدّل أثناء التطوير أو الاختبار، يمكنك اختيار خيارات المطوّرين > إعادة ضبط تقييد المعدّل في ShortcutManager من إعدادات الجهاز، أو يمكنك إدخال الأمر التالي في adb:

$ adb shell cmd shortcut reset-throttling [ --user your-user-id ]

الاحتفاظ بنسخة احتياطية والاستعادة

يمكنك السماح للمستخدمين بإجراء عمليات نسخ احتياطي واستعادة على تطبيقك عند تغيير الأجهزة، وذلك من خلال تضمين السمة android:allowBackup="true" في ملف البيان في تطبيقك. إذا كنت تدعم النسخ الاحتياطي والاستعادة، ضع النقاط التالية حول اختصارات التطبيق في الاعتبار:

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

يعرض مقتطف الرمز التالي أفضل طريقة لاستعادة الاختصارات الديناميكية لتطبيقك وكيفية التحقّق مما إذا كان قد تم الاحتفاظ بالاختصارات المثبَّتة لتطبيقك:

Kotlin

class MyMainActivity : Activity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.dynamicShortcuts.size == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.pinnedShortcuts.size > 0) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}

Java

public class MainActivity extends Activity {
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        if (ShortcutManagerCompat.getDynamicShortcuts().size() == 0) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts().size() > 0) {
                // Pinned shortcuts are restored. Use pdateShortcuts() to make
                // sure they contain up-to-date information.
            }
        }
    }
    // ...
}