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

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

สิทธิ์ 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" />

    <!-- Not needed if you can strongly assert that your app never derives
         physical location from Bluetooth scan results and doesn't need location
         access for any other purpose. -->
    <strike><uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /></strike>
    ...
</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() ดังนี้

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