הרשאות Bluetooth

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

ההרשאות 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 עם צריכת אנרגיה נמוכה, תוכלו להשתמש בתכונות הבאות:

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

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

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

כדי שהאפליקציה תהיה זמינה למכשירים שלא תומכים ב-Bluetooth קלאסי או ב-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);