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

หากต้องการใช้ฟีเจอร์บลูทูธในแอป คุณต้องประกาศสิทธิ์หลายรายการ นอกจากนี้ คุณควรระบุว่าแอปของคุณต้องใช้การรองรับบลูทูธคลาสสิกหรือบลูทูธพลังงานต่ำ (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: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>

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

หากบลูทูธเป็นส่วนสําคัญของแอป คุณสามารถเพิ่ม Flag ลงในไฟล์ 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() ดังนี้

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