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

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

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

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

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

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

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

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

يوضّح مقتطف الرمز التالي كيفية الإعلان عن الأذونات المتعلقة بالبلوتوث في تطبيقك إذا كان يستهدف الإصدار 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" />

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

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

إذا كان تطبيقك يستهدف Android 11 (المستوى 30 لواجهة برمجة التطبيقات) أو إصدارًا أقدم، يُرجى توضيح الأذونات التالية في ملف بيان التطبيق:

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

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

التعرّف على الأجهزة المحلية التي تتضمّن بلوتوث

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

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

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

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

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

راجِع مرجع <uses-permission> لمزيد من المعلومات حول بيان أذونات التطبيق.

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

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

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

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

إذا كان تطبيقك يعتمد على تقنية Bluetooth Low Energy، يمكنك استخدام ما يلي:

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

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

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

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