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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختيار النظام الأساسي: Android iOS

باستخدام حزمة تطوير البرامج (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() للحصول على تقييم احتمالية المكان. تعني القيمة الأعلى أنّ هناك احتمالاً أكبر بأن يكون المكان الأفضل مطابقة.

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

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();
}

      

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()
}

      

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

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

على سبيل المثال، لتمثيل احتمالية 55% أن المكان الصحيح هو المكان (أ)، واحتمال بنسبة 35% أنه هو المكان (ب)، فإن الاستجابة تشتمل على عضوين، المكان (أ) مع احتمالية 0.55 والمكان (ب) مع احتمالية 0.35.

عرض الإحالات في تطبيقك

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