הרשאות Bluetooth

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

הצהרת ההרשאות

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

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

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

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

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

אם האפליקציה שלכם מטרגטת ל-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.

   הערה: אם כוללים את neverForLocation android:usesPermissionFlags, חלק מאותות BLE מסוננים מהסריקה תוצאות.

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 יכול לשמש לאיסוף מידע על המיקום של משתמש.

הערה: במכשירים עם Android מגרסה 8.0 ואילך, אפשר להשתמש CompanionDeviceManager כדי לבצע סריקה של מכשירים נלווים בקרבת מקום בשם האפליקציה דרישה להרשאת המיקום. מידע נוסף על האפשרות הזו זמין במאמר מצב Companion התאמת מכשירים.

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

מציאת מכשירי 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 ‎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():

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);