מעבר ללקוח SDK חדש של 'מקומות'

במדריך זה מוסבר השינויים בין המקומות את ספריית התאימות של האתר או את הגרסה הנפרדת החדשה של Places SDK ל-Android. אם השתמשת בספריית התאימות של 'מקומות' במקום לעבור אל בגרסה העצמאית החדשה של Places SDK ל-Android, המדריך הזה מראה איך לעדכן את הפרויקטים שלכם כך שישתמשו בגרסה החדשה של Places SDK ל-Android.

הדרך היחידה לגשת לתכונות ולתיקוני באגים ב-Places SDK ל-Android גרסה 2.6.0 שלמעלה תשתמש ב-Place SDK ל-Android. Google ממליצה לעדכן מספריית התאימות לגרסה החדשה Places SDK לגרסת Android בהקדם האפשרי.

מה השתנה?

תחומי השינוי העיקריים הם:

  • מופצת הגרסה החדשה של Places SDK ל-Android בתור ספריית לקוח סטטית. לפני ינואר 2019, Places SDK ל-Android הפך לזמין דרך Google Play Services. מאז, סופקה של ספריית תאימות כדי להקל את המעבר Places SDK ל-Android.
  • יש כל השיטות החדשות.
  • עכשיו יש תמיכה במסכות שדות ל-methods שמחזירות מקומות פרטים. אפשר להשתמש במסכות של שדות כדי לציין אילו סוגים של נתוני מקומות החזרה.
  • שיפרנו את קודי הסטטוס שמשמשים לדיווח על שגיאות.
  • בהשלמה האוטומטית יש עכשיו תמיכה באסימונים של סשנים.
  • הכלי לבחירת מקום לא זמין יותר.

מידע על ספריית התאימות של 'מקומות'

בינואר 2019 כשתושק גרסה 1.0 של ה-Places SDK הנפרד ל-Android, Google סיפקה ספריית תאימות כדי לעזור בהעברה מגרסת Google Play Services שהוצא משימוש של Places SDK ל-Android (com.google.android.gms:play-services-places).

ספריית התאימות הזו סופקה באופן זמני להפניה אוטומטית ולתרגום קריאות ל-API שמיועדות לגרסת Google Play Services לגרסה העצמאית החדשה עד שהמפתחים יוכלו להעביר את הקוד שלהם ולהשתמש בשמות החדשים SDK עצמאי. לכל גרסה של Places SDK ל-Android הושקה מגרסה 1.0 עד גרסה 2.6.0, גרסה תואמת. של ספריית התאימות של 'מקומות' שוחררו כדי לספק החדשה.

הקפאה והוצאה משימוש של ספריית התאימות של 'מקומות'

כל הגרסאות של ספריית התאימות של Places SDK ל-Android הוצאו משימוש ב-31 במרץ 2022. גרסה 2.6.0 היא הגרסה האחרונה של ספריית התאימות למקומות. הדרך היחידה לגשת לתכונות ולתיקוני באגים ב'מקומות' ב-SDK ל-Android מגרסה 2.6.0 ייעשה שימוש ב-Place SDK ל-Android.

Google ממליצה לעבור ל-Place SDK ל-Android כדי לגשת לתכונות חדשות ולתיקוני באגים קריטיים בגרסאות קודמות של גרסה 2.6.0. אם אתם משתמשים כרגע בספריית התאימות, אתם צריכים לפעול לפי השלבים הבאים התקנת הקטע 'מקומות SDK ל-Android' כדי לבצע העברה ל-Places SDK ל-Android.

התקנת ספריית הלקוח

הגרסה החדשה של Places SDK ל-Android מופצת ספריית לקוח סטטית.

משתמשים ב-Maven כדי להוסיף את Places SDK ל-Android לפרויקט Android Studio:

  1. אם אתם משתמשים כרגע בספריית התאימות של 'מקומות':

    1. צריך להחליף את השורה הבאה בקטע dependencies:

          implementation 'com.google.android.libraries.places:places-compat:X.Y.Z'

      באמצעות השורה הזו, ניתן לעבור ל-Place SDK ל-Android:

          implementation 'com.google.android.libraries.places:places:3.3.0'

  2. אם אתם משתמשים כרגע בגרסת Play Services של Places SDK ל-Android:

    1. צריך להחליף את השורה הבאה בקטע dependencies:

          implementation 'com.google.android.gms:play-services-places:X.Y.Z'

      באמצעות השורה הזו, ניתן לעבור ל-Place SDK ל-Android:

          implementation 'com.google.android.libraries.places:places:3.3.0'

  3. מסנכרנים את פרויקט Gradle.

  4. מגדירים את הערך minSdkVersion של פרויקט האפליקציה ל-16 ואילך.

  5. עדכון של "Powered by Google" נכסים:

    @drawable/powered_by_google_light // OLD
@drawable/places_powered_by_google_light // NEW
@drawable/powered_by_google_dark // OLD
@drawable/places_powered_by_google_dark // NEW

  6. יוצרים את האפליקציה אם מופיעות שגיאות build כתוצאה מההמרה ל- Places SDK ל-Android לקבלת מידע נוסף, עיינו בקטעים שלמטה על פתרון השגיאות האלה.

הפעלת הלקוח החדש של Places SDK

מפעילים את הלקוח החדש Places SDK כפי שמוצג בדוגמה הבאה:

// Add an import statement for the client library.
import com.google.android.libraries.places.api.Places;

...

// Initialize Places.
Places.initialize(getApplicationContext(), apiKey);

// Create a new Places client instance.
PlacesClient placesClient = Places.createClient(this);

קודי סטטוס

קוד הסטטוס לשגיאות של מגבלות QPS השתנה. שגיאות במגבלות QPS הן עכשיו הוחזרה דרך PlaceStatusCodes.OVER_QUERY_LIMIT. אין יותר מגבלות על QPD.

קודי הסטטוס הבאים נוספו:

  • REQUEST_DENIED – הבקשה נדחתה. הסיבות האפשריות לכך:

    • לא סופק מפתח API.
    • הזנת מפתח API לא חוקי.
    • Places API לא הופעל במסוף Cloud.
    • סופק מפתח API עם הגבלות שגויות על מפתחות.

  • INVALID_REQUEST – הבקשה לא תקינה כי חסרה או לא תקינה ארגומנט.

  • NOT_FOUND – לא נמצאה תוצאה עבור הבקשה הנתונה.

שיטות חדשות

הגרסה החדשה של Places SDK ל-Android מציגה חידושים כדי לשמור על עקביות. כל השיטות החדשות לפעול בהתאם להנחיות הבאות:

  • נקודות הקצה לא משתמשות יותר בפועל get.
  • לאובייקטים של בקשות ושל תשובות יש שם זהה לאובייקט המתאים שיטת הלקוח.
  • לבקשת אובייקטים יש עכשיו builder: הפרמטרים הנדרשים מועברים כבקשה בפרמטרים של ה-builder.
  • אנחנו כבר לא משתמשים במאגרי נתונים זמניים.

בקטע הזה מוצגות השיטות החדשות ומוסבר איך הן פועלות.

אחזור מקום לפי מזהה

שימוש ב-fetchPlace() כדי לקבל פרטים על מקום ספציפי. הפונקציה fetchPlace() פועלת באופן דומה getPlaceById().

כדי לאחזר מקום, פועלים לפי השלבים הבאים:

  1. קוראים לפונקציה fetchPlace(), מעבירים אובייקט FetchPlaceRequest שמציין מקום מזהה ורשימה של שדות שמציינים את נתוני המקום שרוצים להחזיר.

    // Define a Place ID.
String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
FetchPlaceRequest request = FetchPlaceRequest.builder(placeId, placeFields)
        .build();

  2. צריך להתקשר אל addOnSuccessListener() כדי לטפל בFetchPlaceResponse. סינגל מוחזרת תוצאה אחת (Place).

    // Add a listener to handle the response.
placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
  Place place = response.getPlace();
  Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        ApiException apiException = (ApiException) exception;
        int statusCode = apiException.getStatusCode();
        // Handle error with given status code.
        Log.e(TAG, "Place not found: " + exception.getMessage());
    }
});

שליפת תמונה של מקום

שימוש ב-fetchPhoto() כדי לקבל תמונה של מקום. fetchPhoto() מחזירה תמונות של מקום. הדפוס תהליך בקשת התמונה היה פשוט יותר. עכשיו אפשר לבקש PhotoMetadata ישירות מהאובייקט Place; אין יותר צורך בבקשה נפרדת. רוחב או גובה מקסימלי של תמונות הוא 1600 פיקסלים. פונקציות של fetchPhoto() בדומה ל-getPhoto().

כדי לאחזר תמונות של מקומות:

  1. מגדירים שיחה אל fetchPlace(). חשוב לכלול את השדה PHOTO_METADATAS בבקשה שלך:

    List<Place.Field> fields = Arrays.asList(Place.Field.PHOTO_METADATAS);

  2. קבלת אובייקט Place (בדוגמה הזו נעשה שימוש ב-fetchPlace(), אבל אפשר גם להשתמש findCurrentPlace()):

    FetchPlaceRequest placeRequest = FetchPlaceRequest.builder(placeId, fields).build();

  3. מוסיפים OnSuccessListener כדי לקבל את המטא-נתונים של התמונה Place ב-FetchPlaceResponse, ולאחר מכן להשתמש במטא-נתונים של התמונה שהתקבלו כדי מקבלים מפת סיביות וטקסט שיוך (Attribution):

    placesClient.fetchPlace(placeRequest).addOnSuccessListener((response) -> {
    Place place = response.getPlace();

    // Get the photo metadata.
    PhotoMetadata photoMetadata = place.getPhotoMetadatas().get(0);

    // Get the attribution text.
    String attributions = photoMetadata.getAttributions();

    // Create a FetchPhotoRequest.
    FetchPhotoRequest photoRequest = FetchPhotoRequest.builder(photoMetadata)
            .setMaxWidth(500) // Optional.
            .setMaxHeight(300) // Optional.
            .build();
    placesClient.fetchPhoto(photoRequest).addOnSuccessListener((fetchPhotoResponse) -> {
        Bitmap bitmap = fetchPhotoResponse.getBitmap();
        imageView.setImageBitmap(bitmap);
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            int statusCode = apiException.getStatusCode();
            // Handle error with given status code.
            Log.e(TAG, "Place not found: " + exception.getMessage());
        }
    });
});

חיפוש מקום מהמיקום של המשתמש

שימוש ב-findCurrentPlace() כדי למצוא את המיקום הנוכחי של המכשיר של המשתמש. findCurrentPlace() מחזירה רשימה של PlaceLikelihood שמציינת מקומות שבהם המכשיר של המשתמש נמצאת בסבירות הגבוהה ביותר. הפונקציה findCurrentPlace() פועלת באופן דומה getCurrentPlace().

כדי לדעת את המיקום הנוכחי של המכשיר של המשתמש, יש לבצע את השלבים הבאים:

  1. צריך לוודא שהאפליקציה מבקשת את ACCESS_FINE_LOCATION וגם ACCESS_WIFI_STATE הרשאות. המשתמש צריך להעניק הרשאת גישה המיקום הנוכחי של המכשיר. מידע נוסף זמין בקטע שליחת בקשה לאפליקציה הרשאות עבור פרטים.

  2. ליצור FindCurrentPlaceRequest, כולל רשימה של סוגים של נתוני מקומות כדי החזרה.

      // Use fields to define the data types to return.
  List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME);

  // Use the builder to create a FindCurrentPlaceRequest.
  FindCurrentPlaceRequest request =
          FindCurrentPlaceRequest.builder(placeFields).build();

  3. קרא ל-FindCurrentPlace וטפל בתגובה, ולאחר מכן יש לבדוק כדי לוודא המשתמש העניק הרשאה להשתמש במיקום המכשיר שלו.

      // Call findCurrentPlace and handle the response (first check that the user has granted permission).
  if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
      placesClient.findCurrentPlace(request).addOnSuccessListener(((response) -> {
          for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) {
              Log.i(TAG, String.format("Place '%s' has likelihood: %f",
                      placeLikelihood.getPlace().getName(),
                      placeLikelihood.getLikelihood()));
              textView.append(String.format("Place '%s' has likelihood: %f\n",
                      placeLikelihood.getPlace().getName(),
                      placeLikelihood.getLikelihood()));
          }
      })).addOnFailureListener((exception) -> {
          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();
  }

איך למצוא חיזויים להשלמה אוטומטית

שימוש ב-findAutocompletePredictions() כדי להחזיר חיזויים של מקומות בתגובה לשאילתות חיפוש של משתמשים. הפונקציה findAutocompletePredictions() פועלת באופן דומה getAutocompletePredictions().

בדוגמה הבאה מפעילים את findAutocompletePredictions():

// Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
// and once again when the user makes a selection (for example when calling fetchPlace()).
AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();
// Create a RectangularBounds object.
RectangularBounds bounds = RectangularBounds.newInstance(
  new LatLng(-33.880490, 151.184363),
  new LatLng(-33.858754, 151.229596));
// Use the builder to create a FindAutocompletePredictionsRequest.
FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
// Call either setLocationBias() OR setLocationRestriction().
   .setLocationBias(bounds)
   //.setLocationRestriction(bounds)
   .setCountry("au")
   .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
   .setSessionToken(token)
   .setQuery(query)
   .build();

placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
   for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
       Log.i(TAG, prediction.getPlaceId());
       Log.i(TAG, prediction.getPrimaryText(null).toString());
   }
}).addOnFailureListener((exception) -> {
   if (exception instanceof ApiException) {
       ApiException apiException = (ApiException) exception;
       Log.e(TAG, "Place not found: " + apiException.getStatusCode());
   }
});

אסימוני סשן

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

מסכות שדה

בשיטות שמחזירות פרטי מקום, צריך לציין את סוגי המקומות הנתונים שיחזרו עם כל בקשה. זה עוזר להבטיח שאתם רק מבקשים (ומשלמים על) הנתונים שתשתמשו בהם בפועל.

כדי לציין אילו סוגי נתונים יוחזרו, צריך להעביר מערך של פונקציות Place.Field FetchPlaceRequest, כמו בדוגמה הבאה:

// Include address, ID, and phone number.
List<Place.Field> placeFields = Arrays.asList(Place.Field.ADDRESS,
                                              Place.Field.ID,
                                              Place.Field.PHONE_NUMBER);

אפשר להשתמש באחד או יותר מהשדות הבאים:

  • Place.Field.ADDRESS
  • Place.Field.ID
  • Place.Field.LAT_LNG
  • Place.Field.NAME
  • Place.Field.OPENING_HOURS
  • Place.Field.PHONE_NUMBER
  • Place.Field.PHOTO_METADATAS
  • Place.Field.PLUS_CODE
  • Place.Field.PRICE_LEVEL
  • Place.Field.RATING
  • Place.Field.TYPES
  • Place.Field.USER_RATINGS_TOTAL
  • Place.Field.VIEWPORT
  • Place.Field.WEBSITE_URI

מידע נוסף על מק"טים של נתוני מקומות

עדכונים לגבי בורר מקומות והשלמה אוטומטית

חלק זה מסביר את השינויים בווידג'טים של 'מקומות' (בורר מקום ו השלמה אוטומטית).

השלמה אוטומטית פרוגרמטית

בוצעו השינויים הבאים בהשלמה האוטומטית:

  • השם של PlaceAutocomplete השתנה ל-Autocomplete.
    • השם של PlaceAutocomplete.getPlace השתנה ל-Autocomplete.getPlaceFromIntent.
    • השם של PlaceAutocomplete.getStatus השתנה ל-Autocomplete.getStatusFromIntent.
  • השם של PlaceAutocomplete.RESULT_ERROR השתנה ל-AutocompleteActivity.RESULT_ERROR (טיפול בשגיאות עבור קטע של השלמה אוטומטית לא השתנה).

בוחר מקומות

הכלי לבחירת מקומות הוצא משימוש ב-29 בינואר 2019. היא כובתה מ-29 ביולי 2019. העמודה הזו לא זמינה יותר. שימוש מתמשך יגרום הודעת שגיאה. ערכת ה-SDK החדשה לא תומכת בבורר המקומות.

ווידג'טים של השלמה אוטומטית

הווידג'טים של ההשלמה האוטומטית עודכנו:

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

בקטעים הבאים מוסבר איך להוסיף ווידג'ט להשלמה אוטומטית לפרויקט.

הטמעה של AutocompleteFragment

כדי להוסיף מקטע של השלמה אוטומטית, מבצעים את השלבים הבאים:

  1. צריך להוסיף שבר לפריסת ה-XML של הפעילות, כמו שמוצג כאן לדוגמה.

    <fragment
  android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name=
"com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

  2. כדי להוסיף לפעילות את הווידג'ט של ההשלמה האוטומטית:

    • מפעילים את Places, מעבירים את ההקשר של האפליקציה ואת מפתח ה-API.
    • צריך להפעיל את AutocompleteSupportFragment.
    • צריך להתקשר למספר setPlaceFields() כדי לציין את סוגי נתוני המקום הרצויים כדי להשיג.
    • יש להוסיף PlaceSelectionListener כדי לבצע פעולה כלשהי עם התוצאה, וגם לטפל בשגיאות שעלולות להתרחש.

    בדוגמה הבאה אפשר לראות הוספת ווידג'ט של השלמה אוטומטית לפעילות:

    /**
 * Initialize Places. For simplicity, the API key is hard-coded. In a production
 * environment we recommend using a secure mechanism to manage API keys.
 */
if (!Places.isInitialized()) {
    Places.initialize(getApplicationContext(), "YOUR_API_KEY");
}

// Initialize the AutocompleteSupportFragment.
AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
        getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
    @Override
    public void onPlaceSelected(Place place) {
        // TODO: Get info about the selected place.
        Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
    }

    @Override
    public void onError(Status status) {
        // TODO: Handle the error.
        Log.i(TAG, "An error occurred: " + status);
    }
});

משתמשים ב-Intent כדי להפעיל את פעילות ההשלמה האוטומטית.

  1. הפעלת Places, העברת הקשר של האפליקציה ומפתח ה-API
  2. משתמשים ב-Autocomplete.IntentBuilder כדי ליצור Intent, להעביר את ההכוונה הרצויה מצב PlaceAutocomplete (מסך מלא או שכבת-על). הכוונה חייבת להפעיל startActivityForResult, באמצעות העברת קוד בקשה שמזהה את בכוונה טובה.
  3. כדי לקבל את המקום שנבחר, צריך לבטל את הקריאה החוזרת של onActivityResult.

הדוגמה הבאה מראה איך להשתמש ב-Intent כדי להפעיל השלמה אוטומטית ולאחר מכן מטפלים בתוצאה:

    /**
     * Initialize Places. For simplicity, the API key is hard-coded. In a production
     * environment we recommend using a secure mechanism to manage API keys.
     */
    if (!Places.isInitialized()) {
        Places.initialize(getApplicationContext(), "YOUR_API_KEY");
    }

    ...

    // Set the fields to specify which types of place data to return.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

    ...

    /**
     * Override the activity's onActivityResult(), check the request code, and
     * do something with the returned place data (in this example its place name and place ID).
     */
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
            if (resultCode == RESULT_OK) {
                Place place = Autocomplete.getPlaceFromIntent(data);
                Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
            } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
                // TODO: Handle the error.
                Status status = Autocomplete.getStatusFromIntent(data);
                Log.i(TAG, status.getStatusMessage());
            } else if (resultCode == RESULT_CANCELED) {
                // The user canceled the operation.
            }
        }
    }

הכלי לבחירת מקומות לא זמין יותר

הכלי לבחירת מקומות הוצא משימוש ב-29 בינואר 2019. היא כובתה מ-29 ביולי 2019. העמודה הזו לא זמינה יותר. שימוש מתמשך יגרום הודעת שגיאה. ערכת ה-SDK החדשה לא תומכת בבורר המקומות.