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

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

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

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

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

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

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

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

@RequiresApi(Build.VERSION_CODES.N)
fun requestPermissions() {
    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:
    // https://developer.android.com/training/permissions/requesting#request-permission
    locationPermissionRequest.launch(
        arrayOf(
            Manifest.permission.ACCESS_FINE_LOCATION,
            Manifest.permission.ACCESS_COARSE_LOCATION
        )
    )
}
LocationPermissionsActivity.kt

private void requestPermissions() {

    ActivityResultLauncher<String[]> locationPermissionRequest =
            registerForActivityResult(new ActivityResultContracts
                            .RequestMultiplePermissions(), result -> {

                Boolean fineLocationGranted = null;
                Boolean coarseLocationGranted = null;

                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
                    fineLocationGranted = result.getOrDefault(
                            Manifest.permission.ACCESS_FINE_LOCATION, false);
                    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
    });
}
LocationPermissionsActivityJava.java

طلب ترقية إذن الوصول إلى بيانات الموقع الجغرافي الدقيق

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

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

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

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

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

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

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

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

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

2. في وقت لاحق، عندما يستكشف المستخدم الميزات التي تتطلب رصد الموقع الجغرافي في الخلفية، يمكنك طلب رصد الموقع الجغرافي في الخلفية.

مراجع إضافية

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

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

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

الفيديوهات

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

نماذج

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