迁移到新的 Places SDK 客户端

本指南介绍了地点兼容性库与新独立版 Places SDK for Android 之间的变化。如果您一直在使用地点兼容性库,而不是迁移到新的独立版 Places SDK for Android,请参阅本指南,了解如何更新项目以使用新版 Places SDK for Android。

届时,您只能使用 Places SDK for Android 来访问 Places SDK for Android 2.6.0 以上版本的功能和 bug 修复。Google 建议尽快从兼容性库更新到新的 Places SDK for Android 版本。

发生了哪些变化?

主要的变更如下:

  • 新版 Places SDK for Android 以静态客户端库的形式分发。在 2019 年 1 月之前,Places SDK for Android 是通过 Google Play 服务提供的。自那以后,我们提供了地点兼容性库,以简化向新的 Places SDK for Android 过渡。
  • 其中包括全新方法
  • 返回地点详情的方法现在支持字段掩码。您可以使用字段掩码指定要返回的地点数据类型。
  • 改进了用于报告错误的状态代码
  • 自动补全现在支持会话令牌
  • 地点选择器已不再可用

地点兼容性库简介

2019 年 1 月,随着独立 Places SDK for Android 1.0 版发布,Google 提供了一个兼容性库,以帮助从已停用的 Google Play 服务版 Places SDK for Android (com.google.android.gms:play-services-places) 进行迁移。

我们暂时提供此兼容性库,用于将面向 Google Play 服务版本的 API 调用重定向并转换为新的独立版本,直到开发者能够迁移其代码以使用独立 SDK 中的新名称为止。对于 1.0 到 2.6.0 版中的每个 Places SDK for Android 版本,我们发布了相应的地点兼容性库版本,以提供等效功能。

冻结和弃用地点兼容性库

自 2022 年 3 月 31 日起,适用于 Places SDK for Android 的所有版本的兼容性库都将被弃用。版本 2.6.0 是地点兼容性库的最后一个版本。届时,您只能使用 Places SDK for Android 来访问 Places SDK for Android 2.6.0 以上版本的功能和 bug 修复。

Google 建议您迁移到 Places SDK for Android,以便使用 2.6.0 以上版本的新功能和重要 bug 修复。如果您目前正在使用兼容性库,请按照安装 Places SDK for Android 部分中的步骤迁移到 Places SDK for Android。

安装客户端库

新版 Places SDK for Android 以静态客户端库的形式分发。

使用 Maven 将 Places SDK for Android 添加到您的 Android Studio 项目中:

  1. 如果您当前正在使用地点兼容性库

    1. 替换 dependencies 部分中的以下行:

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

      使用以下代码切换到 Places SDK for Android:

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

  2. 如果您目前使用的是 Play 服务版 Places SDK for Android

    1. 替换 dependencies 部分中的以下行:

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

      使用以下代码切换到 Places SDK for Android:

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

  3. 同步您的 Gradle 项目。

  4. 将应用项目的 minSdkVersion 设置为 16 或更高版本。

  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. 构建应用。如果您看到因转换为 Places SDK for 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 密钥无效。
    • 尚未在 Cloud 控制台中启用 Places API。
    • 提供的 API 密钥具有错误的密钥限制。
  • INVALID_REQUEST - 表示由于参数缺失或无效,请求无效。

  • NOT_FOUND - 表示未找到与给定请求对应的结果。

新方法

新版 Places SDK for Android 引入了全新的方法,这些方法旨在实现一致性。所有新方法均符合以下要求:

  • 端点不再使用 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() 会返回地点的照片。已简化请求照片的模式。您现在可以直接从 Place 对象请求 PhotoMetadata;不再需要单独的请求。照片的宽度或高度上限为 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 以从 FetchPlaceResponse 中生成的 Place 获取照片元数据,然后使用生成的照片元数据获取位图和提供方说明文本:

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

会话令牌

会话令牌将用户搜索的查询和选择阶段划分到独立的会话中,以便进行结算。我们建议您针对所有自动补全会话使用会话令牌。会话在用户开始输入查询内容时开始,并在用户选择地点时结束。在每个会话中,用户可以进行多项查询,并最终选择一个地点。会话结束后,令牌将失效;您的应用必须为每个会话生成一个新的令牌。

字段掩码

在返回地点详情的方法中,您必须指定要随每个请求返回的地点数据类型。这有助于确保您只请求实际使用的数据(并为之付费)。

如需指定要返回的数据类型,请在 FetchPlaceRequest 中传递 Place.Field 的数组,如以下示例所示:

// 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

详细了解地点数据 SKU

地点选取器和自动补全功能更新

本部分介绍了对地点 widget(地点选择器和自动补全)的更改。

程序化自动补全

自动补全功能做出了以下更改:

  • PlaceAutocomplete 已重命名为 Autocomplete
    • 已将 PlaceAutocomplete.getPlace 重命名为 Autocomplete.getPlaceFromIntent
    • 已将 PlaceAutocomplete.getStatus 重命名为 Autocomplete.getStatusFromIntent
  • PlaceAutocomplete.RESULT_ERROR 已重命名为 AutocompleteActivity.RESULT_ERROR(自动补全 fragment 的错误处理未更改)。

地点选取器

地点选取器已于 2019 年 1 月 29 日弃用。此功能已于 2019 年 7 月 29 日停用,不再提供。继续使用将导致错误消息。新 SDK 不支持地点选取器。

自动补全 widget

自动补全 widget 已更新:

  • Place 前缀已从所有类中移除。
  • 添加了对会话令牌的支持。该 widget 会在后台自动为您管理令牌。
  • 添加了对字段掩码的支持,可让您选择在用户做出选择后返回哪些类型的地点数据。

以下各部分介绍了如何向您的项目添加 Autocomplete widget。

嵌入 AutocompleteFragment

如需添加自动补全 fragment,请按以下步骤操作:

  1. 向 activity 的 XML 布局添加一个 fragment,如以下示例所示。

    <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. 如需向 activity 添加自动补全 widget,请按以下步骤操作:

    • 初始化 Places,并传递应用上下文和您的 API 密钥。
    • 初始化 AutocompleteSupportFragment
    • 调用 setPlaceFields() 以指示要获取的地点数据类型。
    • 添加 PlaceSelectionListener 以便对结果执行某些操作,并处理可能出现的任何错误。

    下例展示了如何向 activity 添加自动补全 widget:

    /**
     * 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 启动自动补全 activity

  1. 初始化 Places,并传递应用上下文和您的 API 密钥
  2. 使用 Autocomplete.IntentBuilder 创建一个 intent,并传递所需的 PlaceAutocomplete 模式(全屏或叠加)。该 intent 必须调用 startActivityForResult,并传入用于标识您的 intent 的请求代码。
  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.
            }
        }
    }

地点选取器已无法使用

地点选取器已于 2019 年 1 月 29 日弃用。此功能已于 2019 年 7 月 29 日停用,不再提供。继续使用将导致错误消息。新 SDK 不支持地点选取器。