اهداف اشتراک مستقیم را ارائه دهید

از اهداف اشتراک‌گذاری مستقیم استفاده کنید تا کاربران سایر برنامه‌ها بتوانند آدرس‌های اینترنتی، تصاویر یا انواع دیگر داده‌ها را با برنامه خود به اشتراک بگذارند. Direct Share با ارائه مخاطبین از برنامه‌های پیام‌رسان و اجتماعی به‌طور مستقیم در اشتراک‌گذاری Android، بدون اینکه کاربران مجبور باشند برنامه را انتخاب کنند و مخاطب را جستجو کنند، کار می‌کند.

ShortcutManagerCompat یک API AndroidX است که میانبرهای اشتراک گذاری را ارائه می دهد و با API منسوخ ChooserTargetService سازگار است. این روش ترجیحی برای انتشار میانبرهای اشتراک گذاری و ChooserTargets است. برای دستورالعمل‌ها، به استفاده از AndroidX برای ارائه میانبرهای اشتراک‌گذاری و ChooserTargets در این صفحه مراجعه کنید.

انتشار اهداف اشتراک مستقیم

ردیف اشتراک‌گذاری مستقیم Sharesheet فقط میانبرهای پویا ارائه شده توسط 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 روز گذشته کهنه تلقی می شود.

   کاتلین

   ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))

   جاوا

   List<ShortcutInfoCompat> shortcuts = new ArrayList<>();
   shortcuts.add(shortcut1);
   shortcuts.add(shortcut2);
   ...
   ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);

3. اگر در حال توسعه یک برنامه ارتباطی هستید، هر بار که کاربر پیامی را دریافت یا به مخاطبی ارسال کرد، فوراً استفاده از میانبر را از طریق pushDynamicShortcut گزارش دهید. برای اطلاعات بیشتر به گزارش استفاده از میانبر برای برنامه های ارتباطی در این صفحه مراجعه کنید. به عنوان مثال، با مشخص کردن اتصالات قابلیت در میانبر از طریق 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);

4. اگر کاربر مخاطبی را حذف کرد، از removeLongLivedShortcut استفاده کنید. این روش ترجیحی برای حذف میانبر بدون توجه به اینکه آیا توسط سرویس های سیستم کش شده است یا نه، ترجیح داده می شود. قطعه کد زیر نمونه ای از نحوه انجام این کار را نشان می دهد.

   کاتلین

   val deleteShortcutId = "..."
   ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))

   جاوا

   String deleteShortcutId = "...";
   ShortcutManagerCompat.removeLongLivedShortcuts(
       myContext, Arrays.asList(deleteShortcutId));

رتبه بندی اهداف اشتراک مستقیم خود را بهبود بخشید

اشتراک‌گذاری Android تعداد ثابتی از اهداف اشتراک مستقیم را نشان می‌دهد. این پیشنهادات بر اساس رتبه مرتب شده اند. با انجام کارهای زیر می توانید رتبه بندی میانبرهای خود را به طور بالقوه بهبود بخشید:

• اطمینان حاصل کنید که همه shortcutIds منحصر به فرد هستند و هرگز برای اهداف مختلف استفاده مجدد نمی شوند.
• با فراخوانی setLongLived(true) از عمر طولانی میانبر اطمینان حاصل کنید.
• برای میانبرهای مربوط به مکالمه، با انتشار مجدد میانبرهای مربوطه از طریق ShortcutManagerCompat.pushDynamicShortcut ، استفاده از میانبر را برای پیام های خروجی و ورودی گزارش دهید. برای جزئیات به گزارش استفاده از میانبر برای برنامه های ارتباطی در این صفحه مراجعه کنید.
• از ارائه اهداف اشتراک گذاری مستقیم نامربوط یا قدیمی خودداری کنید - به عنوان مثال، مخاطبینی که کاربر در 30 روز گذشته پیامی ارسال نکرده است.
• برای برنامه‌های پیامک، از ارائه میانبر برای کدهای کوتاه یا مکالمه‌هایی که به‌عنوان هرزنامه احتمالی شناسایی شده‌اند، خودداری کنید. احتمال اشتراک گذاری کاربران در آن مکالمات بسیار کم است.
• برای مرتبط کردن میانبر با ویژگی‌های mimeType مناسب setCategories() فراخوانی کنید. به عنوان مثال، برای یک برنامه پیام کوتاه، اگر مخاطب دارای RCS یا MMS نباشد، میانبر مربوطه را با انواع MIME غیر متنی مانند image/* و video/* مرتبط نمی‌کنید.
• برای یک مکالمه مشخص، هنگامی که میانبر پویا فشار داده شد و استفاده از آن گزارش شد، شناسه میانبر را تغییر ندهید. این امر حفظ داده های استفاده را برای رتبه بندی تضمین می کند.

اگر کاربر روی هر هدف Direct Share ضربه بزند، برنامه شما باید آنها را به یک UI ببرد تا بتواند مستقیماً روی موضوع مورد نظر اقدامی انجام دهد. به کاربر یک رابط کاربری ابهام‌زدایی ارائه ندهید، و او را در رابط کاربری غیرمرتبط با هدف مورد استفاده قرار ندهید. به عنوان مثال، در یک برنامه پیام رسانی، ضربه زدن روی یک هدف اشتراک مستقیم کاربر را به نمای مکالمه با شخصی که انتخاب کرده است می برد. صفحه کلید قابل مشاهده است و پیام از قبل با داده های مشترک پر شده است.

اشتراک گذاری میانبرهای میانبر

با شروع Android 10 (سطح API 29)، ShortcutInfo.Builder روش‌ها و پیشرفت‌هایی را اضافه کرد که اطلاعات بیشتری درباره هدف اشتراک‌گذاری ارائه می‌دهد:

setCategories()

با شروع اندروید 10، دسته‌ها نیز برای فیلتر کردن میانبرهایی استفاده می‌شوند که می‌توانند اهداف یا اقدامات اشتراک‌گذاری را مدیریت کنند. برای جزئیات بیشتر به اعلام هدف سهم مراجعه کنید. این فیلد برای میانبرهایی که به‌عنوان اهداف اشتراک‌گذاری استفاده می‌شوند، لازم است.

setLongLived()

مشخص می کند که آیا یک میانبر زمانی معتبر است که توسط برنامه منتشر نشده یا نامرئی شده باشد (به عنوان میانبر پویا یا پین شده). اگر یک میانبر عمر طولانی داشته باشد، حتی پس از اینکه به عنوان میانبر پویا منتشر نشده باشد، می توان آن را توسط سرویس های مختلف سیستم کش ذخیره کرد.

ایجاد میانبر با عمر طولانی می تواند رتبه آن را بهبود بخشد. برای جزئیات بیشتر به دریافت بهترین رتبه مراجعه کنید.

setShortLabel() , setLongLabel()

هنگام انتشار میانبر برای یک شخص، لطفاً نام کامل او را در setLongLabel() و هر نام کوتاهی مانند نام مستعار یا نام کوچک را در setShortLabel() وارد کنید.

به نمونه ای از انتشار میانبرهای اشتراک گذاری در GitHub نگاه کنید.

ارائه تصاویر میانبر

برای ایجاد میانبر اشتراک گذاری، باید یک تصویر از طریق setIcon() اضافه کنید.

میانبرهای اشتراک‌گذاری می‌توانند در سطوح سیستم ظاهر شوند و ممکن است تغییر شکل دهند. به‌علاوه، برخی از دستگاه‌هایی که از نسخه‌های ۷، ۸ یا ۹ Android استفاده می‌کنند (سطوح API ۲۵، ۲۶، ۲۷، و ۲۸) ممکن است نمادهای فقط بیت مپ را بدون پس‌زمینه نمایش دهند که کنتراست را به‌طور چشمگیری کاهش می‌دهد. برای اطمینان از اینکه میانبر شما همانطور که در نظر گرفته شده است، یک بیت مپ تطبیقی ​​با استفاده از IconCompat.createWithAdaptiveBitmap() ارائه دهید.

مطمئن شوید که بیت مپ های تطبیقی ​​از دستورالعمل ها و ابعادی که برای نمادهای تطبیقی ​​تنظیم شده است پیروی می کنند. متداول ترین راه برای انجام این کار این است که بیت مپ مربعی مورد نظر را به 72x72 dp تغییر دهید و آن را در یک بوم شفاف 108x108 dp قرار دهید. اگر نماد شما شامل مناطق شفاف است، باید یک رنگ پس‌زمینه نیز اضافه کنید. در غیر این صورت، مناطق شفاف سیاه به نظر می رسند.

تصاویری را که به شکل خاصی پوشانده شده اند ارائه نکنید. به عنوان مثال، قبل از Android 10 (سطح API 29)، ارائه آواتارهای کاربر برای Direct Share ChooserTarget که روی یک دایره پوشانده شده بودند، معمول بود. اشتراک‌گذاری Android و سایر سطوح سیستم در Android 10 اکنون تصاویر میانبر را شکل می‌دهند و طرح زمینه. روش ارجح برای ارائه میانبرهای اشتراک گذاری، از طریق ShortcutManagerCompat ، به طور خودکار اشیاء بککامپ Direct Share 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 (API 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 کار کنید، مانیفست برنامه باید حاوی مجموعه متا داده انتخابگر-هدف-سرویس و فیلترهای هدف باشد. API اشتراک مستقیم 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>

سوالات متداول میانبرهای اشتراک گذاری

داده های استفاده از میانبر چگونه ذخیره می شوند و آیا از دستگاه خارج می شوند؟

میانبرها به طور کامل روی دستگاه در فهرست داده های سیستم در یک پارتیشن دیسک رمزگذاری شده ذخیره می شوند. اطلاعات موجود در میانبرها مانند نماد، هدف و نام افراد و منابع فقط توسط سرویس های سیستم و همان برنامه ای که میانبرها را منتشر می کند قابل دسترسی است.

تاریخچه اشتراک گذاری مستقیم چیست؟

ما Direct Share را در Android 6.0 (سطح API 23) معرفی کردیم تا به برنامه‌ها اجازه دهیم اشیاء ChooserTarget را از طریق ChooserTargetService ارائه کنند. نتایج به صورت واکنشی در صورت تقاضا بازیابی شدند که منجر به کاهش زمان بارگذاری برای اهداف شد.

در اندروید 10 (سطح API 29)، APIهای اشتراک مستقیم ChooserTargetService با API جدید Shortcuts به اشتراک گذاری جایگزین کردیم. به جای بازیابی نتایج به صورت واکنشی در صورت تقاضا، اشتراک‌گذاری میانبرهای API به برنامه‌ها اجازه می‌دهد اهداف اشتراک‌گذاری مستقیم را از قبل منتشر کنند. این امر به سرعت فرآیند بازیابی اهداف اشتراک مستقیم را هنگام تهیه ShareSheet سرعت بخشید. مکانیسم اشتراک گذاری مستقیم ChooserTargetService به کار خود ادامه می دهد، اما سیستم اهدافی را که به این ترتیب ارائه می شوند، پایین تر از هر هدفی که از اشتراک گذاری میانبرهای API استفاده می کند، رتبه بندی می کند.

Android 11 (سطح API 30) سرویس ChooserTargetService منسوخ کرد و Sharing Shortcuts API تنها راه برای ارائه اهداف اشتراک مستقیم است.

میانبرهای منتشر شده برای اهداف اشتراک‌گذاری چه تفاوتی با میانبرهای راه‌انداز دارند (استفاده معمولی از میانبرها هنگام فشار طولانی روی نمادهای برنامه در راه‌انداز)؟

هر میانبر منتشر شده برای "هدف اشتراک گذاری"، همچنین یک میانبر راه اندازی است و با فشار طولانی روی نماد برنامه در منو نشان داده می شود. حداکثر محدودیت تعداد میانبرها در هر فعالیت همچنین برای تعداد کل میانبرهایی که یک برنامه منتشر می کند اعمال می شود (هدف های اشتراک گذاری و میانبرهای راه انداز قدیمی ترکیبی).

راهنمایی در مورد تعداد میانبرهای اشتراک گذاری که باید منتشر شود چیست.

تعداد میانبرهای اشتراک‌گذاری به همان حد میانبرهای پویا که از طریق getMaxShortcutCountPerActivity(android.content.Context) در دسترس هستند، محدود شده است. می‌توان هر عددی را تا آن حد منتشر کرد، اما باید در نظر داشت که میانبرهای اشتراک‌گذاری را می‌توان در راه‌انداز برنامه با فشار طولانی و در برگه اشتراک‌گذاری قابل مشاهده بود. اکثر راه‌اندازهای برنامه با فشار طولانی حداکثر چهار یا پنج میانبر در حالت عمودی و هشت میانبر در حالت افقی نمایش می‌دهند. برای جزئیات بیشتر و راهنمایی در مورد اشتراک‌گذاری میان‌برها، این پرسش‌های متداول را ببینید.