طلب أذونات تحديد الموقع الجغرافي

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

للبدء، راجِع أفضل الممارسات المتعلّقة بجميع أذونات وقت التشغيل بالإضافة إلى الإرشادات الأوسع نطاقًا بشأن تقليل طلبات الأذونات.

أنواع الوصول إلى الموقع الجغرافي

يحتوي كل إذن على مجموعة من الخصائص التالية:

الموقع الجغرافي في المقدّمة

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

  • في تطبيق للتنقل، تتيح إحدى الميزات للمستخدمين الحصول على اتجاهات مفصّلة.
  • في تطبيق مراسلة، تتيح إحدى الميزات للمستخدمين مشاركة موقعهم الجغرافي الحالي مع مستخدم آخر.

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

  • يظهر نشاط يخص تطبيقك.

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

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

    <!-- Recommended for Android 9 (API level 28) and lower. -->
<!-- Required for Android 10 (API level 29) and higher. -->
<service
    android:name="MyNavigationService"
    android:foregroundServiceType="location" ... >
    <!-- Any inner elements would go here. -->
</service>

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

<manifest ... >
  <!-- Always include this permission -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

  <!-- Include only if your app benefits from precise location access. -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
</manifest>

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

رصد الموقع الجغرافي في الخلفية

يتطلب التطبيق رصد الموقع الجغرافي في الخلفية إذا كانت إحدى الميزات داخل التطبيق تشارك الموقع الجغرافي باستمرار مع مستخدمين آخرين أو تستخدم Geofencing API. في ما يلي بعض الأمثلة:

  • ضمن تطبيق لمشاركة الموقع الجغرافي مع العائلة، تتيح إحدى الميزات للمستخدمين مشاركة الموقع الجغرافي بشكل مستمر مع أفراد العائلة.
  • في أحد تطبيقات إنترنت الأشياء، تتيح إحدى الميزات للمستخدمين ضبط أجهزة المنزل بحيث يتم إيقافها عندما يغادر المستخدم المنزل وإعادة تشغيلها عندما يعود إليه.

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

على نظام التشغيل Android 10 (مستوى واجهة برمجة التطبيقات 29) والإصدارات الأحدث، يجب الإفصاح عن الإذن ACCESS_BACKGROUND_LOCATION في بيان تطبيقك من أجل طلب رصد الموقع الجغرافي في الخلفية في وقت التشغيل. في الإصدارات السابقة من Android، عندما يحصل تطبيقك على إذن الوصول إلى الموقع الجغرافي أثناء عمله في الواجهة الأمامية، يحصل تلقائيًا على إذن رصد الموقع الجغرافي في الخلفية أيضًا.

<manifest ... >
  <!-- Required only when requesting background location access on
       Android 10 (API level 29) and higher. -->
  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
</manifest>

الدقة

يتيح Android مستويات دقة الموقع الجغرافي التالية:

تقريبي
تقدّم هذه الخدمة تقديرًا للموقع الجغرافي للجهاز. إذا كان تقدير الموقع الجغرافي هذا صادرًا عن LocationManagerService أو FusedLocationProvider، ستكون دقة هذا التقدير في حدود 3 كيلومترات مربّعة تقريبًا (أي 1.2 ميل مربّع تقريبًا). يمكن أن يتلقّى تطبيقك المواقع الجغرافية بهذا المستوى من الدقة عند الإفصاح عن إذن ACCESS_COARSE_LOCATION بدون الإفصاح عن إذن ACCESS_FINE_LOCATION.
دقيق
تقدّم تقديرًا للموقع الجغرافي للجهاز يكون دقيقًا قدر الإمكان. إذا كان تقدير الموقع الجغرافي من LocationManagerService أو FusedLocationProvider، يكون هذا التقدير عادةً في حدود 50 مترًا (160 قدمًا)، ويكون أحيانًا دقيقًا في حدود بضعة أمتار (10 أقدام) أو أكثر. يمكن لتطبيقك تلقّي المواقع الجغرافية بهذا المستوى من الدقة عند تعريف إذن ACCESS_FINE_LOCATION.

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

يجب أن يظل تطبيقك يعمل عندما يمنح المستخدم إذن الوصول إلى بيانات الموقع الجغرافي التقريبية فقط. إذا كانت إحدى الميزات في تطبيقك تتطلّب الوصول إلى الموقع الجغرافي الدقيق باستخدام إذن ACCESS_FINE_LOCATION، يمكنك أن تطلب من المستخدم السماح لتطبيقك بالوصول إلى الموقع الجغرافي الدقيق.

تذكير بمنح إذن رصد الموقع الجغرافي في الخلفية

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

التحقّق من متطلبات الموقع الجغرافي في تبعيات حزمة تطوير البرامج (SDK) لتطبيقك

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

مراجع إضافية

لمزيد من المعلومات حول أذونات تحديد الموقع الجغرافي في Android، يمكنك الاطّلاع على المواد التالية:

اختبارات الرموز

الفيديوهات

نماذج

  • نموذج تطبيق لتوضيح كيفية استخدام أذونات تحديد الموقع الجغرافي