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

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

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

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

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

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

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

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

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

لمعرفة الأذونات التي منحها النظام لتطبيقك، تحقَّق من القيمة المعروضة عند طلب الأذونات. يمكنك استخدام مكتبات 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، يمكنك الاطّلاع على المواد التالية:

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

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

الفيديوهات

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

نماذج

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