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

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

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

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

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

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

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

کاتلین 

@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 نشان داده شده است:
گفتگو حاوی گزینه های 'تغییر به دقیق است مکان»، «فقط این بار» و «انکار».
شکل 4. کاربر قبلاً Approximate و When using app را انتخاب کرده بود (در گفتگوی شکل 3 ).
گفتگو حاوی گزینه های "فقط این بار" و 'انکار'.
شکل 5. کاربر قبلاً Approximate و Only this time را انتخاب کرده بود (در گفتگوی شکل 3 ).

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

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

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

دکمه ای که دسترسی به موقعیت پیش زمینه را امکان پذیر می کند در فاصله نیمی از صفحه نمایش از دکمه ای که پس زمینه را فعال می کند قرار گرفته است مکان
شکل 6. هر دو ویژگی به دسترسی به موقعیت مکانی نیاز دارند، اما فقط ویژگی "توصیه ویژگی های نزدیک" به دسترسی به موقعیت مکانی پس زمینه نیاز دارد.

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

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

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

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

منابع اضافی

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

Codelabs

ویدیوها

نمونه ها