הרשאות Bluetooth

כדי להשתמש בתכונות Bluetooth באפליקציה, צריך להצהיר על כמה הרשאות. צריך גם לציין אם האפליקציה דורשת תמיכה ב-Bluetooth רגיל או ב-Bluetooth עם צריכת אנרגיה נמוכה (BLE). אם לאפליקציה שלכם לא נדרש Bluetooth קלאסי או BLE, אבל עדיין אפשר להפיק תועלת מהטכנולוגיות האלה, תוכלו לבדוק את הזמינות בזמן הריצה.

הצהרה על הרשאות

קבוצת ההרשאות שאתם מגדירים באפליקציה תלויה בגרסת ה-SDK היעד של האפליקציה.

טירגוט ל-Android מגרסה 12 ואילך

הערה: ב-Android מגרסה 8.0 (רמת API‏ 26) ואילך, מנהל המכשירים הנלווים (CDM) מספק שיטה יעילה יותר לחיבור למכשירים נלווים, בהשוואה להרשאות המתוארות בקטע הזה. מערכת ה-CDM מספקת ממשק משתמש להתאמה בשם האפליקציה שלכם, ולא נדרשות לה הרשאות מיקום.

אם אתם רוצים לשלוט יותר בחוויית ההתאמה והחיבור, תוכלו להשתמש בהרשאות שמתוארות בקטע הזה.

תיבת דו-שיח של הרשאות Bluetooth
תיבת דו-שיח של הרשאות מערכת, שבה המשתמש מתבקש להעניק לאפליקציה הרשאה לזהות מכשירים בקרבת מקום, לפרסם להם ולהתחבר אליהם.

אם האפליקציה שלכם מטרגטת ל-Android 12 (רמת API 31) ואילך, צריך להצהיר על ההרשאות הבאות בקובץ המניפסט של האפליקציה:

  1. אם האפליקציה מחפשת מכשירי Bluetooth, כמו ציוד היקפי מסוג BLE, צריך להצהיר על ההרשאה BLUETOOTH_SCAN.
  2. אם האפליקציה מאפשרת לזהות את המכשיר הנוכחי במכשירי Bluetooth אחרים, צריך להצהיר על ההרשאה BLUETOOTH_ADVERTISE.
  3. אם האפליקציה מתקשרת עם מכשירי Bluetooth שכבר מותאמים, צריך להצהיר על ההרשאה BLUETOOTH_CONNECT.
  4. בהצהרות ההרשאות הקודמות שקשורות ל-Bluetooth, מגדירים את הערך של android:maxSdkVersion ל-30. שלב התאימות לאפליקציה עוזר למערכת להעניק לאפליקציה רק את הרשאות ה-Bluetooth הנדרשות לה כשהיא מותקנת במכשירים עם Android מגרסה 12 ואילך.
  5. אם האפליקציה משתמשת בתוצאות של סריקת Bluetooth כדי להסיק את המיקום הפיזי, צריך להצהיר על ההרשאה ACCESS_FINE_LOCATION. אחרת, תוכלו לטעון בבירור שהאפליקציה לא מפיקה מיקום פיזי.

ההרשאות BLUETOOTH_ADVERTISE,‏ BLUETOOTH_CONNECT ו-BLUETOOTH_SCAN הן הרשאות בסביבת זמן ריצה. לכן, עליכם לבקש אישור מהמשתמש באפליקציה לפני שתוכלו לחפש מכשירי Bluetooth, להפוך מכשיר לגלוי למכשירים אחרים או לתקשר עם מכשירי Bluetooth שמותאמים כבר. כשהאפליקציה מבקשת לפחות אחת מההרשאות האלה, המערכת מבקשת מהמשתמש לאשר לאפליקציה גישה למכשירים בקרבת מקום, כפי שמוצג באיור 1.

קטע הקוד הבא מראה איך להצהיר על הרשאות שקשורות ל-Bluetooth באפליקציה אם היא מטרגטת את 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>

הצהרה נחרצת על כך שהאפליקציה לא מפיקה מיקום פיזי

אם האפליקציה לא משתמשת בתוצאות הסריקה של Bluetooth כדי להסיק את המיקום הפיזי, אפשר להצהיר בביטחון שהאפליקציה אף פעם לא משתמשת בהרשאות Bluetooth כדי להסיק את המיקום הפיזי. כדי לעשות זאת, מבצעים את השלבים הבאים:

  1. מוסיפים את המאפיין android:usesPermissionFlags להצהרת ההרשאה BLUETOOTH_SCAN ומגדירים את הערך של המאפיין הזה כ-neverForLocation.

  2. אם לאפליקציה שלכם לא נדרשת גישה למיקום בשום אופן אחר, תוכלו להסיר את ההרשאה ACCESS_FINE_LOCATION מהמניפסט של האפליקציה.

קטע הקוד הבא מראה איך לעדכן את קובץ המניפסט של האפליקציה:

<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) וגרסאות קודמות, עליכם להצהיר על ההרשאות הבאות בקובץ המניפסט של האפליקציה:

  • BLUETOOTH נדרש לביצוע כל תקשורת Bluetooth רגילה או BLE, כמו בקשה לחיבור, אישור חיבור והעברת נתונים.
  • ACCESS_FINE_LOCATION נדרש כי בגרסה Android 11 וגרסאות קודמות, סריקה של Bluetooth עשויה לשמש לאיסוף מידע על המיקום של המשתמש.

הרשאות המיקום הן הרשאות בסביבת זמן ריצה, ולכן צריך לבקש את ההרשאות האלה בסביבת זמן הריצה, וגם להצהיר עליהן במניפסט.

גילוי מכשירי Bluetooth מקומיים

אם אתם רוצים שהאפליקציה תיזום חיפוש של מכשירים או שתשנה את הגדרות ה-Bluetooth, עליכם להצהיר על ההרשאה BLUETOOTH_ADMIN. רוב האפליקציות זקוקות להרשאה הזו רק כדי לזהות מכשירי Bluetooth מקומיים. אסור להשתמש ביכולות האחרות שמתקבלות מההרשאה הזו, אלא אם האפליקציה היא 'מנהל צריכת חשמל' שמשנה את הגדרות ה-Bluetooth לפי בקשת המשתמש. מגדירים את ההרשאה בקובץ המניפסט של האפליקציה. לדוגמה:

<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>

אם האפליקציה תומכת בשירות מסוים ויכולה לפעול ב-Android 10 (רמת API 29) או ב-Android 11, צריך להצהיר גם על ההרשאה ACCESS_BACKGROUND_LOCATION כדי לזהות מכשירים עם Bluetooth. מידע נוסף על הדרישה הזו זמין במאמר גישה למיקום ברקע.

בקטע הקוד הבא מוצגת ההצהרה על ההרשאה ACCESS_BACKGROUND_LOCATION:

<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>

למידע נוסף על הצהרה על הרשאות לאפליקציה, אפשר לעיין במסמך העזרה של <uses-permission>.

ציון השימוש בתכונות Bluetooth

אם Bluetooth הוא רכיב קריטי באפליקציה, אפשר להוסיף דגלים לקובץ המניפסט כדי לציין את הדרישה הזו. באמצעות האלמנט <uses-feature> אפשר לציין את סוג החומרה שבה האפליקציה משתמשת ואם היא נדרשת.

בדוגמה הזו מוסבר איך לציין שהאפליקציה שלכם דורשת Bluetooth ‎classic.

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

אם האפליקציה שלכם מסתמכת על Bluetooth עם צריכת אנרגיה נמוכה (BLE), תוכלו להשתמש באפשרויות הבאות:

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

אם תציינו שהתכונה הזו נדרשת לאפליקציה, האפליקציה תוסתר מחנות Google Play למשתמשים במכשירים שלא כוללים את התכונות האלה. לכן, צריך להגדיר את המאפיין הנדרש ל-true רק אם האפליקציה לא יכולה לפעול בלי התכונה.

בדיקת הזמינות של תכונות בזמן הריצה

כדי שהאפליקציה תהיה זמינה למכשירים שלא תומכים ב-Bluetooth קלאסי או ב-BLE, עדיין צריך לכלול את האלמנט <uses-feature> במניפסט של האפליקציה, אבל להגדיר את 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);