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

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

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

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

      

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