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

هناك طرق متعددة لطلب معلومات عن الموقع الجغرافي للجهاز على 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. وتشمل الأمثلة على ذلك ما يلي:

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

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

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

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

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

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

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

مراجع إضافية

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

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

الفيديوهات

نماذج

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