
از اهداف اشتراکگذاری مستقیم (Direct Share) استفاده کنید تا کاربران برنامههای دیگر بتوانند URLها، تصاویر یا سایر انواع دادهها را با برنامه شما آسانتر و سریعتر به اشتراک بگذارند. اشتراکگذاری مستقیم با ارائه مخاطبین از برنامههای پیامرسان و اجتماعی به طور مستقیم در صفحه اشتراکگذاری اندروید کار میکند، بدون اینکه کاربران مجبور باشند برنامه را انتخاب کرده و سپس مخاطب را جستجو کنند.
ShortcutManagerCompat یک API اندروید ایکس است که میانبرهای اشتراکگذاری را ارائه میدهد و با API منسوخشدهی ChooserTargetService سازگار است. این روش ترجیحی برای انتشار هر دوی میانبرهای اشتراکگذاری و ChooserTargets است. برای دستورالعملها، به بخش «استفاده از اندروید ایکس برای ارائهی میانبرهای اشتراکگذاری و ChooserTargets» در این صفحه مراجعه کنید.
انتشار اهداف اشتراکگذاری مستقیم
ردیف Sharesheet Direct Share فقط میانبرهای پویای ارائه شده توسط Sharing Shortcuts API را نمایش میدهد. برای انتشار اهداف Direct Share، مراحل زیر را انجام دهید.
در فایل منبع 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 روز گذشته هیچ فعالیتی از سوی کاربر نداشته باشد، قدیمی تلقی میشود.
کاتلین
ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
جاوا
List<ShortcutInfoCompat> shortcuts = new ArrayList<>(); shortcuts.add(shortcut1); shortcuts.add(shortcut2); ... ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
اگر در حال توسعه یک برنامه ارتباطی هستید، هر بار که کاربر پیامی را دریافت یا به مخاطبی ارسال میکند، بلافاصله از طریق
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);
اگر کاربر یک مخاطب را حذف کند،
removeLongLivedShortcutاستفاده کنید. این روش ترجیحی برای حذف میانبر است، صرف نظر از اینکه آیا توسط سرویسهای سیستم ذخیره شده است یا خیر. قطعه کد زیر مثالی از نحوه انجام این کار را نشان میدهد.کاتلین
val deleteShortcutId = "..." ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
جاوا
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
رتبهبندی اهداف اشتراکگذاری مستقیم خود را بهبود بخشید
صفحه اشتراکگذاری اندروید تعداد ثابتی از اهداف اشتراکگذاری مستقیم را نشان میدهد. این پیشنهادها بر اساس رتبهبندی مرتب شدهاند. شما میتوانید با انجام موارد زیر رتبهبندی میانبرهای خود را بهبود بخشید:
- مطمئن شوید که همه
shortcutIdsمنحصر به فرد هستند و هرگز برای اهداف مختلف استفاده مجدد نمیشوند. - با فراخوانی
setLongLived(true)از ماندگاری میانبر اطمینان حاصل کنید. - برای میانبرهای مربوط به مکالمه، با انتشار مجدد میانبرهای مربوطه از طریق
ShortcutManagerCompat.pushDynamicShortcut، میزان استفاده از میانبر برای پیامهای خروجی و ورودی را گزارش دهید. برای جزئیات بیشتر به بخش «گزارش استفاده از میانبر برای برنامههای ارتباطی» در این صفحه مراجعه کنید. - از ارائه اهداف اشتراکگذاری مستقیم نامرتبط یا قدیمی خودداری کنید - برای مثال، مخاطبینی که کاربر در 30 روز گذشته به آنها پیام نداده است.
- برای برنامههای پیامکی، از ارائه میانبر برای کدهای کوتاه یا مکالماتی که به عنوان هرزنامه احتمالی شناسایی میشوند، خودداری کنید. احتمال اینکه کاربران در این مکالمات اشتراکگذاری کنند، بسیار کم است.
- برای مرتبط کردن میانبر با ویژگیهای
mimeTypeمناسب، تابعsetCategories()را فراخوانی کنید. برای مثال، برای یک برنامه پیامکی، اگر مخاطب RCS یا MMS فعال نباشد، میانبر مربوطه را با انواع MIME غیر متنی مانندimage/*وvideo/*مرتبط نخواهید کرد. - برای یک مکالمه مشخص، به محض اینکه یک میانبر پویا اعمال شد و میزان استفاده گزارش شد، شناسه میانبر را تغییر ندهید. این کار حفظ دادههای استفاده برای رتبهبندی را تضمین میکند.
اگر کاربر روی هر هدف اشتراکگذاری مستقیم ضربه بزند، برنامه شما باید او را به رابط کاربریای ببرد که بتواند مستقیماً روی موضوع هدف، عملی انجام دهد. رابط کاربری ابهامزدایی به کاربر ارائه ندهید و او را در رابط کاربری نامرتبط با هدف ضربهزدهشده قرار ندهید. برای مثال، در یک برنامه پیامرسان، ضربه زدن روی هدف اشتراکگذاری مستقیم، کاربر را به نمای مکالمه با شخصی که انتخاب کرده است، میبرد. صفحهکلید قابل مشاهده است و پیام از قبل با دادههای اشتراکگذاریشده پر شده است.
API اشتراکگذاری میانبرها
از اندروید ۱۰ (سطح API ۲۹)، ShortcutInfo.Builder متدها و بهبودهایی را اضافه کرد که اطلاعات بیشتری در مورد هدف اشتراکگذاری ارائه میدهند:
-
setCategories() - از اندروید ۱۰ به بعد، از دستهها برای فیلتر کردن میانبرهایی که میتوانند اهداف یا اقدامات اشتراکگذاری را مدیریت کنند نیز استفاده میشود. برای جزئیات بیشتر به بخش «اعلان هدف اشتراکگذاری» مراجعه کنید. این فیلد برای میانبرهایی که قرار است به عنوان اهداف اشتراکگذاری استفاده شوند، الزامی است.
-
setLongLived() مشخص میکند که آیا یک میانبر، زمانی که توسط برنامه (به عنوان یک میانبر پویا یا پین شده) منتشر نشده یا نامرئی شده است، معتبر است یا خیر. اگر یک میانبر برای مدت طولانی وجود داشته باشد، میتواند توسط سرویسهای مختلف سیستم حتی پس از انتشار نیافتن به عنوان یک میانبر پویا، ذخیره شود.
طولانی کردن عمر یک میانبر میتواند رتبه آن را بهبود بخشد. برای جزئیات بیشتر به «بهترین رتبه را بگیرید» مراجعه کنید.
-
setShortLabel(),setLongLabel() هنگام انتشار یک میانبر برای یک شخص خاص، لطفاً نام کامل او را در
setLongLabel()و هرگونه نام کوتاه، مانند لقب یا نام کوچک، را درsetShortLabel()وارد کنید.
به نمونهای از انتشار «میانبرهای اشتراکگذاری» در گیتهاب نگاه کنید.
تصاویر میانبر ارائه دهید
برای ایجاد یک میانبر اشتراکگذاری، باید یک تصویر را از طریق setIcon() اضافه کنید.
میانبرهای اشتراکگذاری میتوانند در سطوح مختلف سیستم ظاهر شوند و ممکن است تغییر شکل داده شوند. علاوه بر این، برخی از دستگاههایی که نسخههای ۷، ۸ یا ۹ اندروید (سطح API 25، ۲۶، ۲۷ و ۲۸) را اجرا میکنند، ممکن است آیکونهای فقط بیتمپ را بدون پسزمینه نمایش دهند که به طور چشمگیری کنتراست را کاهش میدهد. برای اطمینان از اینکه میانبر شما همانطور که در نظر گرفته شده به نظر میرسد، با استفاده از IconCompat.createWithAdaptiveBitmap() یک بیتمپ تطبیقی ایجاد کنید.
مطمئن شوید که بیتمپهای تطبیقی از همان دستورالعملها و ابعاد تعیینشده برای آیکونهای تطبیقی پیروی میکنند. رایجترین روش برای انجام این کار، مقیاسبندی بیتمپ مربعی مورد نظر به ۷۲x۷۲ dp و قرار دادن آن در مرکز یک بوم شفاف ۱۰۸x۱۰۸ dp است. اگر آیکون شما شامل نواحی شفاف است، باید یک رنگ پسزمینه نیز در آن قرار دهید. در غیر این صورت، نواحی شفاف سیاه به نظر میرسند.
تصاویر را به صورت ماسک شده با یک شکل خاص ارائه ندهید. به عنوان مثال، قبل از اندروید ۱۰ (سطح API ۲۹)، ارائه آواتارهای کاربر برای Direct Share ChooserTarget ها که به صورت دایره ماسک شده بودند، رایج بود. صفحه اشتراکگذاری اندروید و سایر سطوح سیستم در اندروید ۱۰ اکنون تصاویر میانبر را شکل داده و تمبندی میکنند. روش ترجیحی برای ارائه میانبرهای اشتراکگذاری، از طریق 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>
عنصر داده در یک هدف اشتراکی مشابه مشخصات داده در یک فیلتر intent است. هر هدف اشتراکی میتواند چندین دسته داشته باشد که فقط برای تطبیق میانبرهای منتشر شده یک برنامه با تعاریف هدف اشتراکی آن استفاده میشوند. دستهها میتوانند هر مقدار دلخواهی که توسط برنامه تعریف شده است را داشته باشند.
در صورتی که کاربر در صفحه اشتراکگذاری اندروید، میانبر اشتراکگذاری را انتخاب کند که با مثال target-share در بالا مطابقت داشته باشد، برنامه قصد اشتراکگذاری زیر را دریافت خواهد کرد:
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 در دسترس نخواهد بود و در صورت نیاز باید شناسه را به صورت دستی ارسال کنید.
گزارش استفاده از میانبر برای برنامههای ارتباطی
اگر در حال توسعه یک برنامه ارتباطی هستید، میتوانید با گزارش میزان استفاده از پیامهای خروجی و ورودی، رتبه خود را در صفحه اشتراکگذاری اندروید بهبود بخشید. برای انجام این کار، میانبر مکالمهای که نشان دهنده مخاطب است را از طریق ShortcutManagerCompat.pushDynamicShortcut دوباره منتشر کنید.
استفاده از میانبرها و پیوندهای قابلیت با اندروید ۵.۰ (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 کار کنید، فایل مانیفست برنامه باید شامل مجموعه فرادادههای chooser-target-service و intent-filters باشد. به API فعلی 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>
سوالات متداول در مورد میانبرهای اشتراکگذاری
دادههای استفاده از میانبر چگونه ذخیره میشوند و آیا از دستگاه خارج میشوند؟
میانبرها کاملاً روی دستگاه در دایرکتوری دادههای سیستم در یک پارتیشن دیسک رمزگذاری شده ذخیره میشوند. اطلاعات موجود در میانبرها مانند آیکون، هدف و نام افراد و منابع فقط توسط سرویسهای سیستم و همان برنامهای که میانبرها را منتشر میکند، قابل دسترسی هستند.
تاریخچهی اشتراکگذاری مستقیم چیست؟
ما قابلیت اشتراکگذاری مستقیم (Direct Share) را در اندروید ۶.۰ (سطح API ۲۳) معرفی کردیم تا به برنامهها اجازه دهیم اشیاء ChooserTarget را از طریق یک ChooserTargetService ارائه دهند. نتایج به صورت واکنشی و بر اساس تقاضا بازیابی میشدند که منجر به زمان بارگذاری آهسته برای اهداف میشد.
در اندروید ۱۰ (API سطح ۲۹)، ما APIهای اشتراکگذاری مستقیم ChooserTargetService را با API جدید Sharing Shortcuts جایگزین کردیم. به جای بازیابی نتایج به صورت واکنشی در صورت تقاضا، API Sharing Shortcuts به برنامهها اجازه میدهد تا اهداف Direct Share را از قبل منتشر کنند. این امر به سرعت روند بازیابی اهداف Direct Share را هنگام آمادهسازی ShareSheet تسریع کرد. مکانیسم ChooserTargetService Direct Share به کار خود ادامه خواهد داد، اما سیستم، اهدافی را که به این روش ارائه میشوند، پایینتر از هر هدفی که از Sharing Shortcuts API استفاده میکند، رتبهبندی میکند.
اندروید ۱۱ (API سطح ۳۰) سرویس ChooserTargetService منسوخ کرد و Sharing Shortcuts API تنها راه ارائه اهداف Direct Share است.
میانبرهای منتشر شده برای اهداف اشتراکگذاری چه تفاوتی با میانبرهای لانچر (استفاده معمول از میانبرها هنگام فشار دادن طولانی مدت روی آیکونهای برنامه در لانچر) دارند؟
هر میانبری که برای هدف «اشتراکگذاری» منتشر شود، یک میانبر لانچر نیز محسوب میشود و با لمس طولانی مدت آیکون برنامه، در منو نمایش داده میشود. حداکثر تعداد میانبرها در هر فعالیت، برای کل تعداد میانبرهایی که یک برنامه منتشر میکند (مجموعاً میانبرهای اهداف اشتراکگذاری و لانچرهای قدیمی) نیز اعمال میشود.
چه راهنمایی در مورد تعداد میانبرهای اشتراکگذاری که باید منتشر شود، وجود دارد؟
تعداد میانبرهای اشتراکگذاری به همان محدودیت میانبرهای پویا که از طریق getMaxShortcutCountPerActivity(android.content.Context) در دسترس هستند، محدود میشود. میتوان هر تعدادی را تا آن حد منتشر کرد، اما باید در نظر داشت که میانبرهای اشتراکگذاری میتوانند در لانچر برنامه با لمس طولانی و در صفحه اشتراکگذاری قابل مشاهده باشند. اکثر لانچرهای برنامه با لمس طولانی، حداکثر چهار یا پنج میانبر را در حالت عمودی و هشت میانبر را در حالت افقی نمایش میدهند. برای جزئیات بیشتر و راهنمایی در مورد اشتراکگذاری میانبرها، به این بخش سوالات متداول مراجعه کنید.