באמצעות 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>
מידע נוסף על הרשאות וכדאי להשתמש ב- הרשאות קלות כדי להתחיל.
הצגת המיקום הנוכחי
כדי למצוא את העסק המקומי או מקום אחר שבו המכשיר נמצא כרגע צריך לבצע את השלבים הבאים:
- התקשרות אל
ContextCompat.checkSelfPermission
כדי לבדוק אם המשתמש העניק הרשאה לגשת למכשיר שלו המיקום. האפליקציה צריכה לכלול גם קוד שיבקש מהמשתמשים הרשאה, ולטפל בתוצאה. ראו בקשת הרשאות לאפליקציה לקבלת פרטים. - יוצרים
FindCurrentPlaceRequest
, העברתList
שלPlace.Field
, שמציין את לגבי סוגי הנתונים שהאפליקציה צריכה לבקש. - קוראים לפונקציה
PlacesClient.findCurrentPlace()
, להעביר אתFindCurrentPlaceRequest
שיצרת בכל פעימה. - אפשר להוריד את הרשימה של
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()
האפליקציה צריכה גם להציג ייחוס. אפשר לעיין במסמכים בנושא
שיוכים.