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

หากต้องการใช้ฟีเจอร์บลูทูธในแอป คุณต้องประกาศสิทธิ์หลายรายการ นอกจากนี้ คุณควรระบุด้วยว่าแอปต้อง รองรับบลูทูธคลาสสิกหรือบลูทูธพลังงานต่ำ (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 จะซ่อนแอปของคุณจากผู้ใช้ในอุปกรณ์ที่ไม่มีฟีเจอร์ดังกล่าว ด้วยเหตุนี้ คุณจึงควรตั้งค่าแอตทริบิวต์ `required` เป็น 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);