새 Places SDK 클라이언트로 마이그레이션

이 가이드에서는 장소 간 변경 사항을 설명합니다. 최신 독립형 버전의 Android용 Places SDK. 새 버전으로 이전하는 대신 장소 호환성 라이브러리를 사용해 온 경우 이 가이드에서는 Android용 Places SDK의 새로운 독립형 버전을 새 버전의 Android용 Places SDK를 사용하도록 프로젝트를 업데이트하는 방법

Android용 Places SDK 버전 2.6.0 이상에서 기능과 버그 수정에 액세스하는 유일한 방법은 Android용 Places SDK를 사용하는 것입니다. 호환성 라이브러리에서 새로운 가능한 한 빨리 Android용 Places SDK 버전을 제공합니다.

변경사항

주요 변경 영역은 다음과 같습니다.

  • Android용 Places SDK의 새 버전이 정적 클라이언트 라이브러리로 사용할 수 있습니다. 2019년 1월 이전의 Android용 Places SDK Google Play 서비스를 통해 사용할 수 있게 된 것입니다. 그 이후로 새 버전의 API로의 전환을 용이하게 하기 위해 Android용 Places SDK.
  • 완전히 새로운 메서드가 제공됩니다.
  • 이제 장소를 반환하는 메서드에 필드 마스크가 지원됩니다. 확인하세요. 필드 마스크를 사용하여 반환합니다.
  • 오류를 보고하는 데 사용되는 상태 코드가 개선되었습니다.
  • 이제 자동 완성에서 세션 토큰을 지원합니다.
  • 장소 선택 도구는 더 이상 사용할 수 없습니다.

장소 호환성 라이브러리 정보

2019년 1월, Android용 Places SDK의 버전 1.0이 출시되면서 이전을 돕기 위해 Google에서 호환성 라이브러리 제공 사용 중단된 Android용 Places SDK의 Google Play 서비스 버전에서 (com.google.android.gms:play-services-places)

이 호환성 라이브러리는 리디렉션 및 변환을 위해 임시로 제공되었습니다. Google Play 서비스 버전을 대상으로 하는 API 호출을 새로운 독립형 새 이름을 사용하도록 코드를 이전할 수 있을 때까지 사용할 수 있습니다 Android용 Places SDK의 각 버전에 대해 버전 1.0에서 버전 2.6.0까지 출시되었으며, 이제 동등한 기능을 제공하기 위해 장소 호환성 라이브러리의 기능을 제공합니다

장소 호환성 라이브러리 고정 및 지원 중단

모든 버전의 Android용 Places SDK 호환성 라이브러리 2022년 3월 31일부터 지원이 중단되었습니다. 버전 2.6.0은 장소 호환성 라이브러리. 지역 정보 기능 및 버그 수정을 위한 유일한 방법 Android용 SDK 버전 2.6.0 이상에서 Android용 Places SDK를 사용하게 됩니다.

Android용 Places SDK로 이전하는 것이 좋습니다. 버전 2.6.0 이상의 새 기능 및 중요한 버그 수정을 이용하시기 바랍니다. 현재 호환성 라이브러리를 사용 중인 경우 아래 단계를 따르세요. Android용 Places SDK 설치 섹션으로 이전 Android용 Places SDK로 이전되었습니다.

클라이언트 라이브러리 설치

Android용 Places SDK의 새 버전은 정적 클라이언트 라이브러리를 사용합니다.

Maven을 사용하여 Android용 Places SDK를 Android 스튜디오 프로젝트에 추가합니다.

  1. 현재 장소 호환성 라이브러리를 사용 중인 경우:

    1. dependencies 섹션에서 다음 줄을 바꿉니다.

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

      다음 줄을 사용하여 Android용 Places SDK로 전환합니다.

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

  2. 현재 Android용 Places SDK의 Play 서비스 버전을 사용 중인 경우:

    1. dependencies 섹션에서 다음 줄을 바꿉니다.

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

      다음 줄을 사용하여 Android용 Places SDK로 전환합니다.

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

  3. Gradle 프로젝트를 동기화합니다.

  4. 애플리케이션 프로젝트의 minSdkVersion16 이상으로 설정합니다.

  5. '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. 앱을 빌드합니다. Google.com으로의 변환으로 인해 Android용 Places SDK의 경우 아래 섹션에서 자세한 내용을 확인하세요. 도움이 될 것입니다

새 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 키가 잘못되었습니다.
    • Cloud 콘솔에서 Places API가 사용 설정되지 않았습니다.
    • 잘못된 키 제한이 포함된 API 키가 제공되었습니다.
  • INVALID_REQUEST - 누락되거나 잘못되어 요청이 유효하지 않음 인수입니다.

  • NOT_FOUND — 지정된 요청에 대한 결과를 찾을 수 없습니다.

새 메서드

Android용 Places SDK의 새 버전에 두 가지 방법이 있습니다. 모든 새 메서드 다음을 준수해야 합니다.

  • Endpoints는 더 이상 get 동사를 사용하지 않습니다.
  • 요청 및 응답 객체는 해당 객체와 클라이언트 메서드를 사용합니다.
  • 이제 요청 객체에 빌더가 있습니다. 필수 매개변수가 요청으로 전달됨 빌더 매개변수를 포함해야 합니다.
  • 버퍼는 더 이상 사용되지 않습니다.

이 섹션에서는 새로운 메서드를 소개하고 그 작동 방식을 보여줍니다.

ID로 장소 가져오기

fetchPlace() 사용 특정 장소에 대한 세부정보를 가져올 수 있습니다. fetchPlace()는 다음과 유사하게 작동합니다. getPlaceById()

장소를 가져오려면 다음 단계를 따르세요.

  1. fetchPlace()를 호출하여 장소를 지정하는 FetchPlaceRequest 객체 전달 반환할 장소 데이터를 지정하는 ID 및 필드의 목록입니다.

    // 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 객체에서 직접 가져옵니다. 더 이상 별도의 요청이 필요하지 않습니다. 사진의 최대 너비 또는 높이는 1,600픽셀입니다. 함수 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 그런 다음 결과 사진 메타데이터를 사용하여 비트맵과 속성 텍스트를 가져옵니다.

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

세션 토큰

세션 토큰은 사용자 검색의 쿼리 및 선택 단계를 별도의 세션을 만들 수 없습니다. 모든 자동 완성 세션에 세션 토큰을 사용하는 것이 좋습니다. 사용자가 쿼리를 실행하고, 사용자가 장소를 선택하면 종료됩니다. 각 세션은 여러 개의 쿼리하고 1개의 장소를 선택합니다 세션이 종료되면 토큰이 더 이상 유효하지 않습니다. 앱에서 각 포드에 대해 세션입니다.

필드 마스크

장소 세부정보를 반환하는 메서드에서 반환합니다. 이렇게 하면 비용을 지불할 것입니다.

반환할 데이터 유형을 지정하려면 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
를 통해 개인정보처리방침을 정의할 수 있습니다.

Places Data SKU에 대해 자세히 알아보세요.

장소 선택 도구 및 자동 완성 업데이트

이 섹션에서는 장소 위젯 (장소 선택 도구 및 자동 완성).

프로그래매틱 자동 완성

자동 완성이 다음과 같이 변경되었습니다.

  • PlaceAutocomplete에서 Autocomplete로 이름이 변경되었습니다.
    • PlaceAutocomplete.getPlace에서 Autocomplete.getPlaceFromIntent로 이름이 변경되었습니다.
    • PlaceAutocomplete.getStatus에서 Autocomplete.getStatusFromIntent로 이름이 변경되었습니다.
  • PlaceAutocomplete.RESULT_ERROR에서 AutocompleteActivity.RESULT_ERROR로 이름이 변경되었습니다. (자동 완성 프래그먼트에 대한 오류 처리는 변경되지 않았습니다.)

장소 선택기

장소 선택 도구는 2019년 1월 29일에 지원 중단되었습니다. 사용 중지됨 2019년 7월 29일에 종료되었으며 더 이상 사용할 수 없습니다. 계속 사용하면 오류 메시지가 표시됩니다. 새 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);
        }
    });
    

인텐트를 사용하여 자동 완성 활동 실행

  1. 앱 컨텍스트 및 API 키를 전달하여 Places를 초기화합니다.
  2. Autocomplete.IntentBuilder를 사용하여 인텐트를 만들고 원하는 PlaceAutocomplete 모드 (전체 화면 또는 오버레이) 인텐트는 startActivityForResult: 객체를 식별하는 요청 코드를 인텐트를 지정할 수 있습니다.
  3. 선택한 장소를 수신하도록 onActivityResult 콜백을 재정의합니다.

다음 예는 인텐트를 사용하여 자동 완성을 실행하는 방법을 보여줍니다. 그런 다음 결과를 처리합니다.

    /**
     * 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.
            }
        }
    }

장소 선택 도구를 더 이상 사용할 수 없음

장소 선택 도구는 2019년 1월 29일에 지원 중단되었습니다. 사용 중지됨 2019년 7월 29일에 종료되었으며 더 이상 사용할 수 없습니다. 계속 사용하면 오류 메시지가 표시됩니다. 새 SDK는 장소 선택 도구를 지원하지 않습니다.