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

اختَر النظام الأساسي: 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.

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

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

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