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

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

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

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

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

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

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

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

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

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

في الإصدار 12 من نظام التشغيل Android (المستوى 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 أو إصدار أحدث.

يشير مربّع الحوار إلى الموقع الجغرافي التقريبي فقط
ويحتوي على 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، يُرجى الاطّلاع على المراجع التالية:

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

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

الفيديوهات

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

نماذج

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