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

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

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

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

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

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

إذا كنت تريد مزيدًا من التحكّم في تجربة الإقران والاتصال، استخدِم الأذونات الموضّحة في هذا القسم.

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

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

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

استهداف Android 11 أو الإصدارات الأقدم

إذا كان تطبيقك يستهدف نظام التشغيل 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"/>

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

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

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

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

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