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

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

اگر برنامه شما اندروید ۱۷ (سطح API ۳۷) یا بالاتر را هدف قرار می‌دهد و فقط شامل ویژگی‌هایی است که برای عملکرد به دسترسی به موقعیت مکانی مبتنی بر جلسه نیاز دارند، سیاست Google Play شما را ملزم به استفاده از دکمه موقعیت مکانی می‌کند. برای جزئیات بیشتر، به سیاست دکمه موقعیت مکانی مراجعه کنید.

نمایش جریان درون برنامه‌ای دکمه موقعیت مکانی
شکل ۱. نمایش جریان کاربری دکمه مکان.

چه زمانی از دکمه مکان استفاده کنیم

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

موارد استفاده رایج عبارتند از:

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

سفارشی سازی رابط کاربری

برای اطمینان از اینکه دکمه با زیبایی‌شناسی برنامه شما مطابقت دارد و در عین حال قابل تشخیص است، می‌توانید عناصر بصری زیر را تغییر دهید:

  • طرح رنگ پس‌زمینه و آیکون.
  • سبک، اندازه و شکل کلی را مشخص کنید.
  • برچسب‌های متنی از یک لیست از پیش تعریف شده (مثلاً «استفاده از موقعیت مکانی دقیق»، «اشتراک‌گذاری موقعیت مکانی دقیق»).
نمایش دکمه موقعیت مکانی از گزینه‌های سفارشی‌سازی
شکل ۲. نمونه‌هایی از گزینه‌های سفارشی‌سازی دکمه موقعیت مکانی.

دکمه مکان را پیاده‌سازی کنید

برای ادغام دکمه موقعیت مکانی، از کتابخانه Jetpack استفاده کنید. این کتابخانه راه‌اندازی را ساده می‌کند، رندر امن را در پلتفرم‌های جدیدتر مدیریت می‌کند و یک جایگزین برای برنامه‌هایی که اندروید ۱۶ و پایین‌تر را هدف قرار می‌دهند، فراهم می‌کند.

مرحله ۱: اعلام مجوزها در مانیفست اندروید

شما باید مجوزهای استاندارد مکان را به همراه مجوز اختصاصی USE_LOCATION_BUTTON که توسط سرویس رندرینگ از راه دور سیستم مورد نیاز است، اعلام کنید.

<?xml version="1.0" encoding="utf-8"?>
<!--
     Copyright 2026 The Android Open Source Project

     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
     You may obtain a copy of the License at

          https://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License.
-->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- 1. Standard Coarse and Fine Location Permissions -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!-- Optional: If your app is only using the location button to access 
    location, you should add the "onlyForLocationButton" flag shown below to
    your ACCESS_FINE_LOCATION declaration.

    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" 
    android:usesPermissionFlags="onlyForLocationButton"/>

    Note: Adding this flag restricts your app from accessing the precise 
    location permission via the broader permission, and that users will be 
    required to use the location button in order to share precise location with 
    the app. This is designed to improve user privacy & trust when granting location access.
    -->

    <!-- 2. CRITICAL: Required system permission for rendering the LocationButton -->
    <uses-permission android:name="android.permission.USE_LOCATION_BUTTON" />

    <application
        android:icon="@mipmap/ic_launcher"
        android:label="LocationButtonSample"
        android:theme="@style/Theme.PinPoint">
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

مرحله ۲: پیاده‌سازی کاتلین کامپوزبل

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

import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.width
import androidx.compose.runtime.Composable
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.core.locationbutton.compose.LocationButton
import androidx.core.locationbutton.compose.LocationButtonTextType

@Composable
fun LocationPermissionScreen(onPermissionGranted: () -> Unit, onPermissionDenied: () -> Unit) {
    // Renders the secure system-trusted Location Button composable
    LocationButton(
        // Callback triggered when the user taps the secure button and makes a decision on the permission dialog
        onPermissionResult = { isGranted ->
            if (isGranted) {
                onPermissionGranted()
            } else {
                onPermissionDenied()
            }
        },
        /* ============================================================================
         * VISUAL CUSTOMIZATIONS
         * Un-comment any of the parameters below to customize the button's aesthetics.
         * If omitted, the button falls back to secure, high-contrast system defaults.
         * ============================================================================ */
        /*
        // LABEL TEXT TYPE:
        // Predefined system strings rendered inside the secure process.
        // Options: PreciseLocation, UsePreciseLocation, SharePreciseLocation,
        // NearMyPreciseLocation, or None (for an icon-only button).
        textType = LocationButtonTextType.UsePreciseLocation,

        // COLOR PALETTE:
        // Customize the container background, text label, and icon tint colors.
        backgroundColor = Color(0xFF00796B), // e.g., Material Teal
        textColor = Color.White,
        iconTint = Color(0xFFFFC107),        // e.g., Amber icon tint

        // CORNER RADIUS & SHAPE:
        // Define the resting corner radius and the morphed radius when pressed.
        cornerRadius = 24.dp,        // Rounded capsule shape
        pressedCornerRadius = 12.dp, // Morphs to sharper corners on tap

        // OUTLINE STROKE (BORDERS):
        // Add a contrasting outline stroke around the button bounds.
        strokeColor = Color(0xFF004D40),
        strokeWidth = 2.dp,

        // INTERACTIVE TOUCH PADDING:
        // Defines the secure clickable touch target boundary.
        // Coerced securely by the system between 4.dp and 8.dp.
        clickablePadding = PaddingValues(6.dp)
        */
    )
}

مرحله ۳: سازگاری با نسخه‌های قبلی را مدیریت کنید

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

با استفاده از این رویکرد، می‌توانید از مزایای استفاده از دکمه موقعیت مکانی بدون نیاز به حفظ یک راهکار موازی برای دستگاه‌هایی که اندروید ۱۶ یا پایین‌تر دارند، بهره‌مند شوید.