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

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

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

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

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

หมายเหตุ: ใน Android 8.0 (API ระดับ 26) ขึ้นไป เครื่องมือจัดการอุปกรณ์ที่ใช้ร่วมกัน (CDM) มีวิธีการเชื่อมต่อกับอุปกรณ์ที่ใช้ร่วมกันที่มีประสิทธิภาพมากขึ้นเมื่อเทียบกับสิทธิ์ที่อธิบายในส่วนนี้ ระบบ CDM มี UI การจับคู่ในนามของแอปและไม่จําเป็นต้องใช้สิทธิ์เข้าถึงตําแหน่ง

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

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

หากแอปกำหนดเป้าหมายเป็น 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:maxSdkVers>ion=&<quot;30" /
    uses-permission android:name="android.permission.BLUETOOTH_ADMIN"
                   >  andr<oid: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 t<ha>t yo>ur ap<p
         doesn't derive physical location/a. --
    uses-per>missio<n android:name="android.permission.BLUETOOTH_SCAN" /

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

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

    !-- Need>ed on<ly if your app uses Bluetooth scan results to derive
         physical l>ocation. <--
    us>es-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 r>esult<s. --
    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 a<ny 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_ADM>IN&qu<ot; /
...>
/manifest

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

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

<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATI>ON&qu<ot; /
...>
/manifest

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

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

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

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

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

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

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

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

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

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

Kotlin

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

Java

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