Pratinjau Developer untuk Android 11 kini tersedia; uji dan sampaikan masukan Anda.

Menerima data sederhana dari aplikasi lain

Selain dapat mengirim data ke aplikasi lain, aplikasi Anda juga dapat menerima data dari aplikasi lain. Pikirkan bagaimana pengguna berinteraksi dengan aplikasi Anda dan jenis data apa yang ingin Anda terima dari aplikasi lain. Misalnya, aplikasi jaringan sosial mungkin tertarik untuk menerima konten teks, seperti URL web yang menarik, dari aplikasi lain.

Pengguna akan sering mengirim data ke aplikasi Anda melalui Android ShareSheet atau intent resolver. Semua data yang diterima memiliki jenis MIME yang ditetapkan oleh aplikasi penyedianya. Aplikasi dapat menerima data yang dikirim oleh aplikasi lain melalui tiga cara:

  • Activity dengan tag intent-filter yang cocok dalam manifesnya
  • Satu atau beberapa objek ChooserTarget yang ditampilkan oleh ChooserTargetService
  • Sharing Shortcut yang dipublikasikan oleh aplikasi Anda. Objek ini menggantikan objek ChooserTarget. Sharing Shortcut hanya tersedia jika aplikasi Anda menjalankan Android 10 (API level 29).

Sharing Shortcut dan objek ChooserTarget adalah deep link Direct Share ke Activity tertentu dalam aplikasi Anda. Objek ini sering mewakili orang, dan Android ShareSheet akan menunjukkannya. Contoh, aplikasi pengiriman pesan dapat menyediakan Sharing Shortcut untuk orang yang melakukan deep link langsung ke percakapan dengan orang tersebut.

Mendukung jenis MIME

Aplikasi Anda harus bisa menerima sebanyak mungkin jenis MIME. Misalnya, aplikasi pengiriman pesan yang digunakan untuk mengirim teks, gambar, dan video harus dapat menerima text/*, image/*, dan video/*. Berikut ini beberapa jenis MIME yang umum saat mengirim data sederhana di Android.

  • text/*, pengirim akan sering mengirim text/plain, text/rtf, text/html, text/json
  • image/*, pengirim akan sering mengirim image/jpg, image/png, image/gif
  • video/*, pengirim akan sering mengirim video/mp4, video/3gp
  • penerima harus mendaftar agar dapat menerima ekstensi file yang didukung, pengirim akan sering mengirim application/pdf

Silakan lihat registry resmi IANA untuk jenis media MIME. Anda dapat menerima MIME jenis */*, tetapi hal ini sangat tidak dianjurkan kecuali jika Anda dapat menangani setiap jenis konten yang masuk.

Membuat target berbagi yang baik

Saat pengguna mengetuk target berbagi yang terkait dengan aktivitas tertentu, mereka harus dapat mengonfirmasi dan mengedit konten yang dibagikan itu sebelum menggunakannya. Persyaratan ini sangat penting untuk data teks.

Mengetuk sembarang target Direct Share harus mengarahkan pengguna ke antarmuka di mana tindakan dapat dijalankan langsung pada subjek target. Hindari menunjukkan disambiguitas kepada pengguna atau menempatkan mereka pada antarmuka yang tidak terkait dengan target yang diketuk. Secara khusus, jangan arahkan pengguna ke antarmuka disambiguitas kontak yang mengharuskan mereka mengonfirmasi atau memilih kembali kontak yang akan diajak berbagi, karena mereka sudah melakukan itu dengan mengetuk target di Android ShareSheet. Misalnya, dalam aplikasi pengiriman pesan, mengetuk target Direct Share harus mengarahkan pengguna ke tampilan percakapan dengan orang yang dipilihnya. Keyboard harus terlihat dan pesan harus terisi sebelumnya dengan data yang dibagikan.

Menerima data dengan aktivitas

Perbarui manifes Anda

Filter intent memberi tahu sistem intent apa saja yang dapat diterima oleh sebuah komponen aplikasi. Seperti yang Anda lakukan ketika membuat intent dengan tindakan ACTION_SEND dalam pelajaran Mengirim Data Sederhana ke Aplikasi Lain, Anda membuat filter intent agar dapat menerima intent dengan tindakan ini. Anda menetapkan filter intent dalam manifes menggunakan elemen <intent-filter>. Misalnya, jika aplikasi Anda menangani penerimaan konten teks, satu gambar dengan jenis apa pun, atau banyak gambar dengan jenis apa pun, manifes Anda akan terlihat seperti ini:

    <activity android:name=".ui.MyActivity" >
        <intent-filter>
            <action android:name="android.intent.action.SEND" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:mimeType="image/*" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.SEND" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:mimeType="text/plain" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.SEND_MULTIPLE" />
            <category android:name="android.intent.category.DEFAULT" />
            <data android:mimeType="image/*" />
        </intent-filter>
    </activity>
    

Saat aplikasi lain mencoba membagikan salah satu hal ini dengan membuat intent dan meneruskannya ke startActivity(), aplikasi Anda akan dicantumkan sebagai opsi di Android ShareSheet atau intent resolver. Jika pengguna memilih aplikasi Anda, aktivitas yang terkait (dalam contoh di atas, .ui.MyActivity) akan dimulai. Selanjutnya terserah Anda untuk menangani konten tersebut dengan sesuai dalam kode dan UI.

Catatan: Untuk informasi selengkapnya tentang filter intent dan intent resolver, silakan baca Intent dan Filter Intent

Menangani konten yang masuk

Untuk menangani konten yang dikirim oleh Intent, panggil getIntent() untuk mendapatkan objek Intent. Setelah mendapatkan objek ini, Anda dapat memeriksa isinya untuk menentukan langkah selanjutnya. Selalu ingat bahwa jika aktivitas ini dapat dimulai dari bagian lain pada sistem, misalnya peluncur, maka Anda perlu mempertimbangkan hal ini saat memeriksa intent tersebut.

Harap berhati-hati saat memeriksa data yang masuk; Anda tidak mengetahui data apa yang dikirim oleh aplikasi lain. Misalnya, jenis MIME yang ditetapkan mungkin salah, atau gambar yang dikirim mungkin sangat besar. Juga ingat untuk memproses data biner dalam thread tersendiri, bukan di thread utama ("UI").

Kotlin

    override fun onCreate(savedInstanceState: Bundle?) {
        ...
        when {
            intent?.action == Intent.ACTION_SEND -> {
                if ("text/plain" == intent.type) {
                    handleSendText(intent) // Handle text being sent
                } else if (intent.type?.startsWith("image/") == true) {
                    handleSendImage(intent) // Handle single image being sent
                }
            }
            intent?.action == Intent.ACTION_SEND_MULTIPLE
                    && intent.type?.startsWith("image/") == true -> {
                    handleSendMultipleImages(intent) // Handle multiple images being sent
            }
            else -> {
                // Handle other intents, such as being started from the home screen
            }
        }
        ...
    }

    private fun handleSendText(intent: Intent) {
        intent.getStringExtra(Intent.EXTRA_TEXT)?.let {
            // Update UI to reflect text being shared
        }
    }

    private fun handleSendImage(intent: Intent) {
        (intent.getParcelableExtra<Parcelable>(Intent.EXTRA_STREAM) as? Uri)?.let {
            // Update UI to reflect image being shared
        }
    }

    private fun handleSendMultipleImages(intent: Intent) {
        intent.getParcelableArrayListExtra<Parcelable>(Intent.EXTRA_STREAM)?.let {
            // Update UI to reflect multiple images being shared
        }
    }
    

Java

    void onCreate (Bundle savedInstanceState) {
        ...
        // Get intent, action and MIME type
        Intent intent = getIntent();
        String action = intent.getAction();
        String type = intent.getType();

        if (Intent.ACTION_SEND.equals(action) && type != null) {
            if ("text/plain".equals(type)) {
                handleSendText(intent); // Handle text being sent
            } else if (type.startsWith("image/")) {
                handleSendImage(intent); // Handle single image being sent
            }
        } else if (Intent.ACTION_SEND_MULTIPLE.equals(action) && type != null) {
            if (type.startsWith("image/")) {
                handleSendMultipleImages(intent); // Handle multiple images being sent
            }
        } else {
            // Handle other intents, such as being started from the home screen
        }
        ...
    }

    void handleSendText(Intent intent) {
        String sharedText = intent.getStringExtra(Intent.EXTRA_TEXT);
        if (sharedText != null) {
            // Update UI to reflect text being shared
        }
    }

    void handleSendImage(Intent intent) {
        Uri imageUri = (Uri) intent.getParcelableExtra(Intent.EXTRA_STREAM);
        if (imageUri != null) {
            // Update UI to reflect image being shared
        }
    }

    void handleSendMultipleImages(Intent intent) {
        ArrayList<Uri> imageUris = intent.getParcelableArrayListExtra(Intent.EXTRA_STREAM);
        if (imageUris != null) {
            // Update UI to reflect multiple images being shared
        }
    }
    

Mengupdate UI setelah menerima data bisa jadi mudah, seperti mengisikan EditText, atau bisa pula rumit, seperti menerapkan filter foto yang menarik ke sebuah gambar. Aplikasi Anda dapat memilih tindakan apa yang akan dilakukan selanjutnya.

Memastikan pengguna mengenali aplikasi Anda

Aplikasi Anda direpresentasikan oleh ikon dan label di Android ShareSheet dan intent resolver. Keduanya ditentukan dalam manifes. Anda dapat menetapkan label aktivitas atau filter intent untuk memberikan lebih banyak konteks.

Mulai Android 10 (API level 29), Android ShareSheet hanya akan menggunakan ikon yang ditetapkan dengan tag application dalam manifes. Ikon yang ditetapkan dengan tag intent-filter dan activity akan diabaikan.

Catatan: Target berbagi terbaik tidak memerlukan label dan ikon pada aktivitas atau filter intent terkaitnya. Nama dan ikon aplikasi penerima saja sudah cukup bagi pengguna untuk memahami apa yang terjadi ketika berbagi.

Menyediakan target Direct Share

Direct Share diperkenalkan pada Android 6.0 (API level 23) yang memungkinkan aplikasi untuk menyediakan objek ChooserTarget melalui ChooserTargetService. Hasil diambil secara reaktif berdasarkan permintaan, yang berakibat pada waktu pemuatan target yang lambat.

Pada Android 10 (API level 29), ChooserTargetService Direct Share API diganti dengan Sharing Shortcuts API. Alih-alih mengambil hasil secara reaktif berdasarkan permintaan, Sharing Shortcuts API memungkinkan aplikasi memublikasikan target berbagi langsung di awal. Mekanisme ChooserTargetService Direct Share akan tetap berfungsi, tetapi target yang disediakan dengan cara ini akan menempati peringkat lebih rendah daripada target apa pun yang menggunakan Sharing Shortcuts API.

ShortcutManagerCompat adalah AndroidX API yang menyediakan Sharing Shortcut yang kompatibel dengan ChooserTargetService DirectShare API versi lama. Cara ini lebih disukai untuk memublikasikan Sharing Shortcut dan ChooserTargets. Lihat petunjuk di bawah.

Memublikasikan target Direct Share

Anda hanya dapat menggunakan pintasan dinamis untuk memublikasikan target Direct Share. Ikuti langkah berikut untuk memublikasikan target berbagi langsung menggunakan API baru:

  1. Nyatakan elemen target berbagi dalam file resource XML aplikasi. Untuk selengkapnya, lihat Mendeklarasikan target berbagi di bawah ini.
  2. Publikasikan pintasan dinamis beserta kategori pencocokan ke target berbagi yang dideklarasikan. Pintasan dapat ditambahkan, diakses, diperbarui, dan dihapus menggunakan ShortcutManager atau ShortcutManagerCompat di AndroidX. Penggunaan library kompatibilitas di AndroidX merupakan metode yang lebih baik karena menyediakan kompatibilitas dengan versi Android lama.

Sharing Shortcuts API

ShortcutInfo.Builder menyertakan metode baru dan disempurnakan yang memberikan info tambahan tentang target berbagi:

setCategories()
Ini bukan metode baru, tetapi sekarang kategori juga digunakan untuk memfilter pintasan yang dapat menangani tindakan atau intent berbagi. Lihat Mendeklarasikan target berbagi di bawah untuk penjelasan selengkapnya. Kolom ini wajib ada untuk pintasan yang ingin 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 sematan). Pintasan yang sudah berumur panjang dapat dimasukkan ke dalam cache oleh berbagai layanan sistem, bahkan setelah pintasan tersebut tidak dipublikasikan sebagai pintasan dinamis.

Membuat pintasan berumur panjang dapat meningkatkan peringkatnya. Lihat Mendapatkan peringkat terbaik untuk penjelasan lebih lanjut.

setPerson(), setPersons()

Mengaitkan satu atau beberapa objek Person dengan pintasan. Cara ini dapat digunakan untuk memahami perilaku pengguna di berbagai aplikasi dengan lebih baik, dan membantu layanan prediksi potensial pada framework untuk memberikan saran yang lebih baik di ShareSheet. Penambahan info Person ke pintasan bersifat opsional, tetapi sangat direkomendasikan jika target berbagi dapat dikaitkan dengan orang. Perhatikan bahwa beberapa target berbagi, seperti cloud, tidak dapat dikaitkan dengan orang.

Menyertakan objek Person yang spesifik dengan ID unik dalam target berbagi dan notifikasi terkait dapat meningkatkan peringkat saran. Lihat Mendapatkan peringkat terbaik untuk penjelasan lebih lanjut.

Untuk aplikasi pesan standar, pintasan terpisah harus dipublikasikan untuk setiap kontak, dan kolom Person harus memuat info kontak. Jika target dapat dikaitkan dengan banyak orang (seperti grup chat), tambahkan beberapa objek Person ke satu target berbagi.

Saat memublikasikan pintasan ke orang tertentu, sertakan nama lengkapnya di setLongLabel() dan nama singkat apa pun, seperti nama panggilan atau nama depan, di setShortLabel()

Untuk contoh pemublikasian Sharing Shortcut, lihat Contoh kode Sharing Shortcut.

Mendapatkan peringkat terbaik

Android ShareSheet menunjukkan jumlah pasti target Direct Share. Saran ini diurutkan berdasarkan peringkat. Anda dapat meningkatkan peringkat pintasan dengan melakukan langkah berikut:

  • Pastikan semua shortcutId unik dan tidak pernah digunakan kembali untuk target berbeda.
  • Pastikan pintasan berumur panjang dengan memanggil setLongLived(true).
  • Berikan peringkat yang dapat digunakan untuk membandingkan pintasan dari aplikasi Anda jika data pelatihan tidak ada. Lihat setRank(). Peringkat yang lebih rendah menunjukkan pintasan yang lebih penting.

Untuk memperbaiki peringkat lebih lanjut, aplikasi sosial sebaiknya melakukan semua saran di atas dan:

Untuk memperbaiki peringkat secara maksimal, aplikasi sosial dapat melakukan semua saran di atas dan:

  • Dalam objek Person yang disediakan, memasukkan URI yang valid ke kontak yang terkait di perangkat. Lihat setUri().

Berikut ini contoh pintasan dengan semua perbaikan peringkat yang potensial.

Kotlin

    val person = Person.Builder()
      ...
      .setName(fullName)
      .setKey(staticPersonIdentifier)
      .setUri("tel:$phoneNumber") // alternatively "mailto:$email" or CONTENT_LOOKUP_URI
      .build()

    val shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticPersonIdentifier)
      ...
      .setShortLabel(firstName)
      .setLongLabel(fullName)
      .setPerson(person)
      .setLongLived(true)
      .setRank(personRank)
      .build()
    

Java

    Person person = Person.Builder()
      ...
      .setName(fullName)
      .setKey(staticPersonIdentifier)
      .setUri("tel:"+phoneNumber) // alternatively "mailto:"+email or CONTENT_LOOKUP_URI
      .build();

    ShortcutInfoCompat shortcutInfo = ShortcutInfoCompat.Builder(myContext, staticPersonIdentifier)
      ...
      .setShortLabel(firstName)
      .setLongLabel(fullName)
      .setPerson(person)
      .setLongLived(true)
      .setRank(personRank)
      .build();
    

Kotlin

    val notif = NotificationCompat.Builder(myContext, channelId)
      ...
      .setShortcutId(staticPersonIdentifier)
      .build()
    

Java

    Notification notif = NotificationCompat.Builder(myContext, channelId)
      ...
      .setShortcutId(staticPersonIdentifier)
      .build();

    

Menyediakan gambar pintasan

Untuk membuat Sharing Shortcut, Anda perlu menambahkan gambar melalui setIcon().

Sharing Shortcut dapat muncul di berbagai bagian sistem dan dapat dibentuk ulang. Untuk memastikan pintasan memiliki tampilan seperti yang diinginkan, sediakan bitmap adaptif melalui IconCompat.createWithAdaptiveBitmap().

Bitmap adaptif harus mengikuti panduan dan dimensi yang sama dengan yang ditetapkan untuk ikon adaptif. Cara paling umum untuk mencapai hal ini adalah dengan menskala bitmap persegi yang dimaksudkan ke 72x72 dp di tengah-tengah kanvas transparan 108x108 dp.

Jangan berikan gambar yang disamarkan ke 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 sekarang menyediakan gambar pintasan sebagai bentuk dan tema. Metode yang lebih disukai untuk menyediakan Sharing Shortcut, melalui ShortcutManagerCompat, akan otomatis membentuk backcompat Direct Share ChooserTarget ke lingkaran.

Mendeklarasikan target berbagi

Target berbagi harus dideklarasikan dalam file resource aplikasi, sama seperti penentuan pintasan statis. Tambahkan penentuan target berbagi di dalam elemen root <shortcuts> dalam file resource, beserta penentuan pintasan statis lainnya. Setiap elemen <share-targets> berisi informasi tentang jenis data yang dibagikan, kategori pencocokan, dan class target yang akan menangani intent berbagi. Kode XML-nya terlihat sebagai berikut:

    <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 digunakan hanya untuk mencocokkan pintasan aplikasi yang dipublikasikan dengan penentuan target berbaginya. Kategori dapat memiliki sembarang nilai yang ditentukan aplikasi.

Jika pengguna memilih Sharing Shortcut di Android ShareSheet yang cocok dengan contoh target berbagi di atas, aplikasi akan mendapatkan intent berbagi sebagai 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 itu adalah intent berbeda, Intent.EXTRA_SHORTCUT_ID tidak akan tersedia, dan Anda harus meneruskan ID secara manual, jika memerlukannya.

Menggunakan AndroidX untuk menyediakan Sharing Shortcut dan ChooserTargets

Agar dapat digunakan dengan library kompatibilitas AndroidX, manifes aplikasi harus memuat set filter intent dan layanan target pemilih metadata. Lihat ChooserTargetService Direct Share API terbaru.

Layanan ini sudah dideklarasikan dalam library kompatibilitas, sehingga pengguna tidak perlu mendeklarasikan layanan tersebut dalam manifes aplikasi. Namun, link dari aktivitas berbagi ke layanan ini harus diperhitungkan sebagai penyedia target pemilih (chooser target provider).

Dalam contoh berikut, implementasi ChooserTargetService adalah androidx.core.content.pm.ChooserTargetServiceCompat, yang sudah ditentukan 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

Apa perbedaan utama antara Sharing Shortcuts API terbaru dengan ChooserTargetService Direct Share API lama?

Sharing Shortcuts API menggunakan model push, bukan model pull seperti yang digunakan pada Direct Share API versi lama. Cara ini mempercepat proses pengambilan target berbagi langsung saat menyiapkan ShareSheet. Dari sudut pandang developer aplikasi, jika API baru digunakan, aplikasi perlu menyediakan daftar target berbagi langsung di awal, dan kemungkinan harus mengupdate daftar pintasan setiap kali keadaan internal aplikasi berubah (misalnya, jika kontak baru ditambahkan ke aplikasi pesan).

Apa yang terjadi jika saya tidak bermigrasi untuk menggunakan Sharing Shortcuts API?

Pada Android 10 (API level 29) dan yang lebih baru, Android ShareSheet akan memberikan prioritas yang lebih tinggi pada target berbagi yang disediakan melalui ShortcutManager menggunakan Sharing Shortcuts API. Akibatnya, target berbagi yang telah Anda publikasikan mungkin akan terkubur oleh target berbagi aplikasi lain dan berpotensi tidak pernah muncul saat berbagi.

Dapatkah saya menggunakan ChooserTargetService dan Sharing Shortcuts DirectShare API pada aplikasi saya untuk mendapatkan kompatibilitas dengan versi lama?

Jangan lakukan itu! Sebagai gantinya, gunakan API support library ShortcutManagerCompat yang disediakan. Menggabungkan kedua set API ini dapat mengakibatkan perilaku yang tidak diinginkan/tidak terduga saat mengambil target berbagi.

Apa perbedaan antara pintasan yang dipublikasikan untuk target berbagi dengan pintasan peluncur (penggunaan standar pintasan saat ikon aplikasi pada peluncur ditekan lama)?

Semua pintasan yang dipublikasikan untuk keperluan "berbagi target" juga merupakan pintasan peluncur, dan akan ditampilkan di 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).