المكان الحالي

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

باستخدام Places SDK for 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.Fields، مع تحديد أنواع بيانات الأماكن التي يجب أن يطلبها تطبيقك.
  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: List<Place.Field> = listOf(Place.Field.NAME)

// Use the builder to create a FindCurrentPlaceRequest.
val request: FindCurrentPlaceRequest = 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) {

    val placeResponse = placesClient.findCurrentPlace(request)
    placeResponse.addOnCompleteListener { task ->
        if (task.isSuccessful) {
            val response = task.result
            for (placeLikelihood: PlaceLikelihood in response?.placeLikelihoods ?: emptyList()) {
                Log.i(
                    TAG,
                    "Place '${placeLikelihood.place.name}' has likelihood: ${placeLikelihood.likelihood}"
                )
            }
        } else {
            val exception = task.exception
            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()
}

Java

// Use fields to define the data types to return.
List<Place.Field> placeFields = Collections.singletonList(Place.Field.NAME);

// 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 -> {
        if (task.isSuccessful()){
            FindCurrentPlaceResponse response = task.getResult();
            for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) {
                Log.i(TAG, String.format("Place '%s' has likelihood: %f",
                    placeLikelihood.getPlace().getName(),
                    placeLikelihood.getLikelihood()));
            }
        } else {
            Exception exception = task.getException();
            if (exception instanceof ApiException) {
                ApiException apiException = (ApiException) exception;
                Log.e(TAG, "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()، يجب أن يعرض التطبيق أيضًا بيانات المصدر. يمكنك الاطّلاع على المستندات حول المصادر.