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

باستخدام حزمة تطوير برامج "الأماكن" لأجهزة 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.

ملاحظة: على الرغم من أنّه يمكن استخدام PlacesClient.fetchPlace() لعرض جميع تفاصيل المكان، يمكن استخدام PlacesClient.findCurrentPlace() لعرض مجموعة فرعية فقط من تفاصيل المكان. للحصول على قائمة الحقول التي لا يقبلها findCurrentPlace()، يُرجى الاطّلاع على حقول حزمة تطوير البرامج (SDK) لتطبيق "خرائط Google" لأجهزة Android المتوافقة.

تتطابق الحقول مع نتائج البحث عن الأماكن، وتنقسم إلى ثلاث فئات للفوترة: الأساسية وجهات الاتصال والجو. يتم تحصيل رسوم الاشتراك الأساسية مقابل الحقول الأساسية، ولا يتم تحصيل أي رسوم إضافية. يتم تحصيل رسوم أعلى مقابل حقول "جهة الاتصال" و"الجو". لمزيد من المعلومات حول كيفية فوترة طلبات بيانات "الأماكن"، يُرجى الاطّلاع على الاستخدام والفوترة.

تعرض واجهة برمجة التطبيقات 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، يُرجى الاطّلاع على إعداد برنامج واجهة برمجة التطبيقات Places API.

يمكنك استخدام CancellationToken لمحاولة إلغاء طلب إلى أيّ من فئات الطلبات (على سبيل المثال، FetchPlaceRequest). ويتمّ الإلغاء على أساس أفضل الجهود. بعد تقديم طلب الإلغاء، لن يتم تلقّي أي ردّ. لا يضمن إصدار رمز الإلغاء إلغاء طلب معيّن، وقد يتم تحصيل رسوم منك مقابل الطلب حتى إذا لم يتم عرض أي ردّ.

عرض الإسنادات في تطبيقك

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