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

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

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

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

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

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

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

    <!-- 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 لإجراء أي اتصال عبر تقنية Bluetooth Classic أو BLE، مثل طلب الاتصال وقبول الاتصال ونقل البيانات.
• ACCESS_FINE_LOCATION ضروري لأنّه في نظام التشغيل Android 11 والإصدارات الأقدم، يمكن استخدام البحث عن بلوتوث لجمع معلومات عن الموقع الجغرافي للمستخدم.

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

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

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

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

إذا كان تطبيقك متوافقًا مع إحدى الخدمات ويمكن تشغيله على الإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) أو الإصدار 11 من نظام التشغيل Android، عليك أيضًا الإعلان عن إذن 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"/>

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

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

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

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

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