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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

في الإصدار Android 12 (المستوى 31 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث، يمكن للمستخدمين طلب أن يسترجع تطبيقك معلومات الموقع الجغرافي التقريبية فقط، حتى إذا كان تطبيقك يطلب ACCESS_FINE_LOCATION إذن التشغيل.

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

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

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

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

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

مصادر إضافية

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

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

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

الفيديوهات

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

نماذج

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