تقديم أهداف المشاركة المباشرة

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

ShortcutManagerCompat هي واجهة برمجة تطبيقات AndroidX توفّر اختصارات المشاركة، وهي متوافقة مع الإصدارات السابقة من واجهة برمجة التطبيقات ChooserTargetService التي تم إيقافها. هذه هي الطريقة المفضّلة لنشر كلّ من اختصارات المشاركة وChooserTargets. للحصول على تعليمات، يُرجى الاطّلاع على استخدام AndroidX لتوفير كلّ من اختصارات المشاركة وChooserTargets في هذه الصفحة.

نشر أهداف "المشاركة المباشرة"

لا يعرض صف "المشاركة المباشرة" في قائمة مشاركة البيانات سوى الاختصارات الديناميكية التي توفّرها Sharing Shortcuts API. أكمِل الخطوات التالية لنشر أهداف "المشاركة المباشرة".

1. في ملف موارد 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>
   

2. عند تهيئة تطبيقك، استخدِم 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);

3. إذا كنت بصدد تطوير تطبيق للتواصل، عليك الإبلاغ عن استخدام الاختصار من خلال 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);

4. إذا حذف المستخدِم جهة اتصال، استخدِم 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 المناسبة. على سبيل المثال، بالنسبة إلى تطبيق SMS، إذا لم تكن جهة الاتصال مفعّلة لخدمات الاتصالات التفاعلية (RCS) أو رسالة وسائط متعددة (MMS)، لن تربط الاختصار المقابل بأنواع MIME غير النصية، مثل image/* وvideo/*.
• بالنسبة إلى محادثة معيّنة، بعد إرسال اختصار ديناميكي والإبلاغ عن استخدامه، لا تغيِّر معرّف الاختصار. يضمن ذلك الاحتفاظ ببيانات الاستخدام لأغراض الترتيب.

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

‫Sharing Shortcuts API

بدءًا من 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.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
.addCapabilityBinding("actions.intent.SEND_MESSAGE").build()
ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

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 مرتبط بالإمكانية.

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)

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);

الإبلاغ عن استخدام الاختصارات للرسائل الواردة

لتفعيل الإبلاغ عن الاستخدام عندما يتلقّى المستخدِم رسالة، مثل رسالة قصيرة، رسالة محادثة أو رسالة إلكترونية أو إشعارات، عليك أيضًا تحديد روابط الإمكانات في الاختصار عبر ShortcutInfoCompat.Builder#addCapabilityBinding باستخدام إمكانية actions.intent.RECEIVE_MESSAGE.

val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticConversationIdentifier)
  ...
  .setShortLabel(firstName)
  .setLongLabel(fullName)
  .setCategories(matchedCategories)
  .setLongLived(true)
  .addCapabilityBinding("actions.intent.RECEIVE_MESSAGE").build()

ShortcutManagerCompat.pushDynamicShortcut(myContext, shortcutInfo)

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مرتبط بالإمكانية.

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)

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 وintent-filters. راجِع واجهة برمجة التطبيقات الحالية لـ ChooserTargetService "المشاركة المباشرة".

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

في المثال التالي، يكون تنفيذ 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>

الأسئلة الشائعة حول Sharing Shortcuts API

كيف يتم تخزين بيانات استخدام الاختصارات وهل تغادر الجهاز؟

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

ما هو سجلّ "المشاركة المباشرة"؟

طرحنا ميزة "المشاركة المباشرة" في Android 6.0 (مستوى واجهة برمجة التطبيقات 23) للسماح للتطبيقات بـ توفير كائنات ChooserTarget من خلال ChooserTargetService. تم استرداد النتائج بشكل تفاعلي عند الطلب، ما أدّى إلى بطء وقت تحميل الأهداف.

في Android 10 (مستوى واجهة برمجة التطبيقات 29)، استبدلنا واجهات برمجة التطبيقات لـ ChooserTargetService في "المشاركة المباشرة" بواجهة برمجة التطبيقات الجديدة Sharing Shortcuts API. بدلاً من استرداد النتائج بشكل تفاعلي عند الطلب، تتيح Sharing Shortcuts API للتطبيقات نشر أهداف "المشاركة المباشرة" مسبقًا. أدّى ذلك إلى تسريع عملية استرداد أهداف "المشاركة المباشرة" بشكل كبير عند إعداد ورقة المشاركة. ستستمر آلية "المشاركة المباشرة" في ChooserTargetService في العمل، ولكن يرتب النظام الأهداف التي يتم توفيرها بهذه الطريقة بترتيب أقل من أي هدف يستخدم Sharing Shortcuts API.

في Android 11 (مستوى واجهة برمجة التطبيقات 30)، تم إيقاف خدمة ChooserTargetService، وتُعدّ Sharing Shortcuts API الطريقة الوحيدة لتوفير أهداف "المشاركة المباشرة".

ما هو الفرق بين الاختصارات المنشورة لأهداف المشاركة واختصارات مشغّل التطبيقات (الاستخدام النموذجي للاختصارات عند النقر مع الاستمرار على رموز التطبيقات في مشغّل التطبيقات)؟

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

ما هي الإرشادات بشأن عدد اختصارات المشاركة التي يجب نشرها؟

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