הרשאות 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. ניתן לקבל מידע נוסף בנושא מידע נוסף זמין בקטע מיקום גישה רקע.

קטע הקוד הבא מראה איך להצהיר (declare) על 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 הקלאסי או 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);