Izin Bluetooth Flutter di Android 12+ untuk Printer

POS Flutter yang tadinya mencetak lancar di tablet lama tiba-tiba tidak menemukan printer apa pun di tablet baru, melempar SecurityException di dalam stack trace yang tak seorang pun baca, dan toko menyimpulkan aplikasinya rusak. Sembilan dari sepuluh kali penyebabnya adalah pemisahan izin Android 12, dan perbaikannya dua puluh baris manifest ditambah satu permintaan yang waktunya tepat.

Ini seluruh modelnya dalam satu tempat — apa yang berubah, apa yang benar-benar dibutuhkan aplikasi printer, dan kenapa meminta izin lokasi akan memakan waktu Anda di review Play Console.

Apa yang berubah di Android 12

Sebelum API 31, Bluetooth ditangani izin saat pemasangan ditambah izin lokasi, karena hasil pemindaian bisa mengungkap keberadaan pengguna. Mulai API 31, kemampuannya dipecah menjadi izin runtime yang memetakan apa yang benar-benar dilakukan aplikasi.

Perbedaan yang terlihat pengguna sama pentingnya dengan perbedaan teknisnya. Di Android 12 ke atas, dialognya berbunyi Perangkat di sekitar, yang dipahami kasir dalam konteks printer. Alur lama meminta lokasi, dan justru permintaan semacam itulah yang ditolak lalu ditolak permanen.

Manifest yang bekerja di semua versi Android

Anda tetap membutuhkan izin lama untuk perangkat lawas, dan Anda butuh izin itu tidak berlaku di perangkat baru. Untuk itulah maxSdkVersion ada.

<!-- android/app/src/main/AndroidManifest.xml -->

<!-- Legacy permissions: capped at API 30 so Android 12+ ignores them -->
<uses-permission android:name="android.permission.BLUETOOTH"
                 android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
                 android:maxSdkVersion="30" />

<!-- Android 12+ runtime permissions -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
                 android:usesPermissionFlags="neverForLocation" />

<!-- A receipt printer is not a location feature. Cap location at 30 so
     Play Console never asks you to justify a location permission you
     do not use, and users see "Nearby devices" instead. -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
                 android:maxSdkVersion="30" />

Dua baris memikul sebagian besar nilainya. Flag neverForLocation pada BLUETOOTH_SCAN memberi tahu Android bahwa hasil pemindaian Anda tidak dipakai menurunkan lokasi, sehingga permintaan itu tidak masuk ke keranjang lokasi. Membatasi ACCESS_FINE_LOCATION pada API 30 berarti perangkat modern sama sekali tidak pernah melihat permintaan lokasi dari aplikasi pencetakan.

Meminta izin pada momen yang tepat

Permintaan izin adalah masalah pengalaman pengguna yang menyamar sebagai API. Aturan yang berhasil bagi saya: minta hanya sebagai respons langsung terhadap aksi yang tujuannya jelas-jelas printer, dan tangani penolakan permanen sebagai status tersendiri alih-alih mengulang terus.

import 'package:permission_handler/permission_handler.dart';

/// Ask at the moment the cashier taps "connect printer", never at
/// launch. A permission dialog with no visible cause is the single
/// biggest source of permanent denials.
Future<bool> ensureBluetoothPermissions() async {
  final statuses = await [
    Permission.bluetoothConnect,
    Permission.bluetoothScan,
  ].request();

  final granted = statuses.values.every((s) => s.isGranted);
  if (granted) return true;

  // Permanently denied cannot be re-prompted: the only path forward is
  // the system settings screen, so say that plainly instead of looping.
  if (statuses.values.any((s) => s.isPermanentlyDenied)) {
    await openAppSettings();
  }
  return false;
}

Perhatikan apa yang tidak dilakukan kode itu: ia tidak meminta saat aplikasi diluncurkan, tidak meminta sebelum layar pengaturan printer, dan tidak mengulang permintaan setelah penolakan permanen. Begitu sebuah izin ditolak permanen, sistem tidak akan menampilkan dialognya lagi, jadi satu-satunya respons yang jujur adalah menjelaskan dan menawarkan membuka pengaturan.

Empat kegagalan yang terlihat seperti printer rusak

Ketika toko melapor printer tidak ditemukan, inilah penyebabnya berdasarkan urutan saya memeriksanya.

• Aplikasi menarget API 31 ke atas tetapi hanya mendeklarasikan izin lama. Pemindaian tidak mengembalikan apa pun dan penyambungan melempar exception, tanpa dialog terlihat di mana pun.
• Izin sudah ditolak sekali saat onboarding, sebelum pengguna tahu aplikasinya untuk apa. Semua yang terjadi setelah itu terlihat seperti kerusakan perangkat keras.
• Printer belum dipasangkan di tingkat sistem operasi. Perangkat serial klasik harus di-bonding di pengaturan Android; aplikasi hanya bisa menyambung ke yang sudah ada di sana.
• Bluetooth-nya sendiri mati. Periksa status adapter secara eksplisit dan sampaikan itu, jangan melaporkan kegagalan koneksi yang generik.

Keempatnya menghasilkan keluhan yang sama dari toko dan punya perbaikan yang sama sekali berbeda — itulah sebabnya layar pengaturan printer yang melaporkan tiap kondisi secara terpisah menghemat lebih banyak waktu dukungan daripada logika percobaan ulang sebanyak apa pun.

iOS adalah pertanyaan yang sama sekali lain

Di iOS tidak ada pemisahan izin yang setara, karena kemampuan setaranya memang tidak ada. Apple tidak membuka Bluetooth Classic serial port profile untuk aplikasi pihak ketiga; aksesori menjangkaunya lewat sertifikasi MFi dan External Accessory framework, dan sisanya lewat low energy dengan usage description di Info.plist.

Bagi sebuah produk POS, konsekuensi praktisnya adalah keputusan produk, bukan keputusan kode: entah Anda mensyaratkan printer yang menyediakan antarmuka low energy, atau Anda mendukung Android untuk pencetakan dan memperlakukan iOS sebagai klien lihat-saja. Memutuskannya sejak awal menghindarkan Anda menjanjikan fitur yang tidak akan diberikan platformnya.

Checklist sebelum rilis

Sebelum merilis versi apa pun yang menyentuh Bluetooth, saya menjalankan empat pemeriksaan ini di perangkat fisik.

1. Pasang baru di perangkat Android 12 atau lebih baru, tolak izinnya sekali, dan pastikan aplikasi menjelaskan alih-alih crash.
2. Tolak permanen, lalu pastikan aplikasi menawarkan membuka pengaturan alih-alih gagal diam-diam.
3. Jalankan di perangkat Android 11 dan pastikan jalur lama masih bisa pairing dan mencetak.
4. Periksa manifest hasil merge di keluaran build, bukan manifest sumber Anda — sebuah dependensi bisa menambahkan izin yang tidak pernah Anda deklarasikan.

Model izin Android 12 sebenarnya lebih ramah daripada yang digantikannya: aplikasi printer kini bisa meminta persis apa yang dibutuhkan printer, dan pengguna melihat dialog tentang perangkat di sekitar alih-alih tentang lokasi mereka. Mendeklarasikan empat baris yang tepat dan meminta pada momen yang tepat mengubah panggilan dukungan Bluetooth yang paling umum menjadi bukan peristiwa sama sekali.