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

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

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

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