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

اختيار النظام الأساسي: Android iOS

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