Memungkinkan Aplikasi Lain Memulai Aktivitas Anda

Dua pelajaran sebelumnya memfokuskan pada satu sisi cerita: memulai aktivitas aplikasi lain dari aplikasi Anda. Namun jika aplikasi Anda bisa melakukan suatu aksi yang mungkin berguna bagi aplikasi lain, aplikasi Anda harus disiapkan untuk merespons permintaan aksi dari aplikasi lain. Misalnya, jika Anda membangun sebuah aplikasi sosial yang bisa berbagi pesan atau foto dengan teman pengguna, Anda perlu mendukung maksud ACTION_SEND agar pengguna bisa memulai aksi “berbagi” dari aplikasi lain dan membuka aplikasi Anda untuk melakukan aksi itu.

Untuk memungkinkan aplikasi lain memulai aktivitas, Anda perlu menambahkan elemen <intent-filter> dalam file manifes untuk elemen <activity> yang sesuai.

Bila aplikasi Anda telah dipasang pada perangkat, sistem akan mengidentifikasi filter maksud Anda dan menambahkan informasi ke katalog maksud internal yang didukung oleh semua aplikasi yang terinstal. Bila aplikasi memanggil startActivity() atau startActivityForResult(), dengan maksud implisit, sistem akan mencari aktivitas (atau aktivitas-aktivitas) yang bisa merespons maksud itu.

Menambahkan Filter Maksud

Guna mendefinisikan dengan benar maksud yang bisa ditangani aktivitas Anda, setiap maksud yang Anda tambahkan harus sespesifik mungkin dalam hal tipe aksi dan data yang diterima aktivitas itu.

Sistem mungkin mengirim Intent tertentu ke aktivitas jika aktivitas itu memiliki filter maksud yang memenuhi kriteria objek Intent berikut:

Aksi

String yang menyebutkan aksi yang akan dilakukan. Biasanya salah satu nilai yang didefinisikan platform seperti ACTION_SEND atau ACTION_VIEW.

Tetapkan string ini dalam filter maksud Anda dengan elemen <action>. Nilai yang Anda tetapkan dalam elemen ini harus berupa nama string lengkap untuk aksi, bukannya konstanta API (lihat contoh di bawah ini).

Data

Keterangan data yang terkait dengan maksud.

Tetapkan keterangan dalam filter maksud Anda dengan elemen <data>. Dengan menggunakan satu atau beberapa atribut dalam elemen ini, Anda bisa menetapkan tipe MIME saja, awalan URI saja, skema URI saja, atau kombinasinya dan lain-lain yang menunjukkan tipe data yang diterima.

Catatan: Jika Anda tidak perlu mendeklarasikan hal-hal spesifik tentang data Uri (misalnya, bila aktivitas Anda menangani jenis data “ekstra” lain, sebagai ganti URI), Anda harus menetapkan atribut android:mimeType saja untuk mendeklarasikan tipe data yang ditangani aktivitas, misalnya text/plain atau image/jpeg.

Kategori

Menyediakan cara tambahan untuk membentuk karakter aktivitas yang menangani maksud, biasanya terkait dengan isyarat pengguna atau lokasi memulai aktivitas. Ada beberapa kategori yang didukung oleh sistem, namun sebagian besar jarang digunakan. Akan tetapi, semua maksud implisit didefinisikan dengan CATEGORY_DEFAULT secara default.

Tetapkan dalam filter maksud Anda dengan elemen <category>.

Dalam filter maksud, Anda bisa mendeklarasikan kriteria yang diterima aktivitas dengan mendeklarasikan setiap kriteria dengan elemen XML yang sesuai yang tersarang dalam elemen <intent-filter>.

Misalnya, inilah aktivitas dengan filter maksud yang menangani maksud ACTION_SEND bila tipe data berupa teks atau gambar:

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

Setiap maksud yang masuk menetapkan satu aksi dan satu tipe data saja, namun boleh saja mendeklarasikan beberapa instance elemen <action>, <category>, dan <data> di setiap <intent-filter>.

Jika dua pasang aksi dan data tidak mungkin terjadi secara bersamaan dalam perilakunya, Anda harus membuat filter maksud terpisah untuk menetapkan tindakan yang bisa diterima bila dipasangkan dengan suatu tipe data.

Misalnya, anggaplah aktivitas Anda menangani teks maupun gambar untuk maksud ACTION_SEND dan maksud ACTION_SENDTO. Dalam hal ini, Anda harus mendefinisikan dua filter maksud terpisah untuk kedua tindakan karena maksud ACTION_SENDTO harus menggunakan data Uri untuk menetapkan alamat penerima menggunakan skema URI send atau sendto. Misalnya:

<activity android:name="ShareActivity">
    <!-- filter for sending text; accepts SENDTO action with sms URI schemes -->
    <intent-filter>
        <action android:name="android.intent.action.SENDTO"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:scheme="sms" />
        <data android:scheme="smsto" />
    </intent-filter>
    <!-- filter for sending text or images; accepts SEND action and text or image data -->
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="image/*"/>
        <data android:mimeType="text/plain"/>
    </intent-filter>
</activity>

Catatan: Guna menerima maksud implisit, Anda harus menyertakan kategori CATEGORY_DEFAULT dalam filter maksud. MetodestartActivity() danstartActivityForResult() memperlakukan semua maksud seolah-olah mendeklarasikan kategori CATEGORY_DEFAULT. Jika Anda tidak mendeklarasikannya dalam filter maksud, maka tidak ada maksud implisit yang akan dicocokkan ke aktivitas Anda.

Untuk informasi selengkapnya tentang mengirim dan menerima maksud ACTION_SEND yang melakukan perilaku berbagi sosial, lihat pelajaran tentang Menerima Data Sederhana dari Aplikasi Lain.

Menangani Maksud dalam Aktivitas Anda

Untuk memutuskan aksi yang harus diambil dalam aktivitas, Anda bisa membaca Intent yang digunakan untuk memulainya.

Saat aktivitas Anda dimulai, panggil getIntent() untuk mengambil Intent yang memulai aktivitas. Anda bisa melakukannya kapan saja selama daur hidup aktivitas, namun secara umum Anda harus melakukannya selama callback dini, misalnya onCreate() atau onStart().

Misalnya:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    setContentView(R.layout.main);

    // Get the intent that started this activity
    Intent intent = getIntent();
    Uri data = intent.getData();

    // Figure out what to do based on the intent type
    if (intent.getType().indexOf("image/") != -1) {
        // Handle intents with image data ...
    } else if (intent.getType().equals("text/plain")) {
        // Handle intents with text ...
    }
}

Mengembalikan Hasil

Jika ingin mengembalikan hasil ke aktivitas yang memanggil aktivitas Anda, cukup panggil setResult() untuk menetapkan kode hasil dan Intent yang dikembalikan. Bila operasi Anda selesai dan pengguna harus kembali ke aktivitas asal, panggil finish() untuk menutup (dan memusnahkan) aktivitas Anda. Misalnya :

// Create intent to deliver some kind of result data
Intent result = new Intent("com.example.RESULT_ACTION", Uri.parse("content://result_uri"));
setResult(Activity.RESULT_OK, result);
finish();

Anda harus selalu menetapkan kode hasil bersama hasilnya. Umumnya, baik RESULT_OK atau RESULT_CANCELED. Nanti Anda bisa menyediakan data tambahan bersama Intent, sesuai yang diperlukan.

Catatan: Secara default, hasilnya disetel ke RESULT_CANCELED. Jadi, jika pengguna menekan tombol Kembali sebelum menyelesaikan aksi dan sebelum Anda mengatur hasilnya, aktivitas asal akan menerima hasil “dibatalkan”.

Jika Anda hanya perlu mengembalikan integer yang menunjukkan salah satu opsi hasil, Anda bisa menyetel kode hasil ke nilai yang lebih tinggi daripada 0. Jika Anda menggunakan kode hasil untuk menyampaikan integer dan Anda tidak perlu menyertakan Intent, Anda dapat memanggil setResult() dan meneruskan kode hasil saja. Misalnya:

setResult(RESULT_COLOR_RED);
finish();

Dalam hal ini, mungkin hasilnya hanya sedikit, sehingga kode hasil berupa integer yang didefinisikan secara lokal (lebih besar dari 0). Ini akan berhasil bila Anda mengembalikan hasil ke suatu aktivitas dalam aplikasi Anda sendiri, karena aktivitas yang menerima hasil tersebut bisa merujuk konstanta publik untuk menentukan nilai kode hasil.

Catatan: Tidak perlu memeriksa apakah aktivitas Anda dimulai dengan startActivity() atau startActivityForResult(). Cukup panggil setResult() jika maksud yang memulai aktivitas Anda mungkin mengharapkan sebuah hasil. Jika aktivitas yang menjadi asalnya telah memanggil startActivityForResult(), maka sistem akan memberikan hasil yang Anda sediakan ke setResult(); jika tidak, hasil akan diabaikan.