สิทธิ์การใช้บลูทูธ

หากต้องการใช้ฟีเจอร์บลูทูธในแอป คุณต้องประกาศสิทธิ์หลายอย่าง นอกจากนี้ คุณควรระบุว่าแอปของคุณต้อง รองรับบลูทูธคลาสสิกหรือบลูทูธพลังงานต่ำ (BLE) หรือไม่ หากแอปไม่จำเป็นต้องใช้บลูทูธคลาสสิกหรือ BLE แต่ยังคงได้รับประโยชน์จากเทคโนโลยีเหล่านี้ คุณสามารถตรวจสอบความพร้อมใช้งานที่รันไทม์ได้

ประกาศสิทธิ์

ชุดสิทธิ์ที่คุณประกาศในแอปจะขึ้นอยู่กับ SDK เวอร์ชันเป้าหมายของแอป

กำหนดเป้าหมายเป็น Android 12 ขึ้นไป

หากแอปกำหนดเป้าหมายเป็น Android 12 (API ระดับ 31) ขึ้นไป ให้ประกาศสิทธิ์ต่อไปนี้ในไฟล์ Manifest ของแอป

1. หากแอปค้นหาอุปกรณ์บลูทูธ เช่น อุปกรณ์ต่อพ่วง BLE ให้ประกาศสิทธิ์ BLUETOOTH_SCAN
2. หากแอปทำให้อุปกรณ์ปัจจุบันค้นพบได้สำหรับอุปกรณ์บลูทูธอื่นๆ ให้ประกาศสิทธิ์ BLUETOOTH_ADVERTISE
3. หากแอปสื่อสารกับอุปกรณ์บลูทูธที่จับคู่ไว้แล้ว ให้ประกาศสิทธิ์ BLUETOOTH_CONNECT
4. สำหรับการประกาศสิทธิ์ที่เกี่ยวข้องกับบลูทูธเดิม ให้ตั้งค่า android:maxSdkVersion เป็น 30 ขั้นตอนความเข้ากันได้ของแอปนี้จะช่วยให้ระบบ ให้สิทธิ์ Bluetooth แก่แอปเฉพาะที่จำเป็นเมื่อติดตั้งใน อุปกรณ์ที่ใช้ Android 12 ขึ้นไป
5. หากแอปใช้ผลการสแกนบลูทูธเพื่อหาตำแหน่งจริง ให้ประกาศสิทธิ์ ACCESS_FINE_LOCATION หรือคุณสามารถยืนยันอย่างหนักแน่นว่าแอปของคุณไม่ได้อนุมานandroid:maxSdkVersionตำแหน่งทางกายภาพและตั้งค่าเป็น 30 สำหรับสิทธิ์ ACCESS_FINE_LOCATION

สิทธิ์ BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT และ BLUETOOTH_SCAN เป็นสิทธิ์รันไทม์ ดังนั้น คุณต้องขอความยินยอมจากผู้ใช้อย่างชัดเจนในแอปก่อนจึงจะค้นหาอุปกรณ์บลูทูธ ทำให้อุปกรณ์อื่นค้นพบอุปกรณ์ของคุณ หรือสื่อสารกับอุปกรณ์บลูทูธที่จับคู่ไว้แล้วได้ เมื่อแอปขอสิทธิ์เหล่านี้อย่างน้อย 1 รายการ ระบบจะแจ้งให้ผู้ใช้อนุญาตให้แอปเข้าถึงอุปกรณ์ที่อยู่ใกล้เคียง ดังที่แสดงในรูปที่ 1

ข้อมูลโค้ดต่อไปนี้แสดงวิธีประกาศสิทธิ์ที่เกี่ยวข้องกับบลูทูธ ในแอปหากกำหนดเป้าหมายเป็น Android 12 ขึ้นไป

<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>

ยืนยันอย่างหนักแน่นว่าแอปของคุณไม่ได้อนุมานตำแหน่งจริง

หากแอปไม่ได้ใช้ผลการสแกนบลูทูธเพื่อหาตำแหน่งที่อยู่จริง คุณ สามารถยืนยันอย่างหนักแน่นว่าแอปจะไม่ใช้สิทธิ์บลูทูธ เพื่อหาตำแหน่งที่อยู่จริง โดยทำตามขั้นตอนต่อไปนี้

1. เพิ่มแอตทริบิวต์ android:usesPermissionFlags ลงในBLUETOOTH_SCAN ประกาศการอนุญาต แล้วตั้งค่าของแอตทริบิวต์นี้เป็น neverForLocation

2. หากแอปไม่จำเป็นต้องใช้ตำแหน่งในกรณีอื่นๆ ให้นำ ACCESS_FINE_LOCATION สิทธิ์ออกจากไฟล์ Manifest ของแอป

ข้อมูลโค้ดต่อไปนี้แสดงวิธีอัปเดตไฟล์ Manifest ของแอป

<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>

กำหนดเป้าหมาย Android 11 หรือต่ำกว่า

หากแอปกำหนดเป้าหมายเป็น Android 11 (API ระดับ 30) หรือต่ำกว่า ให้ประกาศสิทธิ์ต่อไปนี้ในไฟล์ Manifest ของแอป

• BLUETOOTH จำเป็นต้องใช้ ในการสื่อสารผ่านบลูทูธคลาสสิกหรือ BLE เช่น การขอ การเชื่อมต่อ การยอมรับการเชื่อมต่อ และการโอนข้อมูล
• ACCESS_FINE_LOCATION เป็นสิ่งจำเป็นเนื่องจากใน Android 11 และเวอร์ชันก่อนหน้า การสแกนบลูทูธ อาจใช้เพื่อรวบรวมข้อมูลเกี่ยวกับตำแหน่งของผู้ใช้ ได้

เนื่องจากสิทธิ์เข้าถึงตำแหน่งเป็นสิทธิ์รันไทม์ คุณจึงต้องขอสิทธิ์เหล่านี้ในรันไทม์ พร้อมทั้งประกาศสิทธิ์ในไฟล์ Manifest

ค้นหาอุปกรณ์บลูทูธในพื้นที่

หากต้องการให้แอปเริ่มการค้นหาอุปกรณ์หรือจัดการการตั้งค่าบลูทูธ คุณต้องประกาศสิทธิ์ BLUETOOTH_ADMIN แอปส่วนใหญ่ต้องการสิทธิ์นี้เพียงเพื่อความสามารถในการค้นหา อุปกรณ์บลูทูธในพื้นที่ อย่าใช้ความสามารถอื่นๆ ที่ได้รับจากสิทธิ์นี้ เว้นแต่แอปจะเป็น "ตัวจัดการพลังงาน" ที่แก้ไขการตั้งค่าบลูทูธ เมื่อผู้ใช้ขอ ประกาศสิทธิ์ในไฟล์ Manifest ของแอป เช่น

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

หากแอปของคุณรองรับบริการและสามารถทำงานบน Android 10 (API ระดับ 29) หรือ Android 11 คุณต้องประกาศสิทธิ์ ACCESS_BACKGROUND_LOCATION เพื่อค้นหาอุปกรณ์บลูทูธด้วย ดูข้อมูลเพิ่มเติมเกี่ยวกับข้อกำหนดนี้ได้ที่หัวข้อเข้าถึงตำแหน่งในเบื้องหลัง

ข้อมูลโค้ดต่อไปนี้แสดงวิธีประกาศ ACCESS_BACKGROUND_LOCATION permission:

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับการประกาศสิทธิ์ของแอปได้ที่<uses-permission> ข้อมูลอ้างอิง

ระบุการใช้ฟีเจอร์บลูทูธ

หากบลูทูธเป็นส่วนสำคัญของแอป คุณสามารถเพิ่มแฟล็กไปยังไฟล์ Manifest เพื่อระบุข้อกำหนดนี้ได้ องค์ประกอบ <uses-feature> ช่วยให้คุณระบุประเภทฮาร์ดแวร์ที่แอปใช้และระบุว่าจำเป็นหรือไม่

ตัวอย่างนี้แสดงวิธีระบุว่าแอปของคุณต้องใช้บลูทูธคลาสสิก

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

หากแอปของคุณใช้บลูทูธพลังงานต่ำ คุณจะใช้สิ่งต่อไปนี้ได้

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

หากคุณระบุว่าแอปต้องใช้ฟีเจอร์ดังกล่าว Google Play Store จะซ่อนแอปของคุณจากผู้ใช้ในอุปกรณ์ที่ไม่มีฟีเจอร์เหล่านั้น ด้วยเหตุนี้ คุณ จึงควรตั้งค่าแอตทริบิวต์ที่จำเป็นเป็น true ก็ต่อเมื่อแอปทำงานไม่ได้หากไม่มี ฟีเจอร์ดังกล่าว

ตรวจสอบความพร้อมใช้งานของฟีเจอร์ที่รันไทม์

หากต้องการให้แอปพร้อมใช้งานในอุปกรณ์ที่ไม่รองรับบลูทูธคลาสสิกหรือ BLE คุณควรใส่องค์ประกอบ <uses-feature> ไว้ใน ไฟล์ Manifest ของแอป แต่ตั้งค่า required="false" จากนั้นในขณะรันไทม์ คุณจะกำหนดความพร้อมใช้งานของฟีเจอร์ได้โดยใช้ 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);