选择 SDK 版本

Places SDK for Android 版本 3.4.0 支持两个 SDK 版本：Places SDK for Android 是现有的 SDK，Places SDK for Android（新）是新一代 SDK 版本。

注意 ：此版本中包含的所有新功能都是 Places SDK for Android（新）的一部分，Places SDK for Android 中不提供。

随着 Places SDK for Android 3.4.0 版本的发布，您的第一个任务是决定要使用的 SDK。如果您是新客户或已在使用 SDK 的现有客户，则出现这种情况。您可以通过本指南了解这两种 SDK 之间的主要区别。

如何选择 SDK 版本

在后端，Places SDK for Android 依赖于 Places API 服务，即 Places API（新）或 Places API。您必须先在 Google Cloud 项目中启用 Places API 服务，然后才能使用 Places SDK for Android。

对于 Android，您可以通过以下两项操作来确定可以在应用中使用哪些 API：

1. 在项目中，您必须对 API 密钥启用 Places API（新）或 Places API，或同时启用两者，具体取决于您打算在应用中使用哪个 API。

2. 通过调用 Places.initializeWithNewPlacesApiEnabled() 或 Places.initialize() 方法来初始化您的应用。

选择您的 SDK

您启用的 Places API 服务版本会控制应用使用的 SDK 版本：

• 两者：为 Places SDK for Android 和 Places SDK for Android（新）启用所有功能。使用 Places.initializeWithNewPlacesApiEnabled() 和 Places.initialize() 方法控制可用功能。

• Places API：启用现有的 Places SDK for Android。您无权访问 Places SDK for Android 3.4.0 版本中添加的新功能。

• Places API（新）：启用 Places SDK for Android（新）以及新增 Places SDK for Android 的主要功能（新）中所述的所有新功能，但不启用当前地点和地点自动补全等现有功能。

如需详细了解如何选择 Places API 服务，请参阅设置您的 Google Cloud 项目。

初始化您的应用

初始化应用时，您必须调用 Places.initializeWithNewPlacesApiEnabled() 或 Places.initialize() 方法。

下表显示了启用每个 SDK 并调用每个初始化方法后的效果。例如，如果您启用了 Places SDK（新）并调用 Places.initializeWithNewPlacesApiEnabled()，则可以使用所有新 API 和所有现有 API。

如果您启用了 Places SDK（新）并调用 Places.initialize()，则无法使用地点详情和地点照片的新功能，但可以调用新的文本搜索。如果您未启用 Places API，则无法访问旧版地点详情，但仍然可以调用新版“文本搜索”。

版本	API	已为 API 密钥启用 SDK		初始化方法
		Places API	Places API（新）	initialize()	initializeWithNewPlacesApiEnabled()
v3.3.0	地点详情
	地点详情（新）
	照片元数据（新）
	文本搜索（新）			任一方法
v3.4.0	照片 URI（新）
	照片位图			任一方法
	CurrentPlace			任一方法
	自动补全			任一方法

您应选择哪种 SDK？

为帮助您决定选择哪个版本，请按以下步骤操作：

1. 如果您是刚刚开始使用 Places SDK for Android 的新客户，请先了解 Places API（新）和新 SDK。

2. 如果您是 Kotlin 开发者，可以使用 SDK，但 Places SDK for Android（新）中的新功能仅在 3.4.0 版中以 Java 提供。

3. 如果您是现有客户并且正在使用会话令牌，请继续使用现有 SDK。Places SDK for Android（新）目前不支持会话令牌。

4. 如果您是现有客户，可以继续使用现有 SDK。不过，为了充分利用 Places SDK for Android（新）的性能提升和功能增强，您可以使用新版 SDK。

   迁移到新 SDK 时无需进行迁移。您只需执行以下操作：

   1. 对应用中使用的 API 密钥启用 Places API（新）。如需了解详情，请参阅使用 API 密钥。

   2. 在模块级 build.gradle 文件的 dependencies 部分中，更新 places 依赖项并添加 kotlin-bom 依赖项：

        dependencies {
            implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
            implementation 'com.google.android.libraries.places:places:3.3.0'
        }

      如需详细了解 kotlin-bom 依赖项，请参阅在传递依赖项中使用最新的 kotlin-stdlib 版本。

   3. 更新现有应用，调用新的 Places.initializeWithNewPlacesApiEnabled() 方法来初始化您的应用。如需了解详情，请参阅初始化 Places API 客户端。

   现有应用仍可继续使用，但您现在可以充分利用所有新的 SDK 功能。

添加到 Places SDK for Android 的主要功能（新）

本部分将介绍 Places SDK for Android 中添加的主要功能（新）。

在 Google Cloud 标准平台上实现

Places SDK for Android（新）在 Google Cloud 上的服务基础架构上实现。此实现带来了更安全、更值得信赖的平台。这种标准设计使所有 SDK 都能实现一定程度的一致性，从而提高 Places SDK for Android（新）的开发效率。

性能改进

Places SDK for Android（新）改进了性能，因此值得替换使用现有 SDK 的应用。

新的“文本搜索”服务

文本搜索会根据一个字符串返回一组地点的相关信息，例如“北京烤鸭”“南京附近的鞋店”或“长安街 123 号”。该服务会返回一个与文本字符串和任何位置偏向设置相匹配的地点列表。

向“地点详情”和“地点照片”中添加了新的响应数据

• 地点详情现在在响应 Place 对象中添加了新的 Review 类。Place 类包含支持此字段的新 getReviews() 方法。调用 getReviews() 可返回针对某个地点最多五条评价。

• Place Photo 将 AuthorAttributions 添加到 PhotoMetadata 类。AuthorAttributions 包含 AuthorAttribution 对象的 List。

向地点照片添加了新的 URI 响应

您现在可以使用地点照片返回图片位图的 URI。以前，您只能返回图像位图本身。

简化的价格方案

Places SDK for Android（新）的定价得到了简化，您只需为实际使用的数据量付费。简化的价格是通过字段列表（也称为字段掩码）实现的。

通过“地点详情”和“文本搜索”，您可以使用字段列表来控制要在响应中返回的字段列表。然后，您只需为请求的数据付费。使用字段列表是一种很好的设计做法，可确保您不会请求不必要的数据，这有助于避免不必要的处理时间和结算费用。

如需详细了解这两种 SDK 的价格信息，请参阅用量和结算。

注意 ：新的价格模式仅适用于地点详情、文本搜索和地点照片。这两种 SDK 的地点自动补全和当前地点的价格相同。

扩展的地点类型

新 SDK 添加了下表中显示的地点类型。这些类型会在“地点详情”和“文本搜索”响应中返回。您还可以在使用“文本搜索”功能的搜索中使用这些新类型和现有类型。表 A 中包含新类型。

类型
american_restaurant	discount_store	ice_cream_shop	sandwich_shop
amusement_center	dog_park	indian_restaurant	school_district
athletic_field	electric_vehicle_charging_station	indonesian_restaurant	seafood_restaurant
auto_parts_store	event_venue	italian_restaurant	ski_resort
banquet_hall	extended_stay_hotel	japanese_restaurant	spanish_restaurant
barbecue_restaurant	农场	korean_restaurant	sporting_goods_store
barber_shop	农庄	lebanese_restaurant	sports_club
bed_and_breakfast	fast_food_restaurant	Marina	sports_complex
brazilian_restaurant	ferry_terminal	市场	steak_house
breakfast_restaurant	fitness_center	medical_lab	sushi_restaurant
brunch_restaurant	french_restaurant	mediterranean_restaurant	swimming_pool
bus_stop	gift_shop	mexican_restaurant	定制
camping_cabin	golf_course	middle_eastern_restaurant	telecommunications_service_provider
cell_phone_store	greek_restaurant	汽车旅店	thai_restaurant
child_care_agency	grocery_store	national_park	transit_depot
chinese_restaurant	guest_house	park_and_ride	truck_stop
coffee_shop	hair_salon	performing_arts_theater	turkish_restaurant
community_center	hamburger_restaurant	pizza_restaurant	vegan_restaurant
顾问	直升飞机场	playground	vegetarian_restaurant
convention_center	hiking_area	学龄前儿童	vietnamese_restaurant
村舍	historical_landmark	private_guest_room	visitor_center
courier_service	home_improvement_store	ramen_restaurant	wedding_venue
cultural_center	招待所	resort_hotel	批发商
dental_clinic	hotel	rest_stop

除了这些新类型之外，Places API（新）也从表 A 中的表 B 中移除了以下类型。这意味着，您现在可以在搜索中使用以下类型：

• country
• administrative_area_level_1
• administrative_area_level_2
• postal_code
• locality