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

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

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

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

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

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

1. หากแอปค้นหาอุปกรณ์บลูทูธ เช่น อุปกรณ์ต่อพ่วง BLE ให้ประกาศสิทธิ์ BLUETOOTH_SCAN
2. หากแอปของคุณทำให้อุปกรณ์ปัจจุบันค้นพบได้โดยอุปกรณ์บลูทูธอื่นๆ ให้ประกาศสิทธิ์ BLUETOOTH_ADVERTISE
3. หากแอปของคุณสื่อสารกับอุปกรณ์บลูทูธที่จับคู่แล้ว ให้ประกาศสิทธิ์ BLUETOOTH_CONNECT
4. สำหรับการประกาศสิทธิ์ที่เกี่ยวข้องกับบลูทูธแบบเดิม ให้ตั้งค่า android:maxSdkVersion เป็น 30 ขั้นตอนความเข้ากันได้ของแอปนี้จะช่วยให้ระบบให้สิทธิ์บลูทูธที่จำเป็นแก่แอปของคุณเท่านั้นเมื่อติดตั้งในอุปกรณ์ที่ใช้ 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

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