أذونات البلوتوث

لاستخدام ميزات البلوتوث في تطبيقك، عليك تحديد عدة أذونات. عليك أيضًا تحديد ما إذا كان تطبيقك يتطلّب إتاحة استخدام البلوتوث العادي أو البلوتوث المنخفض الطاقة (BLE). إذا كان تطبيقك لا يتطلّب استخدام بلوتوث الكلاسيكي أو BLE ولكن يمكنه الاستفادة من هاتين التقنيتين، يمكنك التحقّق من مدى توفّرهما في وقت التشغيل.

تضمين الأذونات في نماذج البيان

تعتمد مجموعة الأذونات التي تفصح عنها في تطبيقك على إصدار حزمة SDK المستهدَف في تطبيقك.

استهداف الإصدار 12 من نظام التشغيل Android أو الإصدارات الأحدث

إذا كان تطبيقك يستهدف الإصدار 12 من نظام التشغيل Android (المستوى 31 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، عليك تقديم بيان عن الأذونات التالية في ملف البيان الخاص بتطبيقك:

1. إذا كان تطبيقك يبحث عن أجهزة بلوتوث، مثل أجهزة BLE الطرفية، يجب الإفصاح عن إذن BLUETOOTH_SCAN.
2. إذا كان تطبيقك يجعل الجهاز الحالي قابلاً للاكتشاف من قِبل أجهزة بلوتوث أخرى، عليك الإفصاح عن إذن BLUETOOTH_ADVERTISE.
3. إذا كان تطبيقك يتواصل مع أجهزة بلوتوث سبق إقرانها، عليك الإفصاح عن إذن BLUETOOTH_CONNECT.
4. بالنسبة إلى بيانات الإذن القديمة المتعلقة بالبلوتوث، اضبط قيمة android:maxSdkVersion على 30. تساعد خطوة توافق التطبيق هذه النظام على منح تطبيقك أذونات البلوتوث التي يحتاجها فقط عند تثبيته على الأجهزة التي تعمل بالإصدار 12 من نظام التشغيل Android أو الإصدارات الأحدث.
5. إذا كان تطبيقك يستخدم نتائج البحث عن أجهزة البلوتوث لتحديد الموقع الجغرافي، عليك تضمين إذن ACCESS_FINE_LOCATION في بيان التطبيق. بخلاف ذلك، يمكنك التأكيد بشدة على أنّ تطبيقك لا يستمد الموقع الجغرافي الفعلي وضبط قيمة android:maxSdkVersion على 30 لإذن ACCESS_FINE_LOCATION.

الأذونات BLUETOOTH_ADVERTISE وBLUETOOTH_CONNECT وBLUETOOTH_SCAN هي أذونات وقت التشغيل. لذلك، يجب طلب موافقة المستخدم بشكل صريح في تطبيقك قبل أن تتمكّن من البحث عن أجهزة بلوتوث أو جعل جهاز ما قابلاً للاكتشاف من قِبل الأجهزة الأخرى أو التواصل مع أجهزة بلوتوث سبق إقرانها. عندما يطلب تطبيقك إذنًا واحدًا على الأقل من هذه الأذونات، يطلب النظام من المستخدم السماح لتطبيقك بالوصول إلى الأجهزة المجاورة، كما هو موضّح في الشكل 1.

يوضّح مقتطف الرمز التالي كيفية تعريف الأذونات ذات الصلة بتقنية Bluetooth في تطبيقك إذا كان يستهدف الإصدار 12 من نظام التشغيل Android أو الإصدارات الأحدث:

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

التأكيد بشدة على أنّ تطبيقك لا يستند إلى الموقع الجغرافي الفعلي

إذا كان تطبيقك لا يستخدم نتائج البحث عن أجهزة البلوتوث لتحديد الموقع الجغرافي الفعلي، يمكنك تقديم تأكيد قوي بأنّ تطبيقك لا يستخدم أبدًا أذونات البلوتوث لتحديد الموقع الجغرافي الفعلي. لإجراء ذلك، يُرجى إكمال الخطوات التالية:

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>

استهداف الإصدار 11 من نظام التشغيل Android أو الإصدارات الأقدم

إذا كان تطبيقك يستهدف الإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات) أو إصدارًا أقدم، عليك تقديم بيان عن الأذونات التالية في ملف البيان الخاص بتطبيقك:

• BLUETOOTH ضروري لإجراء أي عملية اتصال عبر البلوتوث الكلاسيكي أو البلوتوث المنخفض الطاقة، مثل طلب اتصال وقبول اتصال ونقل البيانات.
• ACCESS_FINE_LOCATION ضروري لأنّه على نظام التشغيل Android 11 والإصدارات الأقدم، يمكن استخدام عملية البحث عن أجهزة البلوتوث لجمع معلومات عن الموقع الجغرافي للمستخدم.

بما أنّ أذونات تحديد الموقع الجغرافي هي أذونات وقت التشغيل، عليك طلب هذه الأذونات في وقت التشغيل بالإضافة إلى تعريفها في ملف البيان.

اكتشاف أجهزة بلوتوث محلية

إذا كنت تريد أن يبدأ تطبيقك في البحث عن الأجهزة أو تعديل إعدادات البلوتوث، عليك الإفصاح عن إذن BLUETOOTH_ADMIN. تحتاج معظم التطبيقات إلى هذا الإذن فقط لتتمكّن من اكتشاف أجهزة البلوتوث المحلية. يجب عدم استخدام الإمكانات الأخرى التي يمنحها هذا الإذن إلا إذا كان التطبيق "مدير طاقة" يعدّل إعدادات البلوتوث بناءً على طلب المستخدم. يجب تضمين الإذن في ملف بيان التطبيق. على سبيل المثال:

<manifest>
...
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
...
</manifest>

إذا كان تطبيقك يتيح خدمة ويمكن تشغيله على الإصدار 10 (المستوى 29 من واجهة برمجة التطبيقات) أو الإصدار 11 من نظام التشغيل Android، عليك أيضًا تقديم بيان ACCESS_BACKGROUND_LOCATION للحصول على إذن باكتشاف أجهزة البلوتوث. لمزيد من المعلومات حول هذا الشرط، يُرجى الاطّلاع على مقالة الوصول إلى الموقع الجغرافي في الخلفية.

يوضّح مقتطف الرمز البرمجي التالي كيفية تعريف إذن ACCESS_BACKGROUND_LOCATION:

<manifest>
...
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
...
</manifest>

يمكنك الاطّلاع على <uses-permission> المرجع للحصول على مزيد من المعلومات حول الإفصاح عن أذونات التطبيق.

تحديد استخدام ميزة البلوتوث

إذا كان البلوتوث جزءًا مهمًا من تطبيقك، يمكنك إضافة علامات إلى ملف البيان للإشارة إلى هذا الشرط. يتيح لك العنصر <uses-feature> تحديد نوع الأجهزة التي يستخدمها تطبيقك وما إذا كانت مطلوبة أم لا.

يوضّح هذا المثال كيفية الإشارة إلى أنّ تطبيقك يتطلّب استخدام البلوتوث الكلاسيكي.

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

إذا كان تطبيقك يعتمد على البلوتوث المنخفض الطاقة، يمكنك استخدام ما يلي:

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

إذا ذكرت أنّ الميزة مطلوبة لتطبيقك، سيخفي متجر Google Play تطبيقك عن المستخدمين الذين لا تتوفّر لديهم هذه الميزات على أجهزتهم. لهذا السبب، يجب ضبط السمة required على true فقط إذا كان تطبيقك لا يعمل بدون الميزة.

التحقّق من توفّر الميزات في وقت التشغيل

لإتاحة تطبيقك للأجهزة التي لا تتوافق مع البلوتوث الكلاسيكي أو البلوتوث المنخفض الطاقة، عليك تضمين العنصر <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);