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

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

توضّح هذه الصفحة هذه الطرق وعدة طرق شائعة أخرى لإدارة اختصاراتك.

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

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

إمكانية رؤية الاختصار

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. في AndroidManifest.xml file، أدرِج عملية تعيين السمة android:taskAffinity="" في نشاط الترامبولين.

2. في ملف مصدر الاختصارات، أشر إلى نشاط الترامبولين في intent ضمن الاختصار الثابت.

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

ضبط علامات الأهداف

يمكنك نشر اختصارات ديناميكية باستخدام أي مجموعة من علامات Intent. يُفضّل تحديد مجموعة Intent.FLAG_ACTIVITY_SINGLE_TOP وIntent.FLAG_ACTIVITY_CLEAR_TOP في هدف الاختصار. يضمن ذلك أنّه إذا كان ComponentActivity نشطًا، سيتم عرضه في المقدّمة وإعادة استخدامه بدون إيقافه، ما يتيح لبنية التطبيق ذات النشاط الواحد معالجة حدث الاختصار بسلاسة من خلال onNewIntent().

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

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

يمكن أن يحتوي رمز مشغّل التطبيقات لكل تطبيق على عدد من الاختصارات الثابتة والديناميكية معًا يساوي القيمة التي تعرضها الدالة 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"، مثل "مساعد Google". استخدِم طريقة pushDynamicShortcut في مكتبة ShortcutManagerCompat Jetpack لإنشاء وتعديل اختصارات لاستخدامها في تطبيقات المساعد. عليك أيضًا إضافة مكتبة Google Shortcuts Integration إلى تطبيقك لجعل الروابط الديناميكية مؤهَّلة للظهور على "مساعد Google".

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$ adb shell cmd shortcut reset-throttling [ --user <var>your-user-id</var> ]

النسخ الاحتياطي والاسترداد

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

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

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

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        if (ShortcutManagerCompat.getDynamicShortcuts(this).isEmpty()) {
            // Application restored. Re-publish dynamic shortcuts.
            if (ShortcutManagerCompat.getPinnedShortcuts(this).isNotEmpty()) {
                // Pinned shortcuts are restored. Use updateShortcuts() to make
                // sure they contain up-to-date information.
            }

        }
    }
    // ...
}