Gunakan target Berbagi Langsung untuk mempermudah dan mempercepat pengguna aplikasi lain untuk membagikan URL, gambar, atau jenis data lainnya ke aplikasi Anda. Direct Share berfungsi dengan menampilkan kontak dari aplikasi pesan dan sosial langsung di Android Sharesheet, tanpa mengharuskan pengguna memilih aplikasi lalu menelusuri kontak tersebut.
ShortcutManagerCompat
adalah AndroidX API yang menyediakan Sharing Shortcut, dan yang kompatibel
mundur dengan ChooserTargetService
API yang tidak digunakan lagi. Ini adalah cara yang direkomendasikan untuk memublikasikan Sharing Shortcut dan ChooserTargets
. Untuk mengetahui petunjuknya,
lihat Menggunakan AndroidX untuk menyediakan Sharing Shortcut danChooserTargets
di halaman ini.
Memublikasikan target Direct Share
Baris Sharesheet Direct Share hanya menampilkan pintasan dinamis yang disediakan oleh Sharing Shortcuts API. Selesaikan langkah-langkah berikut untuk memublikasikan target Direct Share.
Di file resource XML aplikasi Anda, deklarasikan elemen
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>
Saat aplikasi Anda melakukan inisialisasi, gunakan
setDynamicShortcuts
untuk mengurutkan pintasan dinamis berdasarkan tingkat kepentingan.Indeks yang lebih rendah menunjukkan kepentingan yang lebih besar. Jika Anda membuat aplikasi komunikasi, percakapan tersebut dapat berupa percakapan teratas yang diurutkan menurut keterkinian saat muncul di aplikasi Anda. Jangan publikasikan pintasan yang sudah tidak berlaku; percakapan tanpa aktivitas pengguna dalam 30 hari terakhir akan dianggap tidak berlaku.
Kotlin
ShortcutManagerCompat.setDynamicShortcuts(myContext, listOf(shortcut1, shortcut2, ..))
Java
List<ShortcutInfoCompat> shortcuts = new ArrayList<>(); shortcuts.add(shortcut1); shortcuts.add(shortcut2); ... ShortcutManagerCompat.setDynamicShortcuts(myContext, shortcuts);
Jika Anda mengembangkan aplikasi komunikasi, segera laporkan penggunaan pintasan melalui
pushDynamicShortcut
setiap kali pengguna menerima atau mengirim pesan ke kontak. Lihat Melaporkan penggunaan pintasan untuk aplikasi komunikasi di halaman ini untuk mengetahui informasi selengkapnya. Misalnya, laporkan penggunaan untuk pesan yang dikirim oleh pengguna dengan menentukan binding kemampuan di pintasan melaluiShortcutInfoCompat.Builder#addCapabilityBinding
dengan kemampuanactions.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);
Jika pengguna menghapus kontak, gunakan
removeLongLivedShortcut
. Ini adalah cara yang direkomendasikan untuk menghapus pintasan, terlepas dari apakah pintasan tersebut di-cache oleh layanan sistem atau tidak. Cuplikan kode berikut menunjukkan contoh cara melakukannya.Kotlin
val deleteShortcutId = "..." ShortcutManagerCompat.removeLongLivedShortcuts(myContext, listOf(deleteShortcutId))
Java
String deleteShortcutId = "..."; ShortcutManagerCompat.removeLongLivedShortcuts( myContext, Arrays.asList(deleteShortcutId));
Meningkatkan peringkat target Berbagi Langsung
Android ShareSheet menunjukkan jumlah pasti target Direct Share. Saran ini diurutkan berdasarkan peringkat. Anda dapat meningkatkan peringkat pintasan dengan melakukan hal berikut:
- Pastikan semua
shortcutIds
unik dan tidak pernah digunakan kembali untuk target yang berbeda. - Pastikan pintasan berumur panjang dengan memanggil
setLongLived(true)
. - Untuk pintasan terkait percakapan, laporkan penggunaan pintasan
untuk pesan keluar dan masuk dengan memublikasikan ulang pintasan terkait
melalui
ShortcutManagerCompat.pushDynamicShortcut
. Lihat Melaporkan penggunaan pintasan untuk aplikasi komunikasi di halaman ini untuk mengetahui detailnya. - Hindari memberikan target Direct Share yang tidak relevan atau sudah tidak berlaku—misalnya, kontak yang belum dikirim oleh pengguna dalam 30 hari terakhir.
- Untuk aplikasi SMS, hindari menyediakan pintasan untuk kode singkat atau percakapan yang teridentifikasi sebagai berpotensi spam. Pengguna sangat tidak mungkin berbagi dengan percakapan tersebut.
- Panggil
setCategories()
untuk mengaitkan pintasan dengan atributmimeType
yang sesuai. Misalnya, untuk aplikasi SMS, jika kontak tidak mengaktifkan RCS atau MMS, Anda tidak akan mengaitkan pintasan terkait dengan jenis MIME non-teks sepertiimage/*
danvideo/*
. - Untuk percakapan tertentu, setelah pintasan dinamis didorong dan penggunaannya dilaporkan, jangan mengubah ID pintasan. Hal ini memastikan retensi data penggunaan untuk peringkat.
Jika pengguna mengetuk target Berbagi Langsung, aplikasi Anda harus mengarahkan mereka ke UI tempat mereka dapat melakukan tindakan langsung pada subjek target. Jangan tampilkan UI disambiguasi kepada pengguna, dan jangan tempatkan di UI yang tidak terkait dengan target yang diketuk. Misalnya, di aplikasi pesan, mengetuk target Direct Share akan mengarahkan pengguna ke tampilan percakapan dengan orang yang mereka pilih. Keyboard terlihat dan pesan akan diisi otomatis dengan data yang dibagikan.
Sharing Shortcuts API
Mulai Android 10 (level API 29),
ShortcutInfo.Builder
menambahkan metode dan peningkatan
yang memberikan info tambahan tentang target berbagi:
setCategories()
- Mulai Android 10, kategori juga digunakan untuk memfilter pintasan yang dapat menangani tindakan atau intent berbagi. Lihat Mendeklarasikan target berbagi untuk mengetahui detailnya. Kolom ini wajib ada untuk pintasan yang dimaksudkan untuk digunakan sebagai target berbagi.
setLongLived()
Menentukan apakah pintasan valid atau tidak setelah pintasan tersebut batal dipublikasikan atau dibuat tidak terlihat oleh aplikasi (sebagai pintasan dinamis atau pintasan yang dipasangi pin). Jika pintasan sudah lama, pintasan tersebut dapat di-cache oleh berbagai layanan sistem, bahkan setelah tidak dipublikasikan sebagai pintasan dinamis.
Membuat pintasan bertahan lama dapat meningkatkan peringkatnya. Lihat Mendapatkan peringkat terbaik untuk mengetahui detailnya.
setShortLabel()
,setLongLabel()
Saat memublikasikan pintasan ke individu tertentu, sertakan nama lengkap mereka di
setLongLabel()
dan nama pendek apa pun, seperti nama panggilan atau nama depan, disetShortLabel()
.
Lihat contoh memublikasikan Pintasan Berbagi di GitHub.
Menyediakan gambar pintasan
Untuk membuat Pintasan Berbagi, Anda perlu menambahkan gambar melalui setIcon()
.
Sharing Shortcut dapat muncul di seluruh platform sistem dan mungkin dibentuk ulang.
Selain itu, beberapa perangkat yang menjalankan Android versi 7, 8, atau 9 (API level 25,
26, 27, dan 28) mungkin menampilkan ikon khusus bitmap tanpa latar belakang, yang
secara dramatis mengurangi kontras. Untuk memastikan pintasan Anda terlihat sebagaimana mestinya,
sediakan bitmap adaptif menggunakan IconCompat.createWithAdaptiveBitmap()
.
Pastikan bitmap adaptif mengikuti pedoman dan dimensi yang ditetapkan untuk ikon adaptif. Cara paling umum untuk melakukannya adalah dengan menskalakan bitmap persegi yang dimaksudkan menjadi 72x72 dp dan memusatkannya dalam kanvas transparan 108x108 dp. Jika ikon Anda menyertakan area transparan, Anda harus menyertakan warna latar belakang; jika tidak, area transparan akan tampak berwarna hitam.
Jangan berikan gambar yang diberi mask sesuai dengan bentuk tertentu. Misalnya, sebelum Android 10 (API level 29), biasanya avatar pengguna disediakan untuk ChooserTarget
Direct Share yang disamarkan ke sebuah lingkaran. Android Sharesheet dan permukaan
sistem lainnya di Android 10 kini menyediakan gambar pintasan sebagai bentuk dan tema.
Metode pilihan untuk menyediakan Sharing Shortcut, melalui ShortcutManagerCompat
, secara otomatis membentuk objek ChooserTarget
Direct Share backcompat menjadi lingkaran untuk Anda.
Mendeklarasikan target berbagi
Target berbagi harus dideklarasikan dalam file resource aplikasi, sama seperti definisi pintasan statis. Tambahkan definisi
target berbagi di dalam elemen root <shortcuts>
dalam file resource,
beserta definisi pintasan statis lainnya. Setiap elemen <share-targets>
berisi informasi tentang jenis data yang dibagikan, kategori yang cocok, dan
class target yang akan menangani intent berbagi. Kode XML-nya akan terlihat
seperti ini:
<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>
Elemen data dalam target berbagi mirip dengan spesifikasi data dalam filter intent. Setiap target berbagi dapat memiliki beberapa kategori, yang hanya digunakan untuk mencocokkan pintasan aplikasi yang dipublikasikan dengan definisi target berbaginya. Kategori dapat memiliki nilai arbitrer yang ditentukan oleh aplikasi.
Jika pengguna memilih Sharing Shortcut di Android ShareSheet yang cocok dengan contoh target berbagi di atas, aplikasi akan mendapatkan intent berbagi berikut:
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>
Jika pengguna membuka target berbagi dari pintasan peluncur, aplikasi akan mendapatkan intent yang telah dibuat saat menambahkan pintasan berbagi ke ShortcutManagerCompat.
Karena intent berbeda, Intent.EXTRA_SHORTCUT_ID
tidak akan tersedia,
dan Anda harus meneruskan ID secara manual jika memerlukannya.
Melaporkan penggunaan pintasan untuk aplikasi komunikasi
Jika mengembangkan aplikasi komunikasi, Anda dapat meningkatkan peringkat di Android Sharesheet dengan melaporkan penggunaan untuk pesan keluar dan masuk.
Untuk melakukannya, publikasikan ulang pintasan percakapan yang mewakili kontak melalui
ShortcutManagerCompat.pushDynamicShortcut
.
Penggunaan pintasan dan binding kemampuan kompatibel dengan versi lama untuk Android 5.0 (API 21).
Melaporkan penggunaan pintasan untuk pesan keluar
Penggunaan pelaporan untuk pesan yang dikirim oleh pengguna secara fungsional mirip dengan mengklik tombol "kirim" setelah membuat pesan.
Untuk memicu pelaporan penggunaan, tentukan binding kemampuan di pintasan
melalui ShortcutInfoCompat.Builder#addCapabilityBinding
dengan kemampuan 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);
Jika pesan keluar ditujukan untuk chat grup, Anda juga harus menambahkan parameter value Audience
karena jenis recipient
dikaitkan dengan kemampuan.
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);
Melaporkan penggunaan pintasan untuk pesan masuk
Untuk memicu pelaporan penggunaan saat pengguna menerima pesan seperti SMS,
pesan chat, email, atau notifikasi, Anda juga harus menentukan binding
kemampuan di pintasan melalui
ShortcutInfoCompat.Builder#addCapabilityBinding
dengan
kemampuan 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);
Jika pesan masuk berasal dari chat grup, Anda juga harus menambahkan parameter value Audience
karena jenis sender
dikaitkan dengan kemampuan tersebut.
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);
Menggunakan AndroidX untuk menyediakan Sharing Shortcut dan ChooserTargets
Agar dapat menggunakan library kompatibilitas AndroidX, manifes aplikasi
harus berisi kumpulan filter intent dan layanan target pemilih metadata. Lihat
ChooserTargetService
Direct Share API saat ini.
Layanan ini sudah dideklarasikan dalam library kompatibilitas sehingga pengguna tidak perlu mendeklarasikan layanan dalam manifes aplikasi. Namun, link dari aktivitas berbagi ke layanan harus diperhitungkan sebagai penyedia target pemilih.
Pada contoh berikut, implementasi ChooserTargetService
adalah androidx.core.content.pm.ChooserTargetServiceCompat
, yang telah didefinisikan di 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>
FAQ Sharing Shortcut
Bagaimana data penggunaan pintasan disimpan dan bagaimana data tersebut keluar dari perangkat?
Pintasan disimpan sepenuhnya di perangkat di direktori data sistem dalam partisi disk terenkripsi. Informasi dalam pintasan seperti ikon, intent, dan nama orang serta resource hanya dapat diakses oleh layanan sistem dan aplikasi yang sama yang memublikasikan pintasan.
Apa itu histori Berbagi Langsung?
Kami memperkenalkan Direct Share di Android 6.0 (API level 23) agar aplikasi dapat
menyediakan objek ChooserTarget
melalui ChooserTargetService
. Hasil diambil secara reaktif sesuai permintaan, sehingga menyebabkan waktu pemuatan target yang lambat.
Di Android 10 (API level 29), kami mengganti ChooserTargetService
Direct
Share API dengan Sharing Shortcuts API baru. Sharing Shortcuts API memungkinkan aplikasi memublikasikan target Direct Share
di awal, bukan mengambil hasil secara reaktif sesuai permintaan. Hal ini mempercepat proses pengambilan target Direct Share
saat menyiapkan ShareSheet. Mekanisme ChooserTargetService
Direct Share
akan terus berfungsi, tetapi sistem memberi peringkat target yang disediakan
dengan cara ini lebih rendah daripada target apa pun yang menggunakan Sharing Shortcuts API.
Android 11 (API level 30) menghentikan penggunaan layanan ChooserTargetService
, dan
Berbagi Shortcuts API adalah satu-satunya cara untuk menyediakan target Direct Share.
Apa perbedaan antara pintasan yang dipublikasikan untuk target berbagi dengan pintasan peluncur (penggunaan standar pintasan saat menekan lama ikon aplikasi di peluncur)?
Semua pintasan yang dipublikasikan untuk keperluan "target berbagi" juga merupakan pintasan peluncur, dan akan ditampilkan pada menu ketika ikon aplikasi ditekan lama. Batas jumlah pintasan maksimum per aktivitas juga berlaku untuk jumlah total pintasan yang dipublikasikan aplikasi (gabungan pintasan peluncur lama dan target berbagi).
Apa panduan tentang jumlah pintasan berbagi yang harus dipublikasikan.
Jumlah pintasan berbagi dibatasi pada batas pintasan dinamis
yang sama dengan yang tersedia melalui
getMaxShortcutCountPerActivity(android.content.Context)
. Pengguna dapat memublikasikan
angka apa pun hingga batas tersebut, tetapi harus ingat bahwa pintasan berbagi dapat terlihat
di peluncur aplikasi dengan menekan lama dan di sheet berbagi. Sebagian besar peluncur aplikasi saat
tekan lama menampilkan maksimal empat atau lima pintasan dalam mode potret, dan
delapan dalam mode lanskap. Lihat
FAQ
ini untuk mengetahui detail dan panduan selengkapnya tentang cara membagikan pintasan.