المكان الحالي (الإصدار القديم)

المطوّرون في المنطقة الاقتصادية الأوروبية

باستخدام حزمة تطوير البرامج (SDK) للأماكن في 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. أنشئ FindCurrentPlaceRequest، مع تمرير List من Place.Field، مع تحديد أنواع بيانات الأماكن التي يجب أن يطلبها تطبيقك.
  3. استدعِ PlacesClient.findCurrentPlace()، مع تمرير FindCurrentPlaceRequest الذي أنشأته في الخطوة السابقة.
  4. احصل على قائمة PlaceLikelihood من FindCurrentPlaceResponse.

تتوافق الحقول مع نتائج "البحث عن الأماكن"، وتنقسم إلى ثلاث فئات للفوترة: "أساسية" و"معلومات الاتصال" و"الأجواء". تتم فوترة الحقول الأساسية بالسعر الأساسي، ولا يتم تحصيل أي رسوم إضافية. يتم تحصيل رسوم أعلى مقابل حقول "معلومات الاتصال" و"الأجواء". لمزيد من المعلومات حول كيفية فوترة طلبات بيانات الأماكن، يُرجى الاطّلاع على الاستخدام والفوترة.

تعرض واجهة برمجة التطبيقات FindCurrentPlaceResponse في Task. يحتوي FindCurrentPlaceResponse على قائمة بعناصر PlaceLikelihood تمثّل الأماكن التي يُرجَّح أن يكون الجهاز فيها. بالنسبة إلى كل مكان، تتضمّن النتيجة مؤشرًا على احتمال أن يكون المكان هو المكان الصحيح. قد تكون القائمة فارغة إذا لم يكن هناك مكان معروف يتوافق مع الموقع الجغرافي المحدّد للجهاز.

يمكنك استدعاء PlaceLikelihood.getPlace() لاسترداد عنصر Place وPlaceLikelihood.getLikelihood() للحصول على تقييم احتمالية المكان. وتعني القيمة الأعلى احتمالاً أكبر بأنّ المكان هو أفضل مطابقة.

يستردّ نموذج الرمز البرمجي التالي قائمة الأماكن التي يُرجّح أن يكون الجهاز موجودًا فيها، ويسجّل اسم كل مكان واحتمالية وجود الجهاز فيه.

Kotlin

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

// Define the search area around the current location (500m radius).
val currentLocation = LatLng(37.4220, -122.0841)
val circle = CircularBounds.newInstance(currentLocation, 500.0)
val request = SearchNearbyRequest.builder(circle, placeFields)
    .setMaxResultCount(20)
    .build()

// Call searchNearby and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) ==
    PackageManager.PERMISSION_GRANTED
) {
    placesClient.searchNearby(request).addOnSuccessListener { response ->
        binding.progressBar.visibility = View.GONE
        adapter.setPlaces(response.places)
    }.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);

// Define the search area around the current location.
LatLng currentLocation = new LatLng(37.4220, -122.0841);
LocationRestriction circle =
        CircularBounds.newInstance(currentLocation, /* radius= */ 500.0);

// Use the builder to create a SearchNearbyRequest.
SearchNearbyRequest request =
        SearchNearbyRequest.builder(circle, placeFields).setMaxResultCount(20).build();

// Call searchNearby and handle the response (first check that the user has granted
// permission).
if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION)
        == PackageManager.PERMISSION_GRANTED) {
    Task<SearchNearbyResponse> placeResponse = placesClient.searchNearby(request);
    placeResponse.addOnCompleteListener(
            task -> {
                binding.progressBar.setVisibility(View.GONE);
                if (task.isSuccessful()) {
                    SearchNearbyResponse response = task.getResult();
                    adapter.setPlaces(response.getPlaces());
                } 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();
}

      

ملاحظات حول قيم الاحتمالية:

  • يوفّر الاحتمال نسبة مئوية نسبية لكون المكان هو أفضل مطابقة ضمن قائمة الأماكن التي تم عرضها لطلب واحد. لا يمكنك مقارنة الاحتمالات في الطلبات المختلفة.
  • ستتراوح قيمة الاحتمالية بين 0.0 و1.0.

على سبيل المثال، لتمثيل احتمال بنسبة% 55 بأنّ المكان الصحيح هو المكان "أ"، واحتمال بنسبة% 35 بأنّه المكان "ب"، يتضمّن الردّ عنصرَين، المكان "أ" باحتمال 0.55 والمكان "ب" باحتمال 0.35.

عرض معلومات تحديد المصدر في تطبيقك

عندما يعرض تطبيقك معلومات تم الحصول عليها من PlacesClient.findCurrentPlace()، يجب أن يعرض التطبيق أيضًا معلومات تحديد المصدر. يمكنك الاطّلاع على المستندات حول عمليات تحديد المصدر.