مکان کنونی (قدیمی)

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

اجازه‌ها

برای استفاده از کتابخانه، نیازی نیست اجازه اضافی در مانیفست برنامه‌تان اعلام کنید، زیرا کتابخانه همه اجازه‌هایی را که استفاده می‌کند در مانیفست خود اعلام می‌کند. بااین‌حال، اگر برنامه شما از PlacesClient.findCurrentPlace() استفاده می‌کند، باید در زمان اجرا اجازه‌های مکان را درخواست کنید.

اگر برنامه‌تان از PlacesClient.findCurrentPlace() استفاده نمی‌کند، اجازه‌های ACCESS_FINE_LOCATION و ACCESS_COARSE_LOCATION را که کتابخانه معرفی کرده است با افزودن موارد زیر به مانیفستتان به‌طور صریح بردارید:

<manifest ... xmlns:tools="http://schemas.android.com/tools">
    ...
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/>
    ...
</manifest>

درباره اجازه‌ها بیشتر بخوانید و برای شروع، استفاده از EasyPermissions را مدنظر قرار دهید.

دریافت مکان کنونی

برای پیدا کردن کسب‌وکار محلی یا مکان دیگری که دستگاه درحال‌حاضر در آنجا قرار دارد، این مراحل را دنبال کنید:

1. با ContextCompat.checkSelfPermission تماس بگیرید تا بررسی کنید کاربر اجازه دسترسی به مکان دستگاهش را داده است یا نه. برنامه شما باید حاوی کدی باشد که از کاربر درخواست اجازه کند و نتیجه را مدیریت کند. برای جزئیات، به درخواست اجازه‌های برنامه مراجعه کنید.
2. با ارسال List از Place.Field، FindCurrentPlaceRequest ایجاد کنید و انواع داده‌های مکان را که برنامه‌تان باید درخواست کند مشخص کنید.
3. با PlacesClient.findCurrentPlace() تماس بگیرید، و FindCurrentPlaceRequest را که در مرحله قبلی ساخته‌اید ارسال کنید.
4. فهرست PlaceLikelihood را از FindCurrentPlaceResponse دریافت کنید.

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

این API FindCurrentPlaceResponse را در Task برمی‌گرداند. FindCurrentPlaceResponse حاوی فهرستی از اشیاء PlaceLikelihood است که مکان‌هایی را نشان می‌دهند که احتمالاً دستگاه در آنجا قرار دارد. برای هر مکان، نتیجه شامل نشانه‌ای از احتمال اینکه مکان درست باشد است. اگر مکان شناخته‌شده‌ای متناظر با مکان دستگاه داده‌شده وجود نداشته باشد، فهرست ممکن است خالی باشد.

می‌توانید PlaceLikelihood.getPlace() را برای بازیابی شیء Place فراخوانی کنید، و PlaceLikelihood.getLikelihood() را برای دریافت رده‌بندی احتمال مکان فراخوانی کنید. مقدار بالاتر به‌معنای احتمال بیشتر برای بهترین مطابقت بودن مکان است.

نمونه کد زیر فهرست مکان‌هایی را که احتمالاً دستگاه در آنجا قرار دارد بازیابی می‌کند و نام و احتمال هر مکان را ثبت می‌کند.

// Use fields to define the data types to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION)
val request = FindCurrentPlaceRequest.newInstance(placeFields)

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) ==
    PackageManager.PERMISSION_GRANTED
) {
    placesClient.findCurrentPlace(request).addOnSuccessListener { response ->
        binding.progressBar.visibility = View.GONE
        adapter.setPlaceLikelihoods(response.placeLikelihoods)
    }.addOnFailureListener { exception ->
        binding.progressBar.visibility = View.GONE
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.statusCode}")
        }
    }
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission()
}

      

// Use fields to define the data types to return.
List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION);

// Use the builder to create a FindCurrentPlaceRequest.
FindCurrentPlaceRequest request = FindCurrentPlaceRequest.newInstance(placeFields);

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
    Task<FindCurrentPlaceResponse> placeResponse = placesClient.findCurrentPlace(request);
    placeResponse.addOnCompleteListener(task -> {
        binding.progressBar.setVisibility(View.GONE);
        if (task.isSuccessful()) {
            FindCurrentPlaceResponse response = task.getResult();
            adapter.setPlaceLikelihoods(response.getPlaceLikelihoods());
        } else {
            Exception exception = task.getException();
            if (exception instanceof ApiException apiException) {
                Log.e("CurrentPlace", "Place not found: " + apiException.getStatusCode());
            }
        }
    });
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission();
}

      

نکاتی درباره مقادیر احتمال:

• احتمال، احتمال نسبی مکان را به‌عنوان بهترین مطابقت در فهرست مکان‌های برگشتی برای یک درخواست واحد ارائه می‌دهد. نمی‌توانید احتمال‌ها را در درخواست‌های مختلف مقایسه کنید.
• مقدار احتمال بین ۰٫۰ و ۱٫۰ خواهد بود.

برای مثال، برای نشان دادن احتمال ۵۵٪ اینکه مکان صحیح «مکان A» است و احتمال ۳۵٪ اینکه «مکان B» است، پاسخ دو عضو دارد، «مکان A» با احتمال ۰٫۵۵ و «مکان B» با احتمال ۰٫۳۵.

نمایش ارجاع‌ها در برنامه

وقتی برنامه شما اطلاعاتی را که از PlacesClient.findCurrentPlace() به‌دست آمده است نمایش می‌دهد، برنامه باید اسناد را نیز نمایش دهد. مستندات مربوط به ارجاع‌ها را ببینید.