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

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

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

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

      

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