הרשאות Bluetooth

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

    <!-- 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 Classic או 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 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);