הרשאות Bluetooth

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

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

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

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

אם האפליקציה שלכם מטרגטת ל-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. אפשרות אחרת היא להצהיר באופן חד משמעי שהאפליקציה לא מסיקה מיקום פיזי ולהגדיר את ההרשאה ACCESS_FINE_LOCATION לערך 30 ב-android:maxSdkVersion.

ההרשאות 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" />

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

• ההרשאה 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 קלאסי.

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

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

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

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

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

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