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

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

   ملاحظة: في حال تضمين neverForLocation في android:usesPermissionFlags، تمت فلترة بعض إشارات BLE من الفحص نتائجك.

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 والإصدارات الأقدم استخدامها لجمع معلومات حول موقع المستخدم.

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

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

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

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

<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():

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