Izin Bluetooth

Untuk menggunakan fitur Bluetooth di aplikasi, Anda harus mendeklarasikan beberapa izin. Anda juga harus menentukan apakah aplikasi Anda memerlukan dukungan untuk Bluetooth klasik atau Bluetooth Hemat Energi (BLE). Jika aplikasi Anda tidak memerlukan Bluetooth klasik atau BLE, tetapi masih dapat memanfaatkan teknologi ini, Anda dapat memeriksa ketersediaan saat runtime.

Mendeklarasikan izin

Kumpulan izin yang Anda deklarasikan di aplikasi Anda bergantung pada versi SDK target aplikasi Anda.

Menargetkan Android 12 atau yang lebih baru

Jika aplikasi Anda menargetkan Android 12 (level API 31) atau yang lebih tinggi, deklarasikan izin berikut dalam file manifes aplikasi Anda:

1. Jika aplikasi Anda mencari perangkat Bluetooth, seperti periferal BLE, nyatakan izin BLUETOOTH_SCAN.
2. Jika aplikasi Anda membuat perangkat saat ini dapat ditemukan oleh perangkat Bluetooth lain, deklarasikan izin BLUETOOTH_ADVERTISE.
3. Jika aplikasi Anda berkomunikasi dengan perangkat Bluetooth yang sudah disambungkan, deklarasikan izin BLUETOOTH_CONNECT.
4. Untuk deklarasi izin terkait Bluetooth lama Anda, tetapkan android:maxSdkVersion ke 30. Langkah kompatibilitas aplikasi ini membantu sistem hanya memberikan izin Bluetooth ke aplikasi Anda yang diperlukan saat diinstal di perangkat yang menjalankan Android 12 atau yang lebih tinggi.
5. Jika aplikasi Anda menggunakan hasil pemindaian Bluetooth untuk mendapatkan lokasi fisik, deklarasikan izin ACCESS_FINE_LOCATION. Jika tidak, Anda dapat menegaskan dengan jelas bahwa aplikasi Anda tidak memperoleh lokasi fisik dan menetapkan android:maxSdkVersion ke 30 untuk izin ACCESS_FINE_LOCATION.

Izin BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT, dan BLUETOOTH_SCAN merupakan izin waktu proses. Oleh karena itu, Anda harus secara eksplisit meminta persetujuan pengguna di aplikasi sebelum dapat mencari perangkat Bluetooth, membuat perangkat dapat ditemukan di perangkat lain, atau berkomunikasi dengan perangkat Bluetooth yang sudah disambungkan. Saat aplikasi Anda meminta setidaknya salah satu izin ini, sistem akan meminta pengguna untuk mengizinkan aplikasi Anda mengakses Perangkat di sekitar, seperti yang ditunjukkan pada gambar 1.

Cuplikan kode berikut menunjukkan cara mendeklarasikan izin terkait Bluetooth di aplikasi Anda jika aplikasi menargetkan Android 12 atau yang lebih tinggi:

<manifest>
    <!-- Request legacy Bluetooth permissions on older devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH"
                     android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
                     android:maxSdkVersion="30" />

    <!-- Needed only if your app looks for Bluetooth devices.
         If your app doesn't use Bluetooth scan results to derive physical
         location information, you can
         <a href="#assert-never-for-location">strongly assert that your app
         doesn't derive physical location</a>. -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

    <!-- Needed only if your app makes the device discoverable to Bluetooth
         devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

    <!-- Needed only if your app communicates with already-paired Bluetooth
         devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

    <!-- Needed only if your app uses Bluetooth scan results to derive
         physical location. -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    ...
</manifest>

Tegaskan dengan jelas bahwa aplikasi Anda tidak memperoleh lokasi fisik

Jika aplikasi Anda tidak menggunakan hasil pemindaian Bluetooth untuk mendapatkan lokasi fisik, Anda dapat membuat pernyataan tegas bahwa aplikasi Anda tidak pernah menggunakan izin Bluetooth untuk mendapatkan lokasi fisik. Caranya, selesaikan langkah-langkah berikut:

1. Tambahkan atribut android:usesPermissionFlags ke deklarasi izin BLUETOOTH_SCAN, lalu tetapkan nilai atribut ke neverForLocation.

2. Jika lokasi tidak diperlukan untuk aplikasi Anda, hapus izin ACCESS_FINE_LOCATION dari manifes aplikasi Anda.

Cuplikan kode berikut menunjukkan cara memperbarui file manifes aplikasi Anda:

<manifest>
    <!-- Include "neverForLocation" only if you can strongly assert that
         your app never derives physical location from Bluetooth scan results. -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
                     android:usesPermissionFlags="neverForLocation" />

    <!-- Set maxSdkVersion to 30 if you can strongly assert that, on
         Android 12 and higher, your app never derives physical location from
         Bluetooth scan results and doesn't need location access for any other
         purpose. -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                     android:maxSdkVersion="30" />
    ...
</manifest>

Menargetkan Android 11 atau yang lebih rendah

Jika aplikasi Anda menargetkan Android 11 (level API 30) atau yang lebih rendah, deklarasikan izin berikut dalam file manifes aplikasi Anda:

• BLUETOOTH diperlukan untuk melakukan komunikasi Bluetooth klasik atau BLE, seperti meminta koneksi, menerima koneksi, dan mentransfer data.
• ACCESS_FINE_LOCATION diperlukan karena, di Android 11 dan yang lebih lama, pemindaian Bluetooth berpotensi digunakan untuk mengumpulkan informasi tentang lokasi pengguna.

Karena izin lokasi adalah izin runtime, Anda harus meminta izin ini saat runtime sekaligus mendeklarasikannya dalam manifes Anda.

Menemukan perangkat Bluetooth lokal

Jika ingin aplikasi Anda memulai penemuan perangkat atau memanipulasi setelan Bluetooth, Anda harus mendeklarasikan izin BLUETOOTH_ADMIN. Sebagian besar aplikasi memerlukan izin ini hanya agar dapat menemukan perangkat Bluetooth lokal. Jangan gunakan kemampuan lain yang diberikan oleh izin ini, kecuali jika aplikasi adalah "pengelola daya" yang mengubah setelan Bluetooth atas permintaan pengguna. Deklarasikan izin di file manifes aplikasi Anda. Contoh:

<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>

Jika aplikasi Anda mendukung layanan dan dapat berjalan di Android 10 (level API 29) atau Android 11, Anda juga harus mendeklarasikan izin ACCESS_BACKGROUND_LOCATION untuk menemukan perangkat Bluetooth. Untuk mengetahui informasi selengkapnya tentang persyaratan ini, lihat Mengakses lokasi di latar belakang.

Cuplikan kode berikut menunjukkan cara mendeklarasikan izin ACCESS_BACKGROUND_LOCATION:

<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>

Lihat referensi <uses-permission> untuk mengetahui informasi selengkapnya tentang mendeklarasikan izin aplikasi.

Menentukan penggunaan fitur Bluetooth

Jika Bluetooth adalah bagian penting dari aplikasi Anda, Anda dapat menambahkan tanda ke file manifes yang menunjukkan persyaratan ini. Elemen <uses-feature> memungkinkan Anda menentukan jenis hardware yang digunakan aplikasi dan apakah hardware tersebut diperlukan atau tidak.

Contoh ini menunjukkan cara menunjukkan bahwa Bluetooth klasik diperlukan untuk aplikasi Anda.

<uses-feature android:name="android.hardware.bluetooth" android:required="true"/>

Jika aplikasi Anda mengandalkan Bluetooth Hemat Energi, Anda dapat menggunakan hal berikut:

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

Jika Anda menyatakan bahwa fitur tersebut diperlukan untuk aplikasi Anda, Google Play Store akan menyembunyikan aplikasi Anda dari pengguna di perangkat yang tidak memiliki fitur tersebut. Oleh karena itu, Anda hanya boleh menyetel atribut wajib ke true jika aplikasi Anda tidak dapat berfungsi tanpa fitur tersebut.

Memeriksa ketersediaan fitur saat runtime

Agar aplikasi Anda tersedia untuk perangkat yang tidak mendukung Bluetooth klasik atau BLE, Anda tetap harus menyertakan elemen <uses-feature> dalam manifes aplikasi, tetapi menetapkan required="false". Kemudian, saat runtime, Anda dapat menentukan ketersediaan fitur menggunakan PackageManager.hasSystemFeature():

// Check to see if the Bluetooth classic feature is available.
val bluetoothAvailable = packageManager.hasSystemFeature(PackageManager.FEATURE_BLUETOOTH)

// Check to see if the BLE feature is available.
val bluetoothLEAvailable = packageManager.hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)

// Use this check to determine whether Bluetooth classic is supported on the device.
// Then you can selectively disable BLE-related features.
boolean bluetoothAvailable = getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH);

// Use this check to determine whether BLE is supported on the device. Then
// you can selectively disable BLE-related features.
boolean bluetoothLEAvailable = getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE);