درخواست دسترسی به مکان در زمان اجرا

وقتی یک ویژگی در برنامه شما نیاز به دسترسی به موقعیت مکانی دارد، قبل از ارسال درخواست مجوز، صبر کنید تا کاربر با آن ویژگی تعامل کند. این گردش کار از بهترین شیوه درخواست مجوزهای زمان اجرا در متن پیروی می‌کند، همانطور که در راهنمایی که نحوه درخواست مجوزهای برنامه را توضیح می‌دهد، توضیح داده شده است.

شکل ۱ مثالی از نحوه انجام این فرآیند را نشان می‌دهد. این برنامه شامل یک ویژگی «اشتراک‌گذاری موقعیت مکانی» است که نیاز به دسترسی موقعیت مکانی پیش‌زمینه دارد. با این حال، برنامه تا زمانی که کاربر دکمه اشتراک‌گذاری موقعیت مکانی را انتخاب نکند، درخواست مجوز موقعیت مکانی نمی‌کند.

پس از اینکه کاربر دکمه اشتراک‌گذاری موقعیت مکانی را انتخاب کرد، پنجره‌ی مجوز موقعیت مکانی سیستم ظاهر می‌شود.
شکل ۱. ویژگی اشتراک‌گذاری موقعیت مکانی که نیاز به دسترسی موقعیت مکانی پیش‌زمینه دارد. این ویژگی در صورتی فعال می‌شود که کاربر گزینه «فقط هنگام استفاده از برنامه اجازه دهید» را انتخاب کند.

کاربر فقط می‌تواند موقعیت مکانی تقریبی را اعطا کند

در اندروید ۱۲ (سطح API 31) یا بالاتر، کاربران می‌توانند از برنامه شما بخواهند که فقط اطلاعات تقریبی موقعیت مکانی را بازیابی کند، حتی زمانی که برنامه شما مجوز زمان اجرای ACCESS_FINE_LOCATION را درخواست می‌کند.

برای مدیریت این رفتار احتمالی کاربر، مجوز ACCESS_FINE_LOCATION را به تنهایی درخواست نکنید. در عوض، هم مجوز ACCESS_FINE_LOCATION و هم مجوز ACCESS_COARSE_LOCATION در یک درخواست زمان اجرا درخواست کنید. اگر سعی کنید فقط ACCESS_FINE_LOCATION درخواست کنید، سیستم در برخی از نسخه‌های اندروید ۱۲ درخواست را نادیده می‌گیرد. اگر برنامه شما اندروید ۱۲ یا بالاتر را هدف قرار می‌دهد، سیستم پیام خطای زیر را در Logcat ثبت می‌کند:

ACCESS_FINE_LOCATION must be requested with ACCESS_COARSE_LOCATION.

وقتی برنامه شما هم ACCESS_FINE_LOCATION و هم ACCESS_COARSE_LOCATION را درخواست می‌کند، پنجره‌ی مجوزهای سیستم شامل گزینه‌های زیر برای کاربر است:

  • دقیق : به برنامه شما اجازه می‌دهد اطلاعات دقیق موقعیت مکانی را دریافت کند.
  • تقریبی : به برنامه شما اجازه می‌دهد فقط اطلاعات تقریبی موقعیت مکانی را دریافت کند.

شکل ۳ نشان می‌دهد که این کادر محاوره‌ای شامل یک راهنمای بصری برای هر دو گزینه است تا به کاربر در انتخاب کمک کند. پس از اینکه کاربر در مورد دقت موقعیت مکانی تصمیم گرفت، برای انتخاب مدت زمان اعطای مجوز، روی یکی از سه دکمه ضربه می‌زند.

در اندروید ۱۲ و بالاتر، کاربران می‌توانند به تنظیمات سیستم بروند تا دقت موقعیت مکانی دلخواه را برای هر برنامه‌ای، صرف نظر از نسخه SDK هدف آن برنامه، تنظیم کنند. این موضوع حتی زمانی که برنامه شما روی دستگاهی با اندروید ۱۱ یا پایین‌تر نصب شده باشد و سپس کاربر دستگاه را به اندروید ۱۲ یا بالاتر ارتقا دهد، نیز صادق است.

این کادر محاوره‌ای فقط به موقعیت تقریبی اشاره دارد و شامل ۳ دکمه است که یکی بالای دیگری قرار دارد
شکل ۲. پنجره‌ی مجوزهای سیستم که وقتی برنامه‌ی شما فقط درخواست ACCESS_COARSE_LOCATION را می‌دهد، ظاهر می‌شود.
این کادر محاوره‌ای دو مجموعه گزینه دارد که یکی بالای دیگری قرار دارد
شکل ۳. پنجره‌ی مجوزهای سیستم که وقتی برنامه‌ی شما هر دو 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 در کدی مشابه کد زیر استفاده کنید، یا می‌توانید از کتابخانه‌های پلتفرم استفاده کنید که در آن خودتان کد درخواست مجوز را مدیریت می‌کنید .

کاتلین 

@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

درخواست ارتقا به موقعیت مکانی دقیق

می‌توانید از کاربر بخواهید که دسترسی برنامه شما را از موقعیت مکانی تقریبی به موقعیت مکانی دقیق ارتقا دهد. با این حال، قبل از اینکه از کاربر بخواهید دسترسی برنامه شما را به موقعیت مکانی دقیق ارتقا دهد، در نظر بگیرید که آیا مورد استفاده برنامه شما کاملاً به این سطح از دقت نیاز دارد یا خیر. اگر برنامه شما نیاز به جفت کردن دستگاهی با دستگاه‌های مجاور از طریق بلوتوث یا وای‌فای دارد، به جای درخواست مجوز ACCESS_FINE_LOCATION ، استفاده از مجوزهای جفت شدن دستگاه همراه یا بلوتوث را در نظر بگیرید.

برای درخواست از کاربر برای ارتقاء دسترسی موقعیت مکانی برنامه شما از تقریبی به دقیق، موارد زیر را انجام دهید:

  1. در صورت لزوم، توضیح دهید که چرا برنامه شما به این مجوز نیاز دارد .
  2. مجوزهای ACCESS_FINE_LOCATION و ACCESS_COARSE_LOCATION را دوباره با هم درخواست کنید. از آنجا که کاربر قبلاً به سیستم اجازه داده است که موقعیت مکانی تقریبی را به برنامه شما اعطا کند، این بار پنجره سیستم متفاوت است، همانطور که در شکل ۴ و شکل ۵ نشان داده شده است:
این کادر محاوره‌ای شامل گزینه‌های «تغییر به مکان دقیق»، «فقط این بار» و «رد کردن» است.
شکل ۴. کاربر قبلاً گزینه‌های تقریبی و هنگام استفاده از برنامه را انتخاب کرده بود (در کادر محاوره‌ای شکل ۳ ).
این کادر محاوره‌ای شامل گزینه‌های «فقط این بار» و «رد کردن» است.
شکل ۵. کاربر قبلاً این بار گزینه‌های تقریبی و فقط را انتخاب کرده بود (در کادر محاوره‌ای شکل ۳ ).

در ابتدا فقط موقعیت مکانی پیش‌زمینه را درخواست کنید

حتی اگر چندین ویژگی در برنامه شما نیاز به دسترسی به موقعیت مکانی داشته باشند، احتمالاً فقط برخی از آنها به دسترسی به موقعیت مکانی در پس‌زمینه نیاز دارند. بنابراین، توصیه می‌شود که برنامه شما درخواست‌های افزایشی برای مجوزهای موقعیت مکانی را انجام دهد، ابتدا درخواست دسترسی به موقعیت مکانی در پیش‌زمینه و سپس درخواست دسترسی به موقعیت مکانی در پس‌زمینه. با انجام درخواست‌های افزایشی، به کاربران کنترل و شفافیت بیشتری می‌دهید زیرا آنها می‌توانند بهتر درک کنند که کدام ویژگی‌های برنامه شما به دسترسی به موقعیت مکانی در پس‌زمینه نیاز دارند.

شکل ۶ نمونه‌ای از یک برنامه را نشان می‌دهد که برای مدیریت درخواست‌های افزایشی طراحی شده است. هر دو ویژگی «نمایش مکان فعلی» و «توصیه مکان‌های نزدیک» نیاز به دسترسی به مکان در پیش‌زمینه دارند. با این حال، فقط ویژگی «توصیه مکان‌های نزدیک» نیاز به دسترسی به مکان در پس‌زمینه دارد.

دکمه‌ای که دسترسی به موقعیت مکانی پیش‌زمینه را فعال می‌کند، به اندازه نصف طول صفحه نمایش از دکمه‌ای که موقعیت مکانی پس‌زمینه را فعال می‌کند، فاصله دارد.
شکل ۶. هر دو ویژگی نیاز به دسترسی به موقعیت مکانی دارند، اما فقط ویژگی «توصیه ویژگی‌های نزدیک» نیاز به دسترسی به موقعیت مکانی در پس‌زمینه دارد.

روند انجام درخواست‌های افزایشی به شرح زیر است:

  1. در ابتدا، برنامه شما باید کاربران را به سمت ویژگی‌هایی که نیاز به دسترسی به موقعیت مکانی در پیش‌زمینه دارند، مانند ویژگی «اشتراک‌گذاری موقعیت مکانی» در شکل ۱ یا ویژگی «نمایش موقعیت مکانی فعلی» در شکل ۲، هدایت کند.

    توصیه می‌شود تا زمانی که برنامه شما به موقعیت مکانی پیش‌زمینه دسترسی پیدا نکرده است، دسترسی کاربر به ویژگی‌هایی که نیاز به دسترسی به موقعیت مکانی در پس‌زمینه دارند را غیرفعال کنید.

  2. بعداً، وقتی کاربر ویژگی‌هایی را بررسی می‌کند که نیاز به دسترسی به موقعیت مکانی در پس‌زمینه دارند، می‌توانید درخواست دسترسی به موقعیت مکانی در پس‌زمینه را بدهید .

منابع اضافی

برای اطلاعات بیشتر در مورد مجوزهای موقعیت مکانی در اندروید، مطالب زیر را مشاهده کنید:

کدلبز

ویدیوها

نمونه‌ها