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

בחירת פלטפורמה: Android iOS

באמצעות 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.

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

ה-API מחזיר FindCurrentPlaceResponse ב- Task. FindCurrentPlaceResponse מכיל רשימה של אובייקטים של PlaceLikelihood שמייצגים מקומות שבהם המכשיר ככל הנראה נמצא. התוצאה של כל מקום כוללת אינדיקציה לסבירות שהמקום הוא הנכון. יכול להיות שהרשימה ריקה, אם לא ידוע על מקום שתואם למיקום המכשיר הנתון.

אפשר להתקשר אל PlaceLikelihood.getPlace() כדי לאחזר אובייקט Place, וגם PlaceLikelihood.getLikelihood() כדי לקבל את דירוג הסבירות של המקום. ככל שהערך גבוה יותר, כך עולה הסבירות שהמקום יתאים בצורה הטובה ביותר.

קטע הקוד הבא מאחזר את רשימת המקומות שבהם סביר להניח שהמכשיר נמצא, ומתעד את השם והסבירות של כל מקום.

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

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

הערות לגבי ערכי הסבירות:

  • הסבירות היא לספק השוואה סבירה של המקום כדי להתאים באופן הטוב ביותר ברשימת המקומות המוחזרים בבקשה יחידה. לא ניתן להשוות סבירות בין בקשות שונות.
  • ערך הסבירות הוא בין 0.0 ל-1.0.

לדוגמה, כדי להציג סבירות של 55% שהמקום הנכון הוא מקום א' וסבירות של 35% שזהו מקום ב', התגובה תהיה שני חברים, מקום א' עם סבירות 0.55 ומקום ב' עם סבירות 0.35.

הצגת שיוכים באפליקציה

כשמוצגים באפליקציה שלך פרטים שהתקבלו מהאפליקציה PlacesClient.findCurrentPlace(), האפליקציה צריכה גם להציג שיוכים. אפשר לקרוא את התיעוד בנושא שיוך (Attribution).