تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

يشير مربّع الحوار إلى الموقع الجغرافي التقريبي فقط ويحتوي على 3 أزرار فوق بعضها. — **الشكل 2.** مربّع حوار أذونات النظام الذي يظهر عندما يطلب تطبيقك `ACCESS_COARSE_LOCATION` فقط

يحتوي مربّع الحوار على مجموعتَين من الخيارات، إحداهما فوق الأخرى. — **الشكل 3.** مربّع حوار أذونات النظام الذي يظهر عندما يطلب تطبيقك كلاً من `ACCESS_FINE_LOCATION` و `ACCESS_COARSE_LOCATION` في طلب تشغيل واحد

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

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

	دقيق	تقريبي
أثناء استخدام التطبيق	`ACCESS_FINE_LOCATION` و `ACCESS_COARSE_LOCATION`	`ACCESS_COARSE_LOCATION`
هذه المرّة فقط	`ACCESS_FINE_LOCATION` و `ACCESS_COARSE_LOCATION`	`ACCESS_COARSE_LOCATION`
رفض	عدم منح أذونات تحديد الموقع الجغرافي	عدم منح أذونات تحديد الموقع الجغرافي

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

Kotlin

@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

Java

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.

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

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

يحتوي مربّع الحوار على الخيارات "تغيير إلى موقع جغرافي دقیق
"و"هذه المرة فقط" و"رفض". — **الشكل 4.** اختار المستخدم في السابق الخيارَين **تقريبي** و**أثناء استخدام التطبيق** (في مربّع الحوار من الشكل 3).

يحتوي مربّع الحوار على الخيارَين "هذه المرّة فقط" و
'رفض". — **الشكل 5.** اختار المستخدم في السابق **تقريبي** و**هذه المرة فقط** (في مربّع الحوار من الشكل 3).

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

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

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

يكون الزر الذي يتيح الوصول إلى الموقع الجغرافي في المقدّمة
في نصف طول الشاشة من الزر الذي يتيح الوصول إلى
بيانات الموقع الجغرافي في الخلفية. — **الشكل 6.** تتطلّب كلتا الميزتين الوصول إلى بيانات الموقع الجغرافي، ولكن ميزة "اقتراح ميزات قريبة" فقط هي التي تتطلّب الوصول إلى بيانات الموقع الجغرافي في الخلفية.

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

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

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

مصادر إضافية

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

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

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

الفيديوهات

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

نماذج

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