استخدِم أهداف "المشاركة المباشرة" لتسهيل وسرعة على مستخدمي التطبيقات الأخرى مشاركة عناوين URL أو الصور أو أنواع أخرى من البيانات مع تطبيقك. تعمل ميزة "المشاركة المباشرة" من خلال عرض جهات الاتصال من المراسلة وتطبيقات التواصل الاجتماعي مباشرةً على Android Sharesheet، بدون أن يضطر المستخدمون إلى اختيار التطبيق ثم البحث عن جهة الاتصال.
ShortcutManagerCompat
هي واجهة برمجة تطبيقات AndroidX توفّر اختصارات المشاركة، ومتوافقة مع
واجهة برمجة التطبيقات ChooserTargetService
المتوقّفة نهائيًا. وهذه هي الطريقة المفضّلة لنشر "اختصارات المشاركة" وChooserTargets
. للحصول على التعليمات،
يُرجى الاطّلاع على استخدام AndroidX لتوفير كل من اختصارات المشاركة وChooserTargets
في هذه الصفحة.
نشر أهداف "المشاركة المباشرة"
لا يعرض صف "المشاركة المباشرة" في "صفحة المشاركة" سوى الاختصارات الديناميكية التي توفّرها واجهة برمجة تطبيقات "اختصارات المشاركة". أكمِل الخطوات التالية لنشر أهداف "المشاركة المباشرة".
يُرجى تحديد عناصر
share-target
في ملف موارد XML الخاص بتطبيقك.<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity"> <data android:mimeType="text/plain" /> <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" /> </share-target> </shortcuts>
عند بدء تشغيل تطبيقك، استخدِم
setDynamicShortcuts
لترتيب الاختصارات الديناميكية حسب الأهمية.يشير انخفاض المؤشر إلى أهمية أكبر. إذا كنت تنشئ تطبيقًا للتواصل، يمكن أن تكون أبرز المحادثات مرتّبة حسب مدى الحداثة كما تظهر في تطبيقك. ويجب عدم نشر اختصارات قديمة لأنّ المحادثة التي لا تتضمن أي نشاط من المستخدمين خلال آخر 30 يومًا تُعتبر قديمة.
Kotlin
ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
Java
List<ShortcutInfoCompat> shortcuts = new ArrayList<>(); shortcuts.add(shortcut1); shortcuts.add(shortcut2); ... ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
إذا كنت تطوّر تطبيقًا للتواصل، يمكنك الإبلاغ عن استخدام الاختصارات من خلال
pushDynamicShortcut
فورًا في كل مرة يتلقّى فيها المستخدم رسالة إلى جهة اتصال أو يرسلها. راجِع قسم الإبلاغ عن استخدام الاختصارات لتطبيقات الاتصالات في هذه الصفحة للحصول على مزيد من المعلومات. على سبيل المثال، يمكنك الإبلاغ عن استخدام الرسائل التي أرسلها المستخدم من خلال تحديد عمليات ربط الإمكانيات في الاختصار من خلالShortcutInfoCompat.Builder#addCapabilityBinding
مع إمكانيةactions.intent.SEND_MESSAGE
.Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
إذا حذف المستخدم جهة اتصال، استخدِم
removeLongLivedShortcut
. وهذه هي الطريقة المفضّلة لإزالة الاختصار بغض النظر عمّا إذا كان قد تم تخزينه مؤقتًا بواسطة خدمات النظام. يعرض مقتطف الرمز التالي مثالاً على كيفية إجراء ذلك.Kotlin
val deleteShortcutId = "..." ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
Java
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
تحسين ترتيب أهداف "المشاركة المباشرة"
تعرِض "قائمة مشاركة البيانات على Android" عددًا ثابتًا من أهداف "المشاركة المباشرة". يتم فرز هذه الاقتراحات حسب الترتيب. يمكنك تحسين ترتيب الاختصارات من خلال إجراء ما يلي:
- تأكَّد من أنّ كل
shortcutIds
فريدة ولا يمكن إعادة استخدامها لأهداف مختلفة. - يمكنك ضمان توفُّر الاختصار لفترة طويلة من خلال استدعاء الرمز
setLongLived(true)
. - بالنسبة إلى الاختصارات المرتبطة بالمحادثات، يمكنك الإبلاغ عن استخدام الاختصارات
للرسائل الصادرة والواردة عن طريق إعادة نشر الاختصارات المقابلة
من خلال
ShortcutManagerCompat.pushDynamicShortcut
. راجِع الإبلاغ عن استخدام الاختصارات لتطبيقات الاتصالات في هذه الصفحة لمعرفة التفاصيل. - تجنَّب تقديم استهدافات "المشاركة المباشرة" القديمة أو غير الملائمة، على سبيل المثال، جهات الاتصال التي لم يرسلها المستخدم خلال آخر 30 يومًا.
- بالنسبة إلى تطبيقات الرسائل القصيرة SMS، تجنب توفير اختصارات للرموز القصيرة أو المحادثات التي يتم تحديدها على أنها غير مرغوب فيها. فمن غير المرجح جدًا أن يشارك المستخدمون مع تلك المحادثات.
- يمكنك طلب
setCategories()
لربط الاختصار بالسماتmimeType
المناسبة. على سبيل المثال، في تطبيقات الرسائل القصيرة SMS، إذا لم تكن جهة الاتصال متوافقة مع خدمات الاتصالات التفاعلية (RCS) أو رسائل الوسائط المتعددة (MMS)، لن يتم ربط الاختصار المقابل بأنواع MIME غير نصية، مثلimage/*
وvideo/*
. - بالنسبة إلى محادثة معيّنة، بعد إرسال اختصار ديناميكي والإبلاغ عن الاستخدام، لا تغيّر رقم تعريف الاختصار. وهذا يضمن الاحتفاظ ببيانات الاستخدام للترتيب.
إذا نقر المستخدم على أيّ هدف من أهداف "المشاركة المباشرة"، يجب أن ينقله تطبيقك إلى واجهة مستخدم حيث يمكنه تنفيذ إجراء مباشرةً على هذا الهدف. لا تقدِّم للمستخدم واجهة مستخدم واضحة، ولا تضعه في واجهة مستخدم غير مرتبطة بالهدف الذي تم النقر عليه. على سبيل المثال، في أحد تطبيقات المراسلة، يؤدي النقر على هدف "المشاركة المباشرة" إلى نقل المستخدم إلى عرض محادثة مع الشخص الذي اختاره. تكون لوحة المفاتيح مرئية ويتم ملء الرسالة مسبقًا بالبيانات المشتركة.
واجهة برمجة تطبيقات اختصارات المشاركة
بدءًا من نظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات)،
أضافت ShortcutInfo.Builder
طرقًا وتحسينات
توفِّر معلومات إضافية حول هدف المشاركة:
setCategories()
- بدءًا من Android 10، يتم استخدام الفئات أيضًا لفلترة الاختصارات التي يمكنها التعامل مع نوايا أو إجراءات المشاركة. راجع تحديد هدف المشاركة لمعرفة التفاصيل. هذا الحقل مطلوب للاختصارات التي يُقصد استخدامها كأهداف للمشاركة.
setLongLived()
تحدِّد هذه السياسة ما إذا كان الاختصار صالحًا عندما يكون غير منشور أو إذا جعل التطبيق غير مرئي (كاختصار ديناميكي أو اختصار مثبَّت). وإذا بقي أحد الاختصارات لفترة طويلة، يمكن تخزينه مؤقتًا في خدمات النظام المختلفة حتى بعد إلغاء نشره كاختصار ديناميكي.
ويمكن أن يؤدي إنشاء اختصار طويل الأمد إلى تحسين ترتيبه. راجع الحصول على أفضل ترتيب للحصول على التفاصيل.
setShortLabel()
،setLongLabel()
عند نشر اختصار لمستخدم، يُرجى تضمين اسمه الكامل في "
setLongLabel()
" وأي اسم مختصر، مثل اللقب أو الاسم الأول، فيsetShortLabel()
.
اطّلِع على مثال على نشر اختصارات المشاركة على GitHub.
تقديم صور مختصرة
لإنشاء اختصار مشاركة، يجب إضافة صورة من خلال setIcon()
.
يمكن أن تظهر اختصارات المشاركة على مساحات عرض النظام وقد يتم تغيير شكلها.
بالإضافة إلى ذلك، قد تعرض بعض الأجهزة التي تعمل بإصدارات Android 7 أو 8 أو 9 (مستويات واجهة برمجة التطبيقات 25 و26 و27 و28) رموزًا نقطية فقط بدون خلفية، ما يؤدي إلى تقليل التباين بشكل كبير. لضمان ظهور الاختصار بالشكل المطلوب،
قدِّم صورة نقطية تكيُّفية باستخدام IconCompat.createWithAdaptiveBitmap()
.
تأكّد من أنّ الصور النقطية التكيُّفية تتّبع نفس الإرشادات والسمات التي تم ضبطها للرموز التكيُّفية. والطريقة الأكثر شيوعًا لإجراء ذلك هي تغيير حجم الصورة النقطية المربّعة المقصودة إلى 72×72 بكسل مستقل الكثافة في الوسط ضمن لوحة شفافة بحجم 108×108 بكسل مستقل الكثافة. إذا كانت الأيقونة تتضمن مناطق شفافة، عليك تضمين لون خلفية؛ وإلا، ستظهر المناطق الشفافة باللون الأسود.
لا تقدِّم صورًا مقنَّعة في شكل معيّن. على سبيل المثال، قبل إصدار Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، كان من الشائع تقديم صور رمزية للمستخدمين في ميزة "المشاركة المباشرة"
ChooserTarget
التي تم إخفاؤها في دائرة. أصبحت الآن "قائمة مشاركة البيانات" من Android ومنصات النظام الأخرى
في Android 10 الآن صورًا لاختصارات الأشكال والمظاهر.
إنّ الطريقة المفضّلة لتوفير اختصارات المشاركة من خلال
ShortcutManagerCompat
تعمل تلقائيًا على تشكيل كائنات المحتوى الخلفي "المشاركة المباشرة" ChooserTarget
في
دوائر نيابةً عنك.
تضمين هدف للحصة
يجب الإعلان عن أهداف المشاركة في ملف موارد التطبيق، على غرار تعريفات الاختصارات الثابتة. أضِف تعريفات استهداف المشاركة داخل العنصر الجذر <shortcuts>
في ملف المورد، إلى جانب تعريفات الاختصارات الثابتة الأخرى. يحتوي كل عنصر <share-targets>
على معلومات حول نوع البيانات التي تتم مشاركتها والفئات المطابقة
والفئة المستهدفة التي ستتعامل مع نية المشاركة. يبدو رمز XML شيئًا
كالتالي:
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <share-target android:targetClass="com.example.android.sharingshortcuts.SendMessageActivity"> <data android:mimeType="text/plain" /> <category android:name="com.example.android.sharingshortcuts.category.TEXT_SHARE_TARGET" /> </share-target> </shortcuts>
يشبه عنصر البيانات في هدف المشاركة مواصفات البيانات في فلتر أهداف. يمكن أن يحتوي كل هدف مشاركة على فئات متعددة لا تُستخدم إلا لمطابقة اختصارات التطبيق المنشورة مع تعريفات أهداف المشاركة الخاصة به. ويمكن أن تحتوي الفئات على أي قيم عشوائية محددة من خلال التطبيق.
في حال اختار المستخدم اختصار المشاركة في "قائمة مشاركة البيانات" في Android الذي يتطابق مع مثال المشاركة المستهدفة أعلاه، سيحصل التطبيق على نية المشاركة التالية:
Action: Intent.ACTION_SEND ComponentName: {com.example.android.sharingshortcuts / com.example.android.sharingshortcuts.SendMessageActivity} Data: Uri to the shared content EXTRA_SHORTCUT_ID: <ID of the selected shortcut>
إذا فتح المستخدم هدف المشاركة من اختصارات مشغّل التطبيقات، سيحصل التطبيق على
الغرض الذي تم إنشاؤه عند إضافة اختصار المشاركة إلى
ShortcutManagerCompat.
وبما أنّ الهدف مختلف، لن يكون المعرّف Intent.EXTRA_SHORTCUT_ID
متاحًا،
وعليك إرسال رقم التعريف يدويًا إذا احتجت إليه.
الإبلاغ عن استخدام الاختصارات لتطبيقات التواصل
إذا كنت تطوّر تطبيقًا للتواصل، يمكنك تحسين ترتيبك في "قائمة مشاركة البيانات" من Android من خلال الإبلاغ عن إحصاءات استخدام كلّ من الرسائل الصادرة والواردة.
لإجراء ذلك، أعِد نشر اختصار المحادثة الذي يمثّل جهة الاتصال من خلال
ShortcutManagerCompat.pushDynamicShortcut
.
تتوافق روابط استخدام الاختصارات والإمكانات مع الإصدارات القديمة من Android 5.0 (واجهة برمجة التطبيقات 21).
الإبلاغ عن استخدام الاختصارات للرسائل الصادرة
يشبه إعداد التقارير عن استخدام الرسائل التي أرسلها المستخدم من الناحية الوظيفية النقر على الزر "إرسال" بعد إنشاء الرسالة.
لبدء إعداد تقارير الاستخدام، عليك تحديد عمليات ربط الإمكانات في الاختصار
من خلال ShortcutInfoCompat.Builder#addCapabilityBinding
مع إمكانية actions.intent.SEND_MESSAGE
.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
إذا كانت الرسالة الصادرة لمحادثة جماعية، عليك أيضًا إضافة قيمة المَعلمة Audience
لأنّ النوع recipient
مرتبط بإمكانية العرض.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", listOf("Audience")).build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.SEND_MESSAGE", "message.recipient.@type", Arrays.asList("Audience")) .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
الإبلاغ عن استخدام اختصارات الرسائل الواردة
لتفعيل عملية إعداد تقارير الاستخدام عندما يتلقّى المستخدم رسالة، مثل رسالة قصيرة SMS أو رسالة محادثة أو رسالة إلكترونية أو إشعارات، عليك أيضًا تحديد عمليات ربط الإمكانيات في الاختصار من خلال ShortcutInfoCompat.Builder#addCapabilityBinding
باستخدام ميزة actions.intent.RECEIVE_MESSAGE
.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(firstName) .setLongLabel(fullName) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE") .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
إذا كانت الرسالة الواردة من محادثة جماعية، عليك أيضًا إضافة قيمة المَعلمة Audience
لأنّ النوع sender
مرتبط بإمكانية العرض.
Kotlin
val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", listOf("Audience")).build() ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)
Java
ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier) ... .setShortLabel(groupShortTitle) .setLongLabel(groupLongTitle) .setCategories(matchedCategories) .setLongLived(true) .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE", "message.sender.@type", Arrays.asList("Audience")) .build(); ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo);
استخدام AndroidX لتوفير كل من اختصارات المشاركة وSelectrTargets
ولكي تتمكّن من العمل مع مكتبة التوافق مع AndroidX، يجب أن يحتوي بيان التطبيق على مجموعة البيانات الوصفية selectr-target-service و intent-filters. يمكنك الاطّلاع على واجهة برمجة تطبيقات ChooserTargetService
Direct Share الحالية.
سبق وتم تعريف هذه الخدمة في مكتبة التوافق، لذا لا يحتاج المستخدم إلى تقديم بيان عن الخدمة في ملف بيان التطبيق. ومع ذلك، يجب أخذ الرابط من نشاط المشاركة إلى الخدمة في الاعتبار كمقدم استهداف محدد.
في المثال التالي، تم تنفيذ ChooserTargetService
بالشكل androidx.core.content.pm.ChooserTargetServiceCompat
، الذي تم تحديده مسبقًا في AndroidX:
<activity android:name=".SendMessageActivity" android:label="@string/app_name" android:theme="@style/SharingShortcutsDialogTheme"> <!-- This activity can respond to Intents of type SEND --> <intent-filter> <action android:name="android.intent.action.SEND" /> <category android:name="android.intent.category.DEFAULT" /> <data android:mimeType="text/plain" /> </intent-filter> <!-- Only needed if you import the sharetarget AndroidX library that provides backwards compatibility with the old DirectShare API. The activity that receives the Sharing Shortcut intent needs to be taken into account with this chooser target provider. --> <meta-data android:name="android.service.chooser.chooser_target_service" android:value="androidx.sharetarget.ChooserTargetServiceCompat" /> </activity>
الأسئلة الشائعة حول اختصارات المشاركة
كيف يتم تخزين بيانات استخدام الاختصار وهل يتم مغادرتها الجهاز؟
يتم تخزين الاختصارات بالكامل على الجهاز في دليل بيانات النظام في قسم مشفّر على القرص. لا يمكن الوصول إلى المعلومات الموجودة في اختصارات مثل الرمز والغرض وأسماء الأشخاص والموارد إلا من خلال خدمات النظام ونفس التطبيق الذي ينشر الاختصارات.
ما هو سجلّ "المشاركة المباشرة"؟
لقد أطلقنا ميزة "المشاركة المباشرة" في الإصدار Android 6.0 (المستوى 23 من واجهة برمجة التطبيقات) للسماح للتطبيقات
بتوفير عناصر ChooserTarget
من خلال ChooserTargetService
. كان يتم استرداد النتائج بشكل تفاعلي عند الطلب، ما أدى إلى بطء وقت تحميل الأهداف.
في Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، تم استبدال واجهة برمجة تطبيقات ميزة "المشاركة المباشرة" (ChooserTargetService
) بواجهة برمجة تطبيقات اختصارات المشاركة الجديدة. بدلاً من استرداد النتائج بشكل تفاعلي عند الطلب، تتيح واجهة برمجة التطبيقات لاختصارات المشاركة للتطبيقات إمكانية نشر أهداف "المشاركة المباشرة" مسبقًا. أدى ذلك إلى تسريع عملية استرداد أهداف "المشاركة المباشرة"
عند إعداد ShareSheet. ستستمر آلية "المشاركة المباشرة" في ChooserTargetService
في العمل، إلا أنّ النظام يصنّف الأهداف المقدَّمة بهذه الطريقة في ترتيب أقل من أي هدف يستخدم واجهة برمجة تطبيقات "اختصارات المشاركة".
أوقف نظام التشغيل Android 11 (المستوى 30 من واجهة برمجة التطبيقات) خدمة ChooserTargetService
نهائيًا،
وهي الطريقة الوحيدة لتوفير أهداف "المشاركة المباشرة".
كيف تختلف الاختصارات المنشورة لأهداف المشاركة عن اختصارات مشغّل التطبيقات (الاستخدام العادي للاختصارات عند الضغط مع الاستمرار على رموز التطبيقات في مشغّل التطبيقات)؟
وأي اختصارات يتم نشرها لغرض "المشاركة المستهدفة" هي أيضًا اختصار لمشغِّل التطبيقات، وسيتم عرضها في القائمة عند الضغط مع الاستمرار على رمز التطبيق. ينطبق أيضًا الحدّ الأقصى لعدد الاختصارات لكل نشاط على إجمالي عدد الاختصارات التي ينشرها التطبيق (أهداف المشاركة واختصارات مشغّل التطبيقات القديمة معًا).
ما هي الإرشادات المتعلقة بعدد اختصارات المشاركة التي يجب أن ينشرها المستخدم؟
يتم حصر عدد اختصارات المشاركة بالحدّ الأقصى نفسه للاختصارات الديناميكية المتاحة من خلال getMaxShortcutCountPerActivity(android.content.Context)
. ويمكن للمرء نشر أي رقم في هذا القيد ولكن يجب أن تضع في اعتبارك أن اختصارات المشاركة يمكن أن تكون مرئية
عند الضغط مع الاستمرار على مشغّل التطبيقات وفي ورقة المشاركة. تعرض معظم مشغّلات التطبيقات عند الضغط مع الاستمرار أربعة أو خمسة اختصارات كحد أقصى في الوضع العمودي، وثمانية اختصارات في الوضع الأفقي. راجِع الأسئلة الشائعة هذه لمعرفة مزيد من التفاصيل والإرشادات حول اختصارات المشاركة.