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

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

دستورالعمل‌های دسترسی به اجازه‌های مکان

برخی‌از قوانین کلی که باید هنگام تصمیم‌گیری درباره نحوه پیاده‌سازی دسترسی به مکان در برنامه‌تان رعایت کنید.

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

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

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

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

در Android 12 (میانای برنامه‌سازی کاربردی سطح ۳۱) یا بالاتر، کاربران می‌توانند درخواست کنند که برنامه شما فقط اطلاعات مکان تقریبی را بازیابی کند، حتی زمانی که برنامه شما اجازه زمان اجرای 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 را درخواست می‌کند، کادر گفتگوی اجازه‌های سیستم شامل گزینه‌های زیر برای کاربر است:

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

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

در Android 12 و نسخه‌های بالاتر، کاربران می‌توانند به تنظیمات سیستم بروند و دقت مکان ترجیحی را برای هر برنامه‌ای، صرف‌نظر از نسخه کیت توسعه نرم‌افزار هدف آن برنامه، تنظیم کنند. این موضوع حتی زمانی که برنامه شما روی دستگاهی با سیستم‌عامل Android 11 یا پایین‌تر نصب شده باشد و سپس کاربر دستگاه را به 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 را دوباره باهم درخواست کنید. ازآنجایی‌که کاربر قبلاً به سیستم اجازه داده است مکان تقریبی را به برنامه‌تان بدهد، کادر گفتگوی سیستم این بار متفاوت است، همان‌طور که در شکل ۴ و شکل ۵ نشان داده شده است:

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

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

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

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

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

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

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

منابع بیشتر

برای کسب اطلاعات بیشتر درباره اجازه‌های مکان در Android، مطالب زیر را مشاهده کنید:

Codelabs

• روال‌های مطلوب حریم خصوصی

ویدیوها

• نحوه یافتن استفاده احتمالی از مکان پس‌زمینه‌ای

نمونه‌ها

• برنامه نمونه برای نشان دادن استفاده از اجازه‌های مکان.