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

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

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

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

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

لكل إذن مجموعة من السمات التالية:

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

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

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

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

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

• النشاط الخاص بتطبيقك مرئي.

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

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

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

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

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

طلب الوصول إلى الموقع الجغرافي في وقت التشغيل

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

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

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

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

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

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

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

مصادر إضافية

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

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

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

الفيديوهات الطويلة

• طريقة معرفة الاستخدام المحتمل لرصد الموقع الجغرافي في الخلفية

العيّنات

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