遷移至 Places Swift SDK for iOS (預先發布版)

從 Places SDK for iOS 遷移至 Places Swift SDK for iOS (預先發布版) 應該很簡單，而且可以逐步完成。由於 iOS 版 Places Swift SDK (預先發布版) 中的結構體與 Objective-C 版的結構體不相容，因此建議您根據 GMSPlacesClient 中 API 的用途，遷移個別功能區塊。

將 Places Swift SDK for iOS (預先發布版) 新增至專案

如要使用 Places Swift SDK for iOS (預先發布版)，請按照下列步驟操作：

  1. 啟用 Places API (新版)。

  2. 將 Places Swift SDK for iOS (預先發布版) 新增至依附元件。您可以選擇安裝 GooglePlaces、GooglePlacesSwift，或同時安裝兩者。

  3. 使用 PlacesClient 初始化 Places 用戶端。

逐步遷移範例

舉例來說，假設使用 Places SDK for iOS 的應用程式會根據文字輸入內容接收自動完成建議，然後擷取第一個地點建議的詳細資料。使用 Places SDK for iOS 時，現有的程式碼可能會如下所示：

// Initialize Places Client.
GMSPlacesClient.provideAPIKey(apiKey)
let client = GMSPlacesClient.shared()

// Fetch Autocomplete Request.
let center = CLLocation(latitude: 37.3913916, longitude: -122.0879074)
let northEast = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWest = CLLocationCoordinate2DMake(37.395804, -122.077023)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.origin = center
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest)

let request = GMSAutocompleteRequest(query: "Sicilian piz")
request.filter = filter

client.fetchAutocompleteSuggestions(from: request) { (results, error) in
  guard let results, error == nil else {
    print("Autocomplete error: \(String(describing: error))")
    return
  }

  // Fetch Place Request.
  guard let placeID = results.first?.placeSuggestion?.placeID else { return }
  let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

  let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

  client.fetchPlace(with: fetchPlaceRequest) { (place: GMSPlace?, error: Error?) in
    guard let place, error == nil else { return }
    print("Place found: \(String(describing: place.name)); \(String(describing: place.website))")
  }
}

更新 Places 用戶端初始化工具

如要將程式碼改為新版，並善用新 SDK 的功能，您必須將 GMSPlacesClient 取代為 PlacesClient。此外，新方法中的參數名稱已變更，因此您必須將參數更新為 from，而非 with。最後，iOS 版 Places Swift SDK (預先發布版) 會使用升級版 AutocompleteRequest。

更新後的程式碼

// Initialize Places Swift Client.
let _ = PlacesClient.provideAPIKey(apiKey)
let placesSwiftClient = PlacesClient.shared

原始程式碼

// Initialize Places Client.
GMSPlacesClient.provideAPIKey(apiKey)
let client = GMSPlacesClient.shared()

更新自動完成要求

您可以先更新自動完成要求流程。舊程式碼會使用回呼來要求自動完成建議，而新程式碼則會採用 switch/await 模式。回呼可能會讓程式碼結構和錯誤處理變得更複雜。新的 iOS 適用 Places Swift SDK (預先發布版) 支援並行作業，可簡化非同步作業。

// Initialize Places Swift Client.
let _ = PlacesClient.provideAPIKey(apiKey)
let placesSwiftClient = PlacesClient.shared

// Fetch Autocomplete Request.
let center = CLLocation(latitude: 37.3913916, longitude: -122.0879074)
let northEast = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWest = CLLocationCoordinate2DMake(37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
let placeID: String
switch await placesSwiftClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let results):
  switch results.first {
  case .place(let placeSuggestion):
    placeID = placeSuggestion.placeID
  case .none:
    fallthrough
  @unknown default:
    return
  }
case .failure(let placesError):
  print("Autocomplete error: \(placesError)")
  return
}

// Initialize Places Client.
GMSPlacesClient.provideAPIKey(apiKey)
let placesClient = GMSPlacesClient.shared()

// Fetch Place Request.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

placesClient.fetchPlace(with: fetchPlaceRequest) { (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name)); \(String(describing: place.website))")
}

更新方法和類別名稱

最後，請重構 fetchPlace 程式碼並移除 GMSPlacesClient 初始化和 GMSPlaceProperty 宣告，完成遷移作業。在 Places Swift SDK for iOS (預先發布版) 中，方法和類別名稱已更新為移除「GMS」前置字串，因此您必須相應更新，例如：GMSFetchPlaceRequest 會變成 FetchPlaceRequest。

類型處理

新的 fetchPlace 方法採用了改良的類型處理方式。舊版程式碼需要傳遞屬性的原始值，但新版程式碼則不需要開發人員在此明確擷取原始值，因此可提升簡潔性和可讀性。

並行

此外，新方法支援並行處理，可在 placesSwiftClient.fetchPlace 中將 placesClient.fetchPlace 中的回呼取代為 switch/await 模式。

// Initialize Places Swift Client.
let _ = PlacesClient.provideAPIKey(apiKey)
let placesSwiftClient = PlacesClient.shared

// Fetch Autocomplete Request.
let center = CLLocation(latitude: 37.3913916, longitude: -122.0879074)
let northEast = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWest = CLLocationCoordinate2DMake(37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
let placeID: String
switch await placesSwiftClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let results):
  switch results.first {
  case .place(let placeSuggestion):
    placeID = placeSuggestion.placeID
  case .none:
    fallthrough
  @unknown default:
    return
  }
case .failure(let placesError):
  print("Autocomplete error: \(placesError)")
  return
}

// Fetch Place Request.
let fetchPlaceRequest = FetchPlaceRequest(placeID: placeID, placeProperties: [.displayName, .websiteURL])
switch await placesSwiftClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  print("Place found: \(place.displayName): \(String(describing: place.description))")

case .failure(let placesError):
  print("Place not found: \(placeID); \(placesError)")
}

跟上最新趨勢

請參閱 Places Swift SDK for iOS (預先發布版) 的版本資訊頁面，瞭解新功能和變更。