
استخدِم أهداف ميزة "المشاركة المباشرة" لتسهيل وتسريع مشاركة المستخدمين لعناوين URL أو صور أو أنواع أخرى من البيانات مع تطبيقك من تطبيقات أخرى. تعمل ميزة "المشاركة المباشرة" من خلال عرض جهات الاتصال من تطبيقات المراسلة ووسائل التواصل الاجتماعي مباشرةً في ورقة المشاركة على Android، بدون أن يضطر المستخدمون إلى اختيار التطبيق ثم البحث عن جهة الاتصال.
ShortcutManagerCompat
هي واجهة برمجة تطبيقات AndroidX توفّر اختصارات المشاركة، وهي متوافقة مع الإصدارات القديمة من واجهة برمجة التطبيقات ChooserTargetService
المتوقّفة نهائيًا. هذه هي الطريقة المفضّلة لنشر كلّ من "اختصارات المشاركة" وChooserTargets
. للحصول على التعليمات، يُرجى الاطّلاع على استخدام AndroidX لتوفير كل من "اختصارات المشاركة" وChooserTargets في هذه الصفحة.
نشر أهداف المشاركة المباشرة
لا يعرض صف "المشاركة المباشرة" في ورقة المشاركة سوى الاختصارات الديناميكية التي توفّرها واجهة برمجة التطبيقات Sharing Shortcuts API. أكمِل الخطوات التالية لنشر أهداف "المشاركة المباشرة".
في ملف موارد XML الخاص بتطبيقك، عرِّف عناصر
share-target
.<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 يومًا.
- بالنسبة إلى تطبيقات الرسائل القصيرة، تجنَّب توفير اختصارات للرموز القصيرة أو المحادثات التي تم تحديدها على أنّها محتوى غير مرغوب فيه محتمل. ومن غير المرجّح أن يشارك المستخدمون في هذه المحادثات.
- اتّصِل بالرقم
setCategories()
لربط الاختصارmimeType
بالسمات المناسبة. على سبيل المثال، بالنسبة إلى تطبيق الرسائل القصيرة، إذا لم تكن جهة الاتصال مفعّلة لخدمة الاتصالات التفاعلية (RCS) أو رسائل الوسائط المتعددة (MMS)، لن تتمكّن من ربط الاختصار المقابل بأنواع MIME غير النصية، مثلimage/*
وvideo/*
. - بالنسبة إلى محادثة معيّنة، بعد إرسال اختصار ديناميكي والإبلاغ عن استخدامه، لا تغيِّر معرّف الاختصار. ويضمن ذلك الاحتفاظ ببيانات الاستخدام لأغراض الترتيب.
إذا نقر المستخدم على أي هدف من أهداف "المشاركة المباشرة"، يجب أن ينقله تطبيقك إلى واجهة مستخدم حيث يمكنه تنفيذ إجراء مباشرةً على موضوع الهدف. لا تعرض واجهة مستخدم لإزالة الغموض، ولا تضع المستخدم في واجهة مستخدم غير مرتبطة بالعنصر الذي تم النقر عليه. على سبيل المثال، في تطبيق مراسلة، يؤدي النقر على هدف "المشاركة المباشرة" إلى نقل المستخدم إلى عرض المحادثة مع الشخص الذي اختاره. تظهر لوحة المفاتيح ويتم ملء الرسالة مسبقًا بالبيانات المشترَكة.
Sharing Shortcuts API
بدءًا من Android 10 (المستوى 29 لواجهة برمجة التطبيقات)،
تمت إضافة ShortcutInfo.Builder
وطرق تحسين
توفر معلومات إضافية عن هدف المشاركة:
setCategories()
- بدءًا من Android 10، تُستخدَم الفئات أيضًا لفلترة الاختصارات التي يمكنها التعامل مع نوايا المشاركة أو الإجراءات. راجِع تعريف هدف للمشاركة للحصول على التفاصيل. هذا الحقل مطلوب للاختصارات المخصّصة للاستخدام كأهداف للمشاركة.
setLongLived()
تحدّد هذه السمة ما إذا كان الاختصار صالحًا عندما يتم إلغاء نشره أو إخفاؤه بواسطة التطبيق (كاختصار ديناميكي أو مثبَّت). إذا كان الاختصار صالحًا لفترة طويلة، يمكن أن تخزّنه مؤقتًا العديد من خدمات النظام حتى بعد إلغاء نشره كاختصار ديناميكي.
يمكن أن يؤدي جعل الاختصار صالحًا لفترة طويلة إلى تحسين ترتيبه. يمكنك الاطّلاع على الحصول على أفضل ترتيب لمعرفة التفاصيل.
setShortLabel()
،setLongLabel()
عند نشر اختصار لشخص معيّن، يُرجى تضمين اسمه الكامل في
setLongLabel()
وأي اسم مختصر، مثل لقب أو اسم أول، فيsetShortLabel()
.
اطّلِع على مثال على نشر "اختصارات المشاركة" على GitHub.
توفير صور الاختصارات
لإنشاء "اختصار مشاركة"، عليك إضافة صورة من خلال setIcon()
.
يمكن أن تظهر "اختصارات المشاركة" على جميع مساحات عرض النظام، وقد يتم تغيير شكلها.
بالإضافة إلى ذلك، قد تعرض بعض الأجهزة التي تعمل بالإصدارات 7 أو 8 أو 9 من نظام التشغيل Android (المستويات 25 و26 و27 و28 من واجهة برمجة التطبيقات) رموزًا تستخدم الصور النقطية فقط بدون خلفية، ما يؤدي إلى انخفاض التباين بشكل كبير. لضمان ظهور الاختصار بالشكل المطلوب،
قدِّم صورة نقطية قابلة للتكيّف باستخدام IconCompat.createWithAdaptiveBitmap()
.
تأكَّد من أنّ الصور النقطية التكيُّفية تتّبع الإرشادات والأبعاد نفسها المحدّدة للرموز التكيُّفية. وأكثر الطرق شيوعًا لتحقيق ذلك هو تغيير حجم الصورة النقطية المربّعة المقصودة إلى 72×72 وحدة بكسل مستقلة الكثافة وتوسيطها ضمن لوحة قماشية شفافة بحجم 108×108 وحدة بكسل مستقلة الكثافة. إذا كان الرمز يتضمّن مناطق شفافة، عليك تضمين لون خلفية، وإلا ستظهر المناطق الشفافة باللون الأسود.
لا تقدّم صورًا مقنّعة بشكل معيّن. على سبيل المثال، قبل الإصدار
Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، كان من الشائع توفير صور رمزية للمستخدمين في
ChooserTarget
ميزة "المشاركة المباشرة"ChooserTarget
يتم إخفاؤها في شكل دائرة. تعمل ورقة المشاركة في Android ومساحات عرض النظام الأخرى في نظام التشغيل Android 10 الآن على تشكيل صور الاختصارات وتحديد تصميمها.
الطريقة المفضّلة لتوفير "اختصارات المشاركة" هي من خلال
ShortcutManagerCompat
،
التي تحوّل تلقائيًا عناصر ChooserTarget
"المشاركة المباشرة" المتوافقة مع الإصدارات القديمة إلى
دوائر.
تحديد هدف المشاركة
يجب الإعلان عن أهداف المشاركة في ملف موارد التطبيق، على غرار تعريفات الاختصارات الثابتة. أضِف تعريفات share
target داخل العنصر الجذر <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 لتوفير كلّ من "اختصارات المشاركة" وChooserTargets
لاستخدام مكتبة التوافق AndroidX، يجب أن يتضمّن بيان التطبيق مجموعة البيانات الوصفية chooser-target-service وفلاتر الأهداف. يمكنك الاطّلاع على ChooserTargetService
Direct Share API الحالية.
يتم الإعلان عن هذه الخدمة مسبقًا في مكتبة التوافق، لذا لا يحتاج المستخدم إلى الإعلان عنها في بيان التطبيق. ومع ذلك، يجب أخذ الرابط من نشاط المشاركة إلى الخدمة في الاعتبار كموفّر هدف في أداة الاختيار.
في المثال التالي، يكون تنفيذ 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>
الأسئلة الشائعة حول اختصارات ميزة المشاركة
كيف يتم تخزين بيانات استخدام الاختصارات وهل يتم نقلها من الجهاز؟
يتم تخزين الاختصارات بالكامل على الجهاز في دليل بيانات النظام في قسم مشفّر من القرص. لا يمكن الوصول إلى المعلومات الواردة في الاختصارات، مثل الرمز والهدف وأسماء الأشخاص والموارد، إلا من خلال خدمات النظام والتطبيق نفسه الذي ينشر الاختصارات.
ما هو سجلّ ميزة "المشاركة المباشرة"؟
قدّمنا ميزة "المشاركة المباشرة" في الإصدار 6.0 من نظام التشغيل Android (المستوى 23 من واجهة برمجة التطبيقات) للسماح للتطبيقات بتوفير عناصر ChooserTarget
من خلال ChooserTargetService
. تم استرداد النتائج بشكل تفاعلي عند الطلب، ما أدّى إلى بطء وقت التحميل للأهداف.
في Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، استبدلنا واجهات برمجة التطبيقات ChooserTargetService
Direct
Share بواجهة برمجة التطبيقات الجديدة Sharing Shortcuts. بدلاً من استرداد النتائج بشكل تفاعلي عند الطلب، تتيح واجهة برمجة التطبيقات "اختصارات المشاركة" للتطبيقات نشر أهداف "المشاركة المباشرة" مسبقًا. وقد أدّى ذلك إلى تسريع عملية استرداد أهداف Direct Share بشكل كبير عند إعداد ShareSheet. سيظل بإمكانك استخدام آلية ChooserTargetService
المشاركة المباشرة
، ولكن سيرتّب النظام الأهداف التي يتم توفيرها بهذه الطريقة في مرتبة أدنى من أي هدف يستخدم واجهة برمجة التطبيقات "اختصارات المشاركة".
أوقف الإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات) خدمة ChooserTargetService
، وأصبحت واجهة برمجة التطبيقات "اختصارات المشاركة" هي الطريقة الوحيدة لتوفير أهداف ميزة "المشاركة المباشرة".
ما الفرق بين اختصارات أهداف المشاركة المنشورة واختصارات مشغّل التطبيقات (الاستخدام المعتاد للاختصارات عند النقر مع الاستمرار على رموز التطبيقات في مشغّل التطبيقات)؟
أي اختصارات تم نشرها لغرض "هدف المشاركة" هي أيضًا اختصارات مشغّل، وستظهر في القائمة عند الضغط مع الاستمرار على رمز تطبيقك. ينطبق الحدّ الأقصى لعدد الاختصارات المسموح به لكل نشاط أيضًا على إجمالي عدد الاختصارات التي ينشرها التطبيق (أهداف المشاركة واختصارات مشغّل التطبيق القديمة معًا).
ما هي الإرشادات المتعلّقة بعدد اختصارات المشاركة التي يجب نشرها؟
يخضع عدد اختصارات المشاركة للحدّ نفسه الذي ينطبق على الاختصارات الديناميكية المتاحة من خلال getMaxShortcutCountPerActivity(android.content.Context)
. يمكن نشر أي عدد من الاختصارات ضمن هذا الحد، ولكن يجب مراعاة أنّ مشاركة الاختصارات يمكن أن تظهر عند الضغط مع الاستمرار على مشغّل التطبيقات وفي ورقة المشاركة. تعرض معظم مشغّلات التطبيقات عند الضغط مع الاستمرار أربعة أو خمسة اختصارات كحد أقصى في الوضع العمودي، وثمانية في الوضع الأفقي. يمكنك الاطّلاع على
الأسئلة الشائعة
لمزيد من التفاصيل والإرشادات حول مشاركة الاختصارات.