لحماية خصوصية المستخدم، يجب أن تطلب التطبيقات التي تستخدم خدمات الموقع الجغرافي أذونات تحديد الموقع الجغرافي.
عند طلب أذونات الموقع الجغرافي، اتّبِع أفضل الممارسات نفسها التي تطبّقها عند طلب أي إذن تشغيل آخر. إنّ أحد الاختلافات المهمة عندما يتعلق الأمر بأذونات تحديد الموقع الجغرافي هو أنّ النظام يتضمّن أذونات متعدّدة مرتبطة بالموقع الجغرافي. وتعتمد الأذونات التي تطلبها وطريقة طلبها على متطلبات الموقع الجغرافي لحالة استخدام تطبيقك.
توضّح هذه الصفحة الأنواع المختلفة لمتطلبات تحديد الموقع الجغرافي، وتقدّم إرشادات حول كيفية طلب أذونات تحديد الموقع الجغرافي في كل حالة.
أنواع الوصول إلى الموقع الجغرافي
يحتوي كل إذن على مجموعة من الخصائص التالية:
- الفئة: إما الموقع الجغرافي في المقدّمة أو الموقع الجغرافي في الخلفية.
- الدقة: إما الموقع الجغرافي الدقيق أو التقريبي
الموقع الجغرافي في المقدّمة
إذا كان تطبيقك يحتوي على ميزة تشارك معلومات الموقع الجغرافي أو تتلقّاها مرة واحدة فقط أو لفترة زمنية محدَّدة، ستتطلّب هذه الميزة الوصول إلى الموقع الجغرافي في المقدّمة. وتشمل بعض الأمثلة ما يلي:
- تتيح ميزة في تطبيق التنقّل للمستخدمين الحصول على اتجاهات مفصّلة.
- تتيح ميزة في تطبيق مراسلة للمستخدمين مشاركة موقعهم الجغرافي الحالي مع مستخدم آخر.
يعتبر النظام أنّ تطبيقك يستخدم الموقع الجغرافي في المقدّمة إذا كانت إحدى ميزات تطبيقك تحصل على الموقع الجغرافي الحالي للجهاز في أحد المواقف التالية:
- إذا كان هناك نشاط ينتمي إلى تطبيقك مرئيًا
يشغِّل تطبيقك خدمة تعمل في المقدّمة. عند تشغيل خدمة تعمل في المقدّمة، يُعلِم النظام المستخدم من خلال عرض إشعار دائم. يحتفظ تطبيقك بالوصول إلى البيانات عندما يكون في الخلفية، مثلاً عندما يضغط العميل على زر الصفحة الرئيسية على جهازه أو يطفئ شاشة جهازه.
بالإضافة إلى ذلك، ننصحك بتقديم بيان عن نوع الخدمة التي تعمل في المقدّمة
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>
رصد الموقع الجغرافي في الخلفية
يتطلب التطبيق الوصول إلى الموقع الجغرافي في الخلفية إذا كانت إحدى الميزات في التطبيق تشارك الموقع الجغرافي باستمرار مع مستخدمين آخرين أو تستخدم واجهة برمجة التطبيقات Geofencing. وفي ما يلي أمثلة عديدة على ذلك:
- تتيح ميزة في تطبيق مشاركة الموقع الجغرافي مع العائلة للمستخدمين باستمرار مشاركة الموقع الجغرافي مع أفراد العائلة.
- تتيح ميزة "إنترنت الأشياء" للمستخدمين ضبط أجهزتهم المنزلية بحيث يتم إيقافها عندما يغادر المستخدم منزله وإعادة تفعيلها عند عودة المستخدم إلى المنزل.
يعتبر النظام أنّ تطبيقك يستخدم الموقع الجغرافي في الخلفية إذا كان يحصل على الموقع الجغرافي الحالي للجهاز في أيّ حالة غير تلك الموضّحة في القسم الموقع الجغرافي في المقدّمة. تكون دقة الموقع الجغرافي في الخلفية مماثلة لدقة الموقع الجغرافي في المقدّمة، والتي تعتمد بدورها على أذونات الموقع الجغرافي التي يعلن عنها تطبيقك.
في الإصدار 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
، يمكنك أن تطلب من المستخدم السماح
لتطبيقك بالوصول إلى الموقع الجغرافي الدقيق.
طلب الوصول إلى الموقع الجغرافي في وقت التشغيل
عندما تحتاج ميزة في تطبيقك إلى الوصول إلى الموقع الجغرافي، عليك الانتظار إلى أن يتفاعل المستخدم مع الميزة قبل تقديم طلب الإذن. يتّبع سير العمل هذا أفضل الممارسات لطلب أذونات التشغيل في السياق، كما هو موضّح في ملف طلب أذونات التطبيقات.
يعرض الشكل 1 مثالاً على كيفية تنفيذ هذه العملية. يحتوي التطبيق على ميزة "مشاركة الموقع الجغرافي" التي تتطلب الوصول إلى الموقع الجغرافي في المقدّمة. ومع ذلك، لا يطلب التطبيق إذن تحديد الموقع الجغرافي إلى أن ينقر المستخدم على زر مشاركة الموقع الجغرافي.
يمكن للمستخدم منح الموقع الجغرافي التقريبي فقط
في الإصدار Android 12 (المستوى 31 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث، يمكن للمستخدمين طلب أن يسترجع تطبيقك
معلومات الموقع الجغرافي التقريبية فقط، حتى إذا كان تطبيقك يطلب
ACCESS_FINE_LOCATION
إذن التشغيل.
للتعامل مع هذا السلوك المحتمل للمستخدم، لا تطلب إذن ACCESS_FINE_LOCATION
بحد ذاته. بدلاً من ذلك، يمكنك طلب إذن ACCESS_FINE_LOCATION
وإذن
ACCESS_COARSE_LOCATION
في طلب بيئة تشغيل واحد. إذا حاولت طلب
ACCESS_FINE_LOCATION
فقط، سيتجاهل النظام الطلب في بعض إصدارات
Android 12. إذا كان تطبيقك يستهدف الإصدار 12 من نظام التشغيل Android أو
إصدارًا أحدث، يسجِّل النظام رسالة الخطأ التالية في
Logcat:
ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.
عندما يطلب تطبيقك الحصول على كل من ACCESS_FINE_LOCATION
وACCESS_COARSE_LOCATION
،
يتضمّن مربّع حوار أذونات النظام الخيارات التالية للمستخدم:
- دقيق: يسمح للتطبيق بالحصول على معلومات عن الموقع الجغرافي الدقيق.
- تقريبي: يسمح لتطبيقك بالحصول على معلومات الموقع الجغرافي التقريبي فقط.
يوضّح الشكل 3 أنّ مربّع الحوار يحتوي على إشارة مرئية لكل من الخيارَين، لمساعدة المستخدم في الاختيار. بعد أن يحدّد المستخدم دقة تحديد الموقع الجغرافي، ينقر على أحد الأزرار الثلاثة لاختيار مدة منح الإذن.
في الإصدار 12 من نظام التشغيل Android والإصدارات الأحدث، يمكن للمستخدمين الانتقال إلى إعدادات النظام لضبط دقة الموقع الجغرافي المفضّلة لأي تطبيق، بغض النظر عن الإصدار المستهدَف من حزمة تطوير البرامج (SDK) لهذا التطبيق. وينطبق ذلك حتى في حال تثبيت تطبيقك على جهاز يعمل بنظام التشغيل Android 11 أو إصدار أقدم، ثم ترقية المستخدم للجهاز إلى Android 12 أو إصدار أحدث.
تأثير اختيار المستخدم في منح الأذونات
يعرض الجدول التالي الأذونات التي يمنحها النظام لتطبيقك، ويستند ذلك إلى الخيارات التي يختارها المستخدم في مربّع حوار وقت تشغيل الأذونات:
دقيق | تقريبي | |
---|---|---|
أثناء استخدام التطبيق | ACCESS_FINE_LOCATION وACCESS_COARSE_LOCATION |
ACCESS_COARSE_LOCATION |
هذه المرّة فقط | ACCESS_FINE_LOCATION وACCESS_COARSE_LOCATION |
ACCESS_COARSE_LOCATION |
رفض | عدم منح أذونات تحديد الموقع الجغرافي | أذونات تحديد الموقع الجغرافي غير متوفّرة |
لتحديد الأذونات التي منحها النظام لتطبيقك، تحقَّق من القيمة المعروضة في طلب الأذونات. يمكنك استخدام مكتبات Jetpack في رمز برمجي مشابه لما يلي، أو يمكنك استخدام مكتبات المنصة التي يمكنك فيها إدارة رمز طلب الإذن بنفسك.
Kotlin
val locationPermissionRequest = registerForActivityResult( ActivityResultContracts.RequestMultiplePermissions() ) { permissions -> when { permissions.getOrDefault(Manifest.permission.ACCESS_FINE_LOCATION, false) -> { // Precise location access granted. } permissions.getOrDefault(Manifest.permission.ACCESS_COARSE_LOCATION, false) -> { // Only approximate location access granted. } else -> { // No location access granted. } } } // ... // Before you perform the actual permission request, check whether your app // already has the permissions, and whether your app needs to show a permission // rationale dialog. For more details, see Request permissions. locationPermissionRequest.launch(arrayOf( Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION))
Java
ActivityResultLauncher<String[]> locationPermissionRequest = registerForActivityResult(new ActivityResultContracts .RequestMultiplePermissions(), result -> { Boolean fineLocationGranted = result.getOrDefault( Manifest.permission.ACCESS_FINE_LOCATION, false); Boolean coarseLocationGranted = result.getOrDefault( Manifest.permission.ACCESS_COARSE_LOCATION,false); if (fineLocationGranted != null && fineLocationGranted) { // Precise location access granted. } else if (coarseLocationGranted != null && coarseLocationGranted) { // Only approximate location access granted. } else { // No location access granted. } } ); // ... // Before you perform the actual permission request, check whether your app // already has the permissions, and whether your app needs to show a permission // rationale dialog. For more details, see Request permissions. locationPermissionRequest.launch(new String[] { Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION });
طلب ترقية إلى الموقع الجغرافي الدقيق
يمكنك أن تطلب من المستخدم ترقية إذن وصول التطبيق من الموقع الجغرافي التقريبي إلى الموقع الجغرافي الدقيق. قبل أن تطلب من المستخدم ترقية إذن وصول تطبيقك إلى
الموقع الجغرافي الدقيق، ننصحك بالتفكير في ما إذا كان سيناريو استخدام تطبيقك يتطلب
هذا المستوى من الدقة. إذا كان تطبيقك يحتاج إلى إقران جهاز مع
أجهزة مجاورة عبر البلوتوث أو Wi-Fi، ننصحك باستخدام إذن
إقران الجهاز المصاحب أو إذن
البلوتوث بدلاً من
طلب إذن ACCESS_FINE_LOCATION
.
لطلب ترقية إذن وصول تطبيقك إلى الموقع الجغرافي من "تقريبي" إلى "دقيق"، اتّبِع الخطوات التالية:
- إذا لزم الأمر، يُرجى توضيح سبب احتياج تطبيقك إلى الإذن.
- يُرجى طلب إذنَي
ACCESS_FINE_LOCATION
وACCESS_COARSE_LOCATION
معًا مرة أخرى. بما أنّ المستخدم سبق أن سمح للنظام بمنح الموقع الجغرافي التقريبي لتطبيقك، سيكون مربّع حوار النظام مختلفًا هذه المرة، كما هو موضح في الشكل 4 والشكل 5:
طلب الموقع الجغرافي في المقدّمة فقط في البداية
حتى إذا كانت عدة ميزات في تطبيقك تتطلّب الوصول إلى الموقع الجغرافي، من المرجّح أن يحتاج بعضها فقط إلى الوصول إلى الموقع الجغرافي في الخلفية. لذلك، يُنصح بأن يُجري تطبيقك طلبات متزايدة للحصول على أذونات تحديد الموقع الجغرافي، بدءًا من طلب الوصول إلى الموقع الجغرافي في المقدّمة ثم طلب الوصول إلى الموقع الجغرافي في الخلفية. ومن خلال تنفيذ طلبات متزايدة، ستمنح المستخدمين مزيدًا من التحكّم والشفافية لأنّهم يستطيعون التعرّف بشكل أفضل على الميزات في تطبيقك التي تحتاج إلى الوصول إلى بيانات الموقع الجغرافي في الخلفية.
يعرض الشكل 6 مثالاً على تطبيق مصمّم للتعامل مع الطلبات المتزايدة. تتطلّب كل من الميزتَين "عرض الموقع الجغرافي الحالي" و "اقتراح أماكن قريبة" إذن الوصول إلى الموقع الجغرافي في المقدّمة. أمّا ميزة "اقتراح أماكن قريبة"، فهى وحدها التي تتطلّب الوصول إلى بيانات الموقع الجغرافي في الخلفية.
في ما يلي عملية تنفيذ الطلبات المتزايدة:
-
في البداية، يجب أن يوجّه تطبيقك المستخدمين إلى الميزات التي تتطلّب الوصول إلى بيانات الموقع الجغرافي في المقدّمة، مثل ميزة "مشاركة الموقع الجغرافي" في الشكل 1 أو ميزة "عرض الموقع الجغرافي الحالي" في الشكل 2.
ننصحك بإيقاف وصول المستخدم إلى الميزات التي تتطلب الوصول إلى الموقع الجغرافي في الخلفية إلى أن يتم منح تطبيقك إذن الوصول إلى الموقع الجغرافي في المقدّمة.
-
في وقت لاحق، عندما يستكشف المستخدم وظائف تتطلب الوصول إلى بيانات الموقع الجغرافي في الخلفية، يمكنك طلب الوصول إلى بيانات الموقع الجغرافي في الخلفية.
طلب رصد الموقع الجغرافي في الخلفية إذا لزم الأمر
تعتمد محتويات مربّع حوار الأذونات على إصدار حزمة SDK المستهدف
عندما تطلب إحدى الميزات في تطبيقك الوصول إلى بيانات الموقع الجغرافي في الخلفية على جهاز يعمل بنظام Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، يتضمّن مربّع حوار أذونات النظام خيارًا بعنوان السماح في كل الأوقات. إذا اختار المستخدم هذا الخيار، تحصل الميزة في تطبيقك على إذن الوصول إلى الموقع الجغرافي في الخلفية.
في نظام التشغيل Android 11 (المستوى 30 من واجهة برمجة التطبيقات) والإصدارات الأحدث، لا يتضمّن مربّع حوار النظام الخيار السماح طوال الوقت. بدلاً من ذلك، على المستخدمين تفعيل ميزة "تحديد الموقع الجغرافي" في الخلفية من صفحة الإعدادات، كما هو موضّح في الشكل 7.
يمكنك مساعدة المستخدمين في الانتقال إلى صفحة الإعدادات هذه باتّباع أفضل الممارسات عند طلب إذن تحديد الموقع الجغرافي في الخلفية. تعتمد عملية منح الإذن على إصدار حزمة تطوير البرامج (SDK) المستهدَف لتطبيقك.
يستهدف التطبيق الإصدار 11 من نظام التشغيل Android أو إصدارًا أحدث
إذا لم يتم منح تطبيقك إذن ACCESS_BACKGROUND_LOCATION
، وعرض
shouldShowRequestPermissionRationale()
true
، يمكنك عرض واجهة مستخدم تعليمية للمستخدمين تتضمّن ما يلي:
- يُرجى توضيح سبب احتياج ميزة التطبيق إلى الوصول إلى الموقع الجغرافي في الخلفية.
- التصنيف المرئي للمستخدم لخيار الإعدادات الذي يمنح إذن رصد الموقع الجغرافي في الخلفية
(على سبيل المثال، السماح طوال الوقت في الشكل 7). يمكنك الاتصال بالرقم
getBackgroundPermissionOptionLabel()
للحصول على هذا التصنيف. يتمّ تعريب القيمة المعروضة لهذه الطريقة لتتوافق مع اللغة المفضّلة للمستخدم على الجهاز. - خيار للمستخدمين لرفض الإذن إذا رفض المستخدمون منح إذن الوصول إلى الموقع الجغرافي في الخلفية، من المفترض أن يتمكنوا من مواصلة استخدام تطبيقك.
يستهدف التطبيق الإصدار 10 من نظام التشغيل Android أو إصدارًا أقدم
عندما تطلب إحدى الميزات في تطبيقك الوصول إلى الموقع الجغرافي في الخلفية، سيظهر للمستخدمين مربع حوار من النظام. يتضمّن مربّع الحوار هذا خيارًا للانتقال إلى موقع تطبيقك الجغرافي وخيارات الأذونات في صفحة الإعدادات.
طالما أنّ تطبيقك يتّبع أفضل الممارسات لطلب أذونات الموقع الجغرافي، لن تحتاج إلى إجراء أي تغييرات للسماح بهذا السلوك.
يمكن أن يؤثر المستخدم في دقة الموقع الجغرافي في الخلفية.
إذا طلب المستخدم تحديد الموقع الجغرافي التقريبي، تنطبق خيارات
المستخدم في مربّع حوار أذونات الموقع الجغرافي أيضًا على رصد الموقع الجغرافي في الخلفية. بعبارة أخرى، إذا منح المستخدم تطبيقك إذن ACCESS_BACKGROUND_LOCATION
ولكنه لم يمنح التطبيق سوى إذن الوصول إلى الموقع الجغرافي التقريبي في المقدّمة، لن يحصل
تطبيقك على إذن الوصول إلى الموقع الجغرافي التقريبي في الخلفية أيضًا.
تذكير بمنح إذن الوصول إلى الموقع الجغرافي في الخلفية
في الإصدار 10 من نظام Android والإصدارات الأحدث، عندما تصل ميزة في تطبيقك إلى الموقع الجغرافي للجهاز في الخلفية للمرة الأولى بعد أن يمنح المستخدم إذن الوصول إلى الموقع الجغرافي في الخلفية، يحدّد النظام موعدًا لإرسال إشعار إلى المستخدم. يذكّر هذا الإشعار المستخدم بأنّه سمح لتطبيقك بالوصول إلى الموقع الجغرافي للجهاز طوال الوقت. يظهر مثال على الإشعار في الشكل 8.
التحقّق من متطلبات الموقع الجغرافي في العناصر الاعتمادية لحزمة تطوير البرامج (SDK) لتطبيقك
تحقّق مما إذا كان تطبيقك يستخدم أيّ حِزم تطوير برامج (SDK) تعتمد على أذونات تحديد الموقع الجغرافي،
وخاصةً إذن ACCESS_FINE_LOCATION
. يمكنك الرجوع إلى هذه المقالة على Medium
حول التعرّف على سلوكيات العناصر الاعتمادية لـ SDK.
مصادر إضافية
لمزيد من المعلومات حول أذونات تحديد الموقع الجغرافي في Android، يمكنك الاطّلاع على المراجع التالية:
الدروس التطبيقية حول الترميز
الفيديوهات
نماذج
- نموذج تطبيق يوضّح استخدام أذونات تحديد الموقع الجغرافي