המיקום הנוכחי

מפתחים באזור הכלכלי האירופי (EEA)

באמצעות Places 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.Fields, ומציינים את סוגי נתוני המקום שהאפליקציה צריכה לבקש.
  3. מתקשרים אל PlacesClient.findCurrentPlace() ומעבירים את FindCurrentPlaceRequest שיצרתם בשלב הקודם.
  4. מקבלים את רשימת PlaceLikelihood מ-FindCurrentPlaceResponse.

השדות תואמים לתוצאות של חיפוש מקומות, והם מחולקים לשלוש קטגוריות לחיוב: בסיסי, פרטי קשר ואווירה. החיוב על שדות בסיסיים הוא לפי התעריף הבסיסי, ולא חלים עליהם חיובים נוספים. החיוב על השדות 'איש קשר' ו'אווירה' הוא גבוה יותר. למידע נוסף על החיוב על בקשות לנתוני מקומות, אפשר לעיין במאמר שימוש וחיוב.

ממשק ה-API מחזיר 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(), היא חייבת להציג גם את פרטי השיוך. מידע נוסף זמין במאמר בנושא שיוך.