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

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

الإفصاح عن الأذونات

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

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

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

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

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

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

  1. إذا كان تطبيقك يبحث عن devices Bluetooth، مثل الأجهزة الطرفية التي تعمل بالبلوتوث المنخفض الاستهلاك للطاقة، يجب الإفصاح عن الإذن BLUETOOTH_SCAN.
  2. إذا كان تطبيقك يجعل الجهاز الحالي قابلاً للاكتشاف من قِبل أجهزة بلوتوث أخرى، يجب الإفصاح عن إذن BLUETOOTH_ADVERTISE.
  3. إذا كان تطبيقك يتواصل مع devices التي تم إقرانها عبر البلوتوث، يجب الإفصاح عن إذن 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>

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

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

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

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

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

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

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

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

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

لتوفير تطبيقك على الأجهزة التي لا تتوافق مع البلوتوث الكلاسيكي أو تقنية <uses-feature>، يجب تضمين العنصر <uses-feature> في ملف required="false"، ولكن يجب ضبط القيمة على 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);