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

لحماية خصوصية المستخدم، يجب أن تطلب التطبيقات التي تستخدم خدمات الموقع الجغرافي أذونات تحديد الموقع الجغرافي.

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

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

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

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

• الفئة: إما الموقع الجغرافي في المقدّمة أو الموقع الجغرافي في الخلفية.
• الدقة: إما الموقع الجغرافي الدقيق أو التقريبي

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

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

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

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

• إذا كان هناك نشاط ينتمي إلى تطبيقك مرئيًا

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

  بالإضافة إلى ذلك، ننصحك بتقديم بيان عن نوع الخدمة التي تعمل في المقدّمة‏ 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 أو إصدار أحدث.

تأثير اختيار المستخدم في منح الأذونات

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

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

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

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.

لطلب ترقية إذن وصول تطبيقك إلى الموقع الجغرافي من إذن الوصول التقريبي إلى إذن الوصول الدقيق، اتّبِع الخطوات التالية:

1. إذا لزم الأمر، وضِّح سبب احتياج تطبيقك إلى الإذن.
2. يُرجى طلب إذنَي ACCESS_FINE_LOCATION وACCESS_COARSE_LOCATION معًا مرة أخرى. بما أنّ المستخدم سبق أن سمح للنظام بمنح الموقع الجغرافي التقريبي لتطبيقك، سيكون مربّع حوار النظام مختلفًا هذه المرة، كما هو موضح في الشكل 4 والشكل 5:

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

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

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

في ما يلي عملية تنفيذ الطلبات المتزايدة:

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

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

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، يمكنك الاطّلاع على المراجع التالية:

الدروس التطبيقية حول الترميز

• أفضل الممارسات المتعلقة بالخصوصية

الفيديوهات

• كيفية العثور على حالات استخدام محتمل للموقع الجغرافي في الخلفية

نماذج

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