Place Autocomplete

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.
Selecione a plataforma: Android iOS JavaScript Serviço da Web

O serviço de preenchimento automático no SDK do Places para iOS retorna previsões de locais em resposta a consultas de pesquisa dos usuários. À medida que o usuário digita, o serviço de preenchimento automático retorna sugestões de lugares, como empresas, endereços, códigos extras e pontos de interesse.

É possível adicionar o preenchimento automático no aplicativo das seguintes formas:

Adicionar um controle de IU de preenchimento automático

O controle de IU de preenchimento automático é uma caixa de diálogo de pesquisa com a funcionalidade integrada de preenchimento automático. Conforme o usuário digita termos de pesquisa, o controle apresenta uma lista de locais previstos para escolha. Quando o usuário faz uma seleção, uma instância GMSPlace é retornada, e o app pode usá-la para ver detalhes sobre o local selecionado.

É possível adicionar o widget de preenchimento automático do seu aplicativo das seguintes formas:

Como adicionar um controle de tela cheia

Use o controle de tela cheia quando quiser um contexto modal, em que a IU de preenchimento automático substitui temporariamente a IU do app até que o usuário faça a seleção. Essa funcionalidade é fornecida pela classe GMSAutocompleteViewController. Quando o usuário seleciona um local, o aplicativo recebe um retorno de chamada.

Para adicionar um widget de tela cheia ao aplicativo:

  1. Crie um elemento de IU no app principal para iniciar o controle de IU de preenchimento automático, por exemplo, um gerenciador de toque em uma UIButton.
  2. Implemente o protocolo GMSAutocompleteViewControllerDelegate no controlador de visualização pai.
  3. Crie uma instância do GMSAutocompleteViewController e atribua o controlador de visualização pai como a propriedade delegada.
  4. Crie um GMSPlaceField para definir os tipos de dados de lugar a serem retornados.
  5. Adicione um GMSAutocompleteFilter para restringir a consulta a um tipo específico de lugar.
  6. Apresente o GMSAutocompleteViewController usando [self presentViewController...].
  7. Gerencie a seleção do usuário no método delegado didAutocompleteWithPlace.
  8. Dispense o controlador nos métodos delegados didAutocompleteWithPlace, didFailAutocompleteWithError e wasCancelled.

O exemplo a seguir demonstra uma possível maneira de iniciar GMSAutocompleteViewController em resposta ao toque de um usuário em um botão.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  override func viewDidLoad() {
    makeButton()
  }

  // Present the Autocomplete view controller when the button is pressed.
  @objc func autocompleteClicked(_ sender: UIButton) {
    let autocompleteController = GMSAutocompleteViewController()
    autocompleteController.delegate = self

    // Specify the place data types to return.
    let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) |
      UInt(GMSPlaceField.placeID.rawValue))!
    autocompleteController.placeFields = fields

    // Specify a filter.
    let filter = GMSAutocompleteFilter()
    filter.types = [.address]
    autocompleteController.autocompleteFilter = filter

    // Display the autocomplete view controller.
    present(autocompleteController, animated: true, completion: nil)
  }

  // Add a button to the view.
  func makeButton() {
    let btnLaunchAc = UIButton(frame: CGRect(x: 5, y: 150, width: 300, height: 35))
    btnLaunchAc.backgroundColor = .blue
    btnLaunchAc.setTitle("Launch autocomplete", for: .normal)
    btnLaunchAc.addTarget(self, action: #selector(autocompleteClicked), for: .touchUpInside)
    self.view.addSubview(btnLaunchAc)
  }

}

extension ViewController: GMSAutocompleteViewControllerDelegate {

  // Handle the user's selection.
  func viewController(_ viewController: GMSAutocompleteViewController, didAutocompleteWith place: GMSPlace) {
    print("Place name: \(place.name)")
    print("Place ID: \(place.placeID)")
    print("Place attributions: \(place.attributions)")
    dismiss(animated: true, completion: nil)
  }

  func viewController(_ viewController: GMSAutocompleteViewController, didFailAutocompleteWithError error: Error) {
    // TODO: handle the error.
    print("Error: ", error.localizedDescription)
  }

  // User canceled the operation.
  func wasCancelled(_ viewController: GMSAutocompleteViewController) {
    dismiss(animated: true, completion: nil)
  }

  // Turn the network activity indicator on and off again.
  func didRequestAutocompletePredictions(_ viewController: GMSAutocompleteViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
  }

  func didUpdateAutocompletePredictions(_ viewController: GMSAutocompleteViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
  }

}

Objective-C

#import "ViewController.h"
@import GooglePlaces;

@interface ViewController () <GMSAutocompleteViewControllerDelegate>

@end

@implementation ViewController {
  GMSAutocompleteFilter *_filter;
}

- (void)viewDidLoad {
  [super viewDidLoad];
  [self makeButton];
}

  // Present the autocomplete view controller when the button is pressed.
- (void)autocompleteClicked {
  GMSAutocompleteViewController *acController = [[GMSAutocompleteViewController alloc] init];
  acController.delegate = self;

  // Specify the place data types to return.
  GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
  acController.placeFields = fields;

  // Specify a filter.
  _filter = [[GMSAutocompleteFilter alloc] init];
  _filter.types = @[ kGMSPlaceTypeBank ];
  acController.autocompleteFilter = _filter;

  // Display the autocomplete view controller.
  [self presentViewController:acController animated:YES completion:nil];
}

  // Add a button to the view.
- (void)makeButton{
  UIButton *btnLaunchAc = [UIButton buttonWithType:UIButtonTypeCustom];
  [btnLaunchAc addTarget:self
             action:NSSelectorFromString(@"autocompleteClicked") forControlEvents:UIControlEventTouchUpInside];
  [btnLaunchAc setTitle:@"Launch autocomplete" forState:UIControlStateNormal];
  btnLaunchAc.frame = CGRectMake(5.0, 150.0, 300.0, 35.0);
  btnLaunchAc.backgroundColor = [UIColor blueColor];
  [self.view addSubview:btnLaunchAc];
}

  // Handle the user's selection.
- (void)viewController:(GMSAutocompleteViewController *)viewController
didAutocompleteWithPlace:(GMSPlace *)place {
  [self dismissViewControllerAnimated:YES completion:nil];
  // Do something with the selected place.
  NSLog(@"Place name %@", place.name);
  NSLog(@"Place ID %@", place.placeID);
  NSLog(@"Place attributions %@", place.attributions.string);
}

- (void)viewController:(GMSAutocompleteViewController *)viewController
didFailAutocompleteWithError:(NSError *)error {
  [self dismissViewControllerAnimated:YES completion:nil];
  // TODO: handle the error.
  NSLog(@"Error: %@", [error description]);
}

  // User canceled the operation.
- (void)wasCancelled:(GMSAutocompleteViewController *)viewController {
  [self dismissViewControllerAnimated:YES completion:nil];
}

  // Turn the network activity indicator on and off again.
- (void)didRequestAutocompletePredictions:(GMSAutocompleteViewController *)viewController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
}

- (void)didUpdateAutocompletePredictions:(GMSAutocompleteViewController *)viewController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;
}

@end

Como adicionar um controlador de resultados

Use um controlador de resultados quando quiser ter mais controle sobre a IU de inserção de texto. O controlador de resultados alterna dinamicamente a visibilidade da lista de resultados com base no foco da IU de entrada.

Para adicionar um controlador de resultados ao aplicativo:

  1. Crie um GMSAutocompleteResultsViewController.
  2. Implemente o protocolo GMSAutocompleteResultsViewControllerDelegate no controlador de visualização pai e atribua o controlador como a propriedade delegada.
  3. Crie um objeto UISearchController, transmitindo o GMSAutocompleteResultsViewController como argumento do controlador de resultados.
  4. Defina GMSAutocompleteResultsViewController como a propriedade searchResultsUpdater do UISearchController.
  5. Adicione a searchBar do UISearchController à IU do app.
  6. Gerencie a seleção do usuário no método delegado didAutocompleteWithPlace.

Há várias maneiras de colocar a barra de pesquisa de um UISearchController na IU do app:

Adicionar uma barra de pesquisa à barra de navegação

O exemplo de código a seguir demonstra a adição de um controlador de resultados, a adição de searchBar à barra de navegação e o gerenciamento da seleção do usuário:

Swift

class ViewController: UIViewController {

  var resultsViewController: GMSAutocompleteResultsViewController?
  var searchController: UISearchController?
  var resultView: UITextView?

  override func viewDidLoad() {
    super.viewDidLoad()

    resultsViewController = GMSAutocompleteResultsViewController()
    resultsViewController?.delegate = self

    searchController = UISearchController(searchResultsController: resultsViewController)
    searchController?.searchResultsUpdater = resultsViewController

    // Put the search bar in the navigation bar.
    searchController?.searchBar.sizeToFit()
    navigationItem.titleView = searchController?.searchBar

    // When UISearchController presents the results view, present it in
    // this view controller, not one further up the chain.
    definesPresentationContext = true

    // Prevent the navigation bar from being hidden when searching.
    searchController?.hidesNavigationBarDuringPresentation = false
  }
}

// Handle the user's selection.
extension ViewController: GMSAutocompleteResultsViewControllerDelegate {
  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didAutocompleteWith place: GMSPlace) {
    searchController?.isActive = false
    // Do something with the selected place.
    print("Place name: \(place.name)")
    print("Place address: \(place.formattedAddress)")
    print("Place attributions: \(place.attributions)")
  }

  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didFailAutocompleteWithError error: Error){
    // TODO: handle the error.
    print("Error: ", error.localizedDescription)
  }

  // Turn the network activity indicator on and off again.
  func didRequestAutocompletePredictions(_ viewController: GMSAutocompleteViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
  }

  func didUpdateAutocompletePredictions(_ viewController: GMSAutocompleteViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
  }
}

Objective-C

- (void)viewDidLoad {
  _resultsViewController = [[GMSAutocompleteResultsViewController alloc] init];
  _resultsViewController.delegate = self;

  _searchController = [[UISearchController alloc]
                       initWithSearchResultsController:_resultsViewController];
  _searchController.searchResultsUpdater = _resultsViewController;

  // Put the search bar in the navigation bar.
  [_searchController.searchBar sizeToFit];
  self.navigationItem.titleView = _searchController.searchBar;

  // When UISearchController presents the results view, present it in
  // this view controller, not one further up the chain.
  self.definesPresentationContext = YES;

  // Prevent the navigation bar from being hidden when searching.
  _searchController.hidesNavigationBarDuringPresentation = NO;
}

// Handle the user's selection.
- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
  didAutocompleteWithPlace:(GMSPlace *)place {
    _searchController.active = NO;
    // Do something with the selected place.
    NSLog(@"Place name %@", place.name);
    NSLog(@"Place address %@", place.formattedAddress);
    NSLog(@"Place attributions %@", place.attributions.string);
}

- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didFailAutocompleteWithError:(NSError *)error {
  [self dismissViewControllerAnimated:YES completion:nil];
  // TODO: handle the error.
  NSLog(@"Error: %@", [error description]);
}

// Turn the network activity indicator on and off again.
- (void)didRequestAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
}

- (void)didUpdateAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;
}

Adicionar uma barra de pesquisa à parte superior de uma visualização

O exemplo de código a seguir mostra como adicionar searchBar à parte superior de uma visualização.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  var resultsViewController: GMSAutocompleteResultsViewController?
  var searchController: UISearchController?
  var resultView: UITextView?

  override func viewDidLoad() {
    super.viewDidLoad()

    resultsViewController = GMSAutocompleteResultsViewController()
    resultsViewController?.delegate = self

    searchController = UISearchController(searchResultsController: resultsViewController)
    searchController?.searchResultsUpdater = resultsViewController

    let subView = UIView(frame: CGRect(x: 0, y: 65.0, width: 350.0, height: 45.0))

    subView.addSubview((searchController?.searchBar)!)
    view.addSubview(subView)
    searchController?.searchBar.sizeToFit()
    searchController?.hidesNavigationBarDuringPresentation = false

    // When UISearchController presents the results view, present it in
    // this view controller, not one further up the chain.
    definesPresentationContext = true
  }
}

// Handle the user's selection.
extension ViewController: GMSAutocompleteResultsViewControllerDelegate {
  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didAutocompleteWith place: GMSPlace) {
    searchController?.isActive = false
    // Do something with the selected place.
    print("Place name: \(place.name)")
    print("Place address: \(place.formattedAddress)")
    print("Place attributions: \(place.attributions)")
  }

  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didFailAutocompleteWithError error: Error){
    // TODO: handle the error.
    print("Error: ", error.localizedDescription)
  }

  // Turn the network activity indicator on and off again.
  func didRequestAutocompletePredictions(forResultsController resultsController: GMSAutocompleteResultsViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
  }

  func didUpdateAutocompletePredictions(forResultsController resultsController: GMSAutocompleteResultsViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
  }
}

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];

    _resultsViewController = [[GMSAutocompleteResultsViewController alloc] init];
    _resultsViewController.delegate = self;

    _searchController = [[UISearchController alloc]
                             initWithSearchResultsController:_resultsViewController];
    _searchController.searchResultsUpdater = _resultsViewController;

    UIView *subView = [[UIView alloc] initWithFrame:CGRectMake(0, 65.0, 250, 50)];

    [subView addSubview:_searchController.searchBar];
    [_searchController.searchBar sizeToFit];
    [self.view addSubview:subView];

    // When UISearchController presents the results view, present it in
    // this view controller, not one further up the chain.
    self.definesPresentationContext = YES;
}

// Handle the user's selection.
- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didAutocompleteWithPlace:(GMSPlace *)place {
  [self dismissViewControllerAnimated:YES completion:nil];
  // Do something with the selected place.
  NSLog(@"Place name %@", place.name);
  NSLog(@"Place address %@", place.formattedAddress);
  NSLog(@"Place attributions %@", place.attributions.string);
}

- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didFailAutocompleteWithError:(NSError *)error {
  [self dismissViewControllerAnimated:YES completion:nil];
  // TODO: handle the error.
  NSLog(@"Error: %@", [error description]);
}

// Turn the network activity indicator on and off again.
- (void)didRequestAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
}

- (void)didUpdateAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;
}

Por padrão, o UISearchController oculta a barra de navegação durante a apresentação, o que pode ser desativado. Nos casos em que a barra de navegação fica visível e opaca, o UISearchController não define a posição corretamente.

Use o código a seguir como solução alternativa:

Swift

navigationController?.navigationBar.translucent = false
searchController?.hidesNavigationBarDuringPresentation = false

// This makes the view area include the nav bar even though it is opaque.
// Adjust the view placement down.
self.extendedLayoutIncludesOpaqueBars = true
self.edgesForExtendedLayout = .top

Objective-C

self.navigationController.navigationBar.translucent = NO;
_searchController.hidesNavigationBarDuringPresentation = NO;

// This makes the view area include the nav bar even though it is opaque.
// Adjust the view placement down.
self.extendedLayoutIncludesOpaqueBars = YES;
self.edgesForExtendedLayout = UIRectEdgeTop;

Como adicionar uma barra de pesquisa usando resultados pop-over

O exemplo de código a seguir mostra como colocar uma barra de pesquisa no lado direito da barra de navegação e exibir os resultados em um pop-up.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  var resultsViewController: GMSAutocompleteResultsViewController?
  var searchController: UISearchController?
  var resultView: UITextView?

  override func viewDidLoad() {
    super.viewDidLoad()

    resultsViewController = GMSAutocompleteResultsViewController()
    resultsViewController?.delegate = self

    searchController = UISearchController(searchResultsController: resultsViewController)
    searchController?.searchResultsUpdater = resultsViewController

    // Add the search bar to the right of the nav bar,
    // use a popover to display the results.
    // Set an explicit size as we don't want to use the entire nav bar.
    searchController?.searchBar.frame = (CGRect(x: 0, y: 0, width: 250.0, height: 44.0))
    navigationItem.rightBarButtonItem = UIBarButtonItem(customView: (searchController?.searchBar)!)

    // When UISearchController presents the results view, present it in
    // this view controller, not one further up the chain.
    definesPresentationContext = true

    // Keep the navigation bar visible.
    searchController?.hidesNavigationBarDuringPresentation = false
    searchController?.modalPresentationStyle = .popover
  }
}
// Handle the user's selection.
extension ViewController: GMSAutocompleteResultsViewControllerDelegate {
  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didAutocompleteWith place: GMSPlace) {
    searchController?.isActive = false
    // Do something with the selected place.
    print("Place name: \(place.name)")
    print("Place address: \(place.formattedAddress)")
    print("Place attributions: \(place.attributions)")
  }

  func resultsController(_ resultsController: GMSAutocompleteResultsViewController,
                         didFailAutocompleteWithError error: Error){
    // TODO: handle the error.
    print("Error: ", error.localizedDescription)
  }

  // Turn the network activity indicator on and off again.
  func didRequestAutocompletePredictions(forResultsController resultsController: GMSAutocompleteResultsViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
  }

  func didUpdateAutocompletePredictions(forResultsController resultsController: GMSAutocompleteResultsViewController) {
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
  }
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  _resultsViewController = [[GMSAutocompleteResultsViewController alloc] init];
  _resultsViewController.delegate = self;

  _searchController = [[UISearchController alloc]
                           initWithSearchResultsController:_resultsViewController];
  _searchController.searchResultsUpdater = _resultsViewController;

  // Add the search bar to the right of the nav bar,
  // use a popover to display the results.
  // Set an explicit size as we don't want to use the entire nav bar.
  _searchController.searchBar.frame = CGRectMake(0, 0, 250.0f, 44.0f);
  self.navigationItem.rightBarButtonItem =
  [[UIBarButtonItem alloc] initWithCustomView:_searchController.searchBar];

  // When UISearchController presents the results view, present it in
  // this view controller, not one further up the chain.
  self.definesPresentationContext = YES;

  // Keep the navigation bar visible.
  _searchController.hidesNavigationBarDuringPresentation = NO;

  _searchController.modalPresentationStyle = UIModalPresentationPopover;
}

// Handle the user's selection.
- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didAutocompleteWithPlace:(GMSPlace *)place {
  [self dismissViewControllerAnimated:YES completion:nil];
  NSLog(@"Place name %@", place.name);
  NSLog(@"Place address %@", place.formattedAddress);
  NSLog(@"Place attributions %@", place.attributions.string);
}

- (void)resultsController:(GMSAutocompleteResultsViewController *)resultsController
didFailAutocompleteWithError:(NSError *)error {
  [self dismissViewControllerAnimated:YES completion:nil];
  // TODO: handle the error.
  NSLog(@"Error: %@", [error description]);
}

// Turn the network activity indicator on and off again.
- (void)didRequestAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = YES;
}

- (void)didUpdateAutocompletePredictionsForResultsController:
    (GMSAutocompleteResultsViewController *)resultsController {
  [UIApplication sharedApplication].networkActivityIndicatorVisible = NO;
}

Usar uma fonte de dados de tabela

Caso seu app tenha uma IU de texto de pesquisa personalizada, use a classe GMSAutocompleteTableDataSource para gerar a visualização em tabela dos resultados no controlador de visualizações.

Para usar GMSAutocompleteTableDataSource como fonte de dados e delegado da UITableView em um controlador de visualização:

  1. Implemente os protocolos GMSAutocompleteTableDataSourceDelegate e UISearchBarDelegate no controlador de visualização.
  2. Crie uma instância GMSAutocompleteTableDataSource e atribua o controlador de visualização como a propriedade delegada.
  3. Defina GMSAutocompleteTableDataSource como a propriedade de fonte de dados e delegue a instância UITableView no controlador de visualização.
  4. No gerenciador da entrada de texto de pesquisa, chame sourceTextHasChanged no GMSAutocompleteTableDataSource.
  5. Gerencie a seleção do usuário no método delegado didAutocompleteWithPlace.
  6. Dispense o controlador nos métodos delegados didAutocompleteWithPlace, didFailAutocompleteWithError e wasCancelled.

O exemplo de código a seguir demonstra o uso da classe GMSAutocompleteTableDataSource para direcionar a visualização em tabela de um UIViewController quando UISearchBar é adicionado separadamente.

Swift

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import GooglePlaces
import UIKit

class PlaceAutocompleteViewController: UIViewController {

  private var tableView: UITableView!
  private var tableDataSource: GMSAutocompleteTableDataSource!

  override func viewDidLoad() {
    super.viewDidLoad()

    let searchBar = UISearchBar(frame: CGRect(x: 0, y: 20, width: self.view.frame.size.width, height: 44.0))
    searchBar.delegate = self
    view.addSubview(searchBar)

    tableDataSource = GMSAutocompleteTableDataSource()
    tableDataSource.delegate = self

    tableView = UITableView(frame: CGRect(x: 0, y: 64, width: self.view.frame.size.width, height: self.view.frame.size.height - 44))
    tableView.delegate = tableDataSource
    tableView.dataSource = tableDataSource

    view.addSubview(tableView)
  }
}

extension PlaceAutocompleteViewController: UISearchBarDelegate {
  func searchBar(_ searchBar: UISearchBar, textDidChange searchText: String) {
    // Update the GMSAutocompleteTableDataSource with the search text.
    tableDataSource.sourceTextHasChanged(searchText)
  }
}

extension PlaceAutocompleteViewController: GMSAutocompleteTableDataSourceDelegate {
  func didUpdateAutocompletePredictions(for tableDataSource: GMSAutocompleteTableDataSource) {
    // Turn the network activity indicator off.
    UIApplication.shared.isNetworkActivityIndicatorVisible = false
    // Reload table data.
    tableView.reloadData()
  }

  func didRequestAutocompletePredictions(for tableDataSource: GMSAutocompleteTableDataSource) {
    // Turn the network activity indicator on.
    UIApplication.shared.isNetworkActivityIndicatorVisible = true
    // Reload table data.
    tableView.reloadData()
  }

  func tableDataSource(_ tableDataSource: GMSAutocompleteTableDataSource, didAutocompleteWith place: GMSPlace) {
    // Do something with the selected place.
    print("Place name: \(place.name)")
    print("Place address: \(place.formattedAddress)")
    print("Place attributions: \(place.attributions)")
  }

  func tableDataSource(_ tableDataSource: GMSAutocompleteTableDataSource, didFailAutocompleteWithError error: Error) {
    // Handle the error.
    print("Error: \(error.localizedDescription)")
  }

  func tableDataSource(_ tableDataSource: GMSAutocompleteTableDataSource, didSelect prediction: GMSAutocompletePrediction) -> Bool {
    return true
  }
}

      

Objective-C

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#import "PlaceAutocompleteViewController.h"
@import GooglePlaces;
@import UIKit;

@interface PlaceAutocompleteViewController () <GMSAutocompleteTableDataSourceDelegate, UISearchBarDelegate>

@end

@implementation PlaceAutocompleteViewController {
  UITableView *tableView;
  GMSAutocompleteTableDataSource *tableDataSource;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  UISearchBar *searchBar = [[UISearchBar alloc] initWithFrame:CGRectMake(0, 20, self.view.frame.size.width, 44)];
  searchBar.delegate = self;

  [self.view addSubview:searchBar];

  tableDataSource = [[GMSAutocompleteTableDataSource alloc] init];
  tableDataSource.delegate = self;

  tableView = [[UITableView alloc] initWithFrame:CGRectMake(0, 64, self.view.frame.size.width, self.view.frame.size.height - 44)];
  tableView.delegate = tableDataSource;
  tableView.dataSource = tableDataSource;

  [self.view addSubview:tableView];
}

#pragma mark - GMSAutocompleteTableDataSourceDelegate

- (void)didUpdateAutocompletePredictionsForTableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource {
  // Turn the network activity indicator off.
  UIApplication.sharedApplication.networkActivityIndicatorVisible = NO;

  // Reload table data.
  [tableView reloadData];
}

- (void)didRequestAutocompletePredictionsForTableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource {
  // Turn the network activity indicator on.
  UIApplication.sharedApplication.networkActivityIndicatorVisible = YES;

  // Reload table data.
  [tableView reloadData];
}

- (void)tableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource didAutocompleteWithPlace:(GMSPlace *)place {
  // Do something with the selected place.
  NSLog(@"Place name: %@", place.name);
  NSLog(@"Place address: %@", place.formattedAddress);
  NSLog(@"Place attributions: %@", place.attributions);
}

- (void)tableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource didFailAutocompleteWithError:(NSError *)error {
  // Handle the error
  NSLog(@"Error %@", error.description);
}

- (BOOL)tableDataSource:(GMSAutocompleteTableDataSource *)tableDataSource didSelectPrediction:(GMSAutocompletePrediction *)prediction {
  return YES;
}

#pragma mark - UISearchBarDelegate

- (void)searchBar:(UISearchBar *)searchBar textDidChange:(NSString *)searchText {
  // Update the GMSAutocompleteTableDataSource with the search text.
  [tableDataSource sourceTextHasChanged:searchText];
}

@end

      

Como personalizar cores de texto e de plano de fundo

Você pode definir as cores de todos os planos de fundo e textos no controle de IU do Autocomplete para que o widget corresponda à aparência visual do app de maneira mais precisa. Há duas formas de definir as cores do widget:

  • Use o protocolo UIAppearance do iOS nativo para definir o estilo de controles de IU sempre que possível. Essas configurações se aplicam a muitos, mas não todos, os elementos de controle da IU.
  • Usando os métodos do SDK nas classes de widget para definir propriedades que não são compatíveis com o protocolo UIAppearance.

Normalmente, o app usa uma combinação do protocolo UIAppearance e dos métodos do SDK. O diagrama a seguir mostra que elementos podem ser estilizados:

Preencher automaticamente as cores do controle da IU

A tabela a seguir lista todos os elementos da IU e indica como cada um precisa ser estilizado (protocolo UIAppearance ou método SDK).

Elemento de IU Método Guias de estilo
Tonalidade da barra de navegação (segundo plano) Protocolo UIAppearance Chame setBarTintColor no proxy UINavigationBar.
Cor da barra de navegação (circunflexo na barra de pesquisa e botão "Cancelar") Protocolo UIAppearance Chame setTintColor no proxy UINavigationBar.
Cor do texto da barra de pesquisa Protocolo UIAppearance Defina NSForegroundColorAttributeName em searchBarTextAttributes.
Cor da tonalidade da barra de pesquisa N/A A barra de pesquisa é translúcida e será exibida como uma versão sombreada da barra de navegação.
Cor do texto do marcador da barra de pesquisa (texto de pesquisa padrão) Protocolo UIAppearance Defina NSForegroundColorAttributeName em placeholderAttributes.
Texto principal (também aplicado a erros e texto de mensagens) Método do SDK Chame primaryTextColor.
Destaque de texto principal Método do SDK Chame primaryTextHighlightColor.
Texto secundário Método do SDK Chame secondaryTextColor.
Texto de erro e mensagem Método do SDK Chame primaryTextColor.
Plano de fundo da célula da tabela Método do SDK Chame tableCellBackgroundColor.
Cor do separador de células da tabela Método do SDK Chame tableCellSeparatorColor.
Botão "Tentar novamente" Método do SDK Chame tintColor.
Indicador de atividade (ícone de carregamento do progresso) Protocolo UIAppearance Chame setColor no proxy UIActivityIndicatorView.
Logotipo "Powered by Google", imagem de nuvem triste N/A A versão em branco ou cinza é selecionada automaticamente com base no contraste do plano de fundo.
Lupa e ícones de texto simples no campo de texto da barra de pesquisa N/A Para definir o estilo, substitua as imagens padrão por imagens da cor desejada.

Como usar o protocolo UIAppearance

Você pode usar o protocolo UIAppearance para usar o proxy de aparência de um determinado elemento da IU, que pode ser usado para definir a cor dele. Quando uma modificação é feita, todas as instâncias de um determinado elemento da IU são afetadas. Por exemplo, o exemplo abaixo muda a cor do texto de classes UITextField para verde quando elas estão contidas em um UISearchBar:

[[UITextField appearanceWhenContainedIn:[UISearchBar class], nil]
    setDefaultTextAttributes:@{NSForegroundColorAttributeName:[UIColor greenColor]}];

Para mais informações sobre como definir valores de cor, consulte a Referência da classe UIColor.

Os snippets de código a seguir mostram todos os comandos de proxy que você precisa usar para definir o estilo de tudo no controle de IU de preenchimento automático em tela cheia. Adicione este código ao método didFinishLaunchingWithOptions em Appdelegate.m:

// Define some colors.
UIColor *darkGray = [UIColor darkGrayColor];
UIColor *lightGray = [UIColor lightGrayColor];

// Navigation bar background.
[[UINavigationBar appearance] setBarTintColor:darkGray];
[[UINavigationBar appearance] setTintColor:lightGray];

// Color of typed text in the search bar.
NSDictionary *searchBarTextAttributes = @{
                                          NSForegroundColorAttributeName: lightGray,
                                          NSFontAttributeName : [UIFont systemFontOfSize:[UIFont systemFontSize]]
                                          };
[UITextField appearanceWhenContainedInInstancesOfClasses:@[[UISearchBar class]]]
    .defaultTextAttributes = searchBarTextAttributes;

// Color of the placeholder text in the search bar prior to text entry.
NSDictionary *placeholderAttributes = @{
                                        NSForegroundColorAttributeName: lightGray,
                                        NSFontAttributeName : [UIFont systemFontOfSize:[UIFont systemFontSize]]
                                        };

// Color of the default search text.
// NOTE: In a production scenario, "Search" would be a localized string.
NSAttributedString *attributedPlaceholder =
[[NSAttributedString alloc] initWithString:@"Search"
                                attributes:placeholderAttributes];
[UITextField appearanceWhenContainedInInstancesOfClasses:@[[UISearchBar class]]]
    .attributedPlaceholder = attributedPlaceholder;

// Color of the in-progress spinner.
[[UIActivityIndicatorView appearance] setColor:lightGray];

// To style the two image icons in the search bar (the magnifying glass
// icon and the 'clear text' icon), replace them with different images.
[[UISearchBar appearance] setImage:[UIImage imageNamed:@"custom_clear_x_high"]
                  forSearchBarIcon:UISearchBarIconClear
                            state:UIControlStateHighlighted];
[[UISearchBar appearance] setImage:[UIImage imageNamed:@"custom_clear_x"]
                  forSearchBarIcon:UISearchBarIconClear
                            state:UIControlStateNormal];
[[UISearchBar appearance] setImage:[UIImage imageNamed:@"custom_search"]
                    forSearchBarIcon:UISearchBarIconSearch
                            state:UIControlStateNormal];

// Color of selected table cells.
UIView *selectedBackgroundView = [[UIView alloc] init];
selectedBackgroundView.backgroundColor = [UIColor lightGrayColor];
[UITableViewCell appearanceWhenContainedIn:[GMSAutocompleteViewController class], nil]
    .selectedBackgroundView = selectedBackgroundView;

Como definir propriedades de estilo de controle de IU

Um subconjunto de elementos de controle da IU tem propriedades que não são afetadas pelo protocolo UIAppearance, portanto, precisa ser definido diretamente. O exemplo de código a seguir mostra a definição de cores em primeiro e segundo plano e a aplicação delas a uma instância de controle da IU chamada acController. Adicione este código ao método onLaunchClicked em ViewController.m:

UIColor *darkGray = [UIColor darkGrayColor];
UIColor *lightGray = [UIColor lightGrayColor];

acController.secondaryTextColor = [UIColor colorWithWhite:1.0f alpha:0.5f];
acController.primaryTextColor = lightGray;
acController.primaryTextHighlightColor = [UIColor grayColor];
acController.tableCellBackgroundColor = darkGray;
acController.tableCellSeparatorColor = lightGray;
acController.tintColor = lightGray;

Como receber previsões de lugar de forma programática

Você pode criar uma IU de pesquisa personalizada como uma alternativa à IU fornecida pelo widget de preenchimento automático. Para fazer isso, seu app precisa receber previsões de lugar de forma programática. Seu app pode conseguir uma lista de nomes e/ou endereços de lugares previstos de uma das seguintes maneiras:

Ligando para GMSPlacesClient findAutocompletePredictionsFromQuery:

Para ver uma lista de nomes e/ou endereços de lugares previstos, primeiro instancie o GMSPlacesClient e, em seguida, chame o método GMSPlacesClient findAutocompletePredictionsFromQuery: com os parâmetros a seguir:

  • Uma string autocompleteQuery contendo o texto digitado pelo usuário.
  • Uma GMSAutocompleteSessionToken, que é usada para identificar cada sessão individual. Seu app precisa transmitir o mesmo token para cada chamada de solicitação de preenchimento automático e, em seguida, transmitir esse token com um ID de local na chamada seguinte para fetchPlacefromPlaceID: para recuperar o Place Details do local selecionado pelo usuário.
  • Um GMSAutocompleteFilter para:
    • Viés ou restringir os resultados para uma região específica.
    • Restrinja os resultados a um tipo específico de lugar.
    • Um objeto GMSPlaceLocationBias/Constraint que direciona os resultados para uma área especificada por limites de latitude e longitude
  • Um método de callback para lidar com as previsões retornadas.

Os exemplos de código abaixo mostram uma chamada para findAutocompletePredictionsFromQuery:.

Swift

/**
 * Create a new session token. Be sure to use the same token for calling
 * findAutocompletePredictions, as well as the subsequent place details request.
 * This ensures that the user's query and selection are billed as a single session.
 */
let token = GMSAutocompleteSessionToken.init()

// Create a type filter.
let filter = GMSAutocompleteFilter()
filter.types = [.bank] 
filter.locationBias = GMSPlaceRectangularLocationOption( northEastBounds,
                                   southWestBounds);

placesClient?.findAutocompletePredictions(fromQuery: "cheesebu",

                                          filter: filter,
                                          sessionToken: token,
                                          callback: { (results, error) in
    if let error = error {
      print("Autocomplete error: \(error)")
      return
    }
    if let results = results {
      for result in results {
        print("Result \(result.attributedFullText) with placeID \(result.placeID)")
      }
    }
})

Objective-C

/**
 * Create a new session token. Be sure to use the same token for calling
 * findAutocompletePredictionsFromQuery:, as well as the subsequent place details request.
 * This ensures that the user's query and selection are billed as a single session.
 */
GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init];

// Create a type filter.
GMSAutocompleteFilter *_filter = [[GMSAutocompleteFilter alloc] init];
_filter.types = @[ kGMSPlaceTypeBank ];

[_placesClient findAutocompletePredictionsFromQuery:@"cheesebu"
filter:_filter sessionToken:token callback:^(NSArray<GMSAutocompletePrediction *> * _Nullable results, NSError * _Nullable error) {
  if (error != nil) {
    NSLog(@"An error occurred %@", [error localizedDescription]);
    return;
  }
  if (results != nil) {
    for (GMSAutocompletePrediction *result in results) {
      NSLog(@"Result %@ with PlaceID %@", result.attributedFullText, result.placeID);
    }
  }
}];

A API invoca o método de callback especificado, transmitindo uma matriz de objetos GMSAutocompletePrediction.

Cada objeto GMSAutocompletePrediction contém as seguintes informações:

  • attributedFullText: o texto completo da previsão, na forma de um NSAttributedString. Por exemplo, "Sydney Opera House, Sydney, New South Wales, Austrália". Cada intervalo de texto que corresponde à entrada do usuário tem um atributo, kGMSAutocompleteMatchAttribute. Use esse atributo para destacar o texto correspondente na consulta do usuário, por exemplo, como mostrado abaixo.
  • placeID: o ID do lugar previsto. O ID do lugar é um identificador textual que identifica um lugar de forma exclusiva. Para mais informações sobre IDs de lugar, consulte a Visão geral do ID de lugar.
  • distanceMeters: a distância em linha reta entre a origin especificada até o destino. Se a propriedade origin não estiver definida, nenhum valor de distância será retornado.

O exemplo de código a seguir ilustra como destacar em negrito as partes do resultado que correspondem ao texto da consulta do usuário usando enumerateAttribute:

Swift

let regularFont = UIFont.systemFont(ofSize: UIFont.labelFontSize)
let boldFont = UIFont.boldSystemFont(ofSize: UIFont.labelFontSize)

let bolded = prediction.attributedFullText.mutableCopy() as! NSMutableAttributedString
bolded.enumerateAttribute(kGMSAutocompleteMatchAttribute, in: NSMakeRange(0, bolded.length), options: []) {
  (value, range: NSRange, stop: UnsafeMutablePointer<ObjCBool>) -> Void in
    let font = (value == nil) ? regularFont : boldFont
    bolded.addAttribute(NSFontAttributeName, value: font, range: range)
}

label.attributedText = bolded
    

Objective-C

UIFont *regularFont = [UIFont systemFontOfSize:[UIFont labelFontSize]];
UIFont *boldFont = [UIFont boldSystemFontOfSize:[UIFont labelFontSize]];

NSMutableAttributedString *bolded = [prediction.attributedFullText mutableCopy];
[bolded enumerateAttribute:kGMSAutocompleteMatchAttribute
                   inRange:NSMakeRange(0, bolded.length)
                   options:0
                usingBlock:^(id value, NSRange range, BOOL *stop) {
                  UIFont *font = (value == nil) ? regularFont : boldFont;
                  [bolded addAttribute:NSFontAttributeName value:font range:range];
                }];

label.attributedText = bolded;
    

Como usar o coletor

Se você quiser criar seu próprio controle de preenchimento automático do zero, use GMSAutocompleteFetcher, que encapsula o método autocompleteQuery em GMSPlacesClient. O coletor limita as solicitações, retornando apenas resultados para o texto da pesquisa inserido mais recentemente. Ele não fornece elementos de IU.

Para implementar o GMSAutocompleteFetcher, siga estas etapas:

  1. Implemente o protocolo GMSAutocompleteFetcherDelegate.
  2. Crie um objeto GMSAutocompleteFetcher.
  3. Chame sourceTextHasChanged no coletor enquanto o usuário digita.
  4. Processe previsões e erros usando os métodos de protocolo didAutcompleteWithPredictions e didFailAutocompleteWithError.

O exemplo de código a seguir demonstra como usar o coletor para receber a entrada do usuário e exibir correspondências de local em uma visualização de texto. A funcionalidade de selecionar um lugar foi omitida. FetcherSampleViewController deriva de UIViewController em FetcherSampleViewController.h.

Swift

import UIKit
import GooglePlaces

class ViewController: UIViewController {

  var textField: UITextField?
  var resultText: UITextView?
  var fetcher: GMSAutocompleteFetcher?

  override func viewDidLoad() {
    super.viewDidLoad()

    view.backgroundColor = .white
    edgesForExtendedLayout = []

    // Set bounds to inner-west Sydney Australia.
    let neBoundsCorner = CLLocationCoordinate2D(latitude: -33.843366,
                                                longitude: 151.134002)
    let swBoundsCorner = CLLocationCoordinate2D(latitude: -33.875725,
                                                longitude: 151.200349)

    // Set up the autocomplete filter.
    let filter = GMSAutocompleteFilter()
    filter.locationRestriction = GMSPlaceRectangularLocationOption(neBoundsCorner, swBoundsCorner)

    // Create a new session token.
    let token: GMSAutocompleteSessionToken = GMSAutocompleteSessionToken.init()

    // Create the fetcher.
    fetcher = GMSAutocompleteFetcher(bounds: nil, filter: filter)
    fetcher?.delegate = self
    fetcher?.provide(token)

    textField = UITextField(frame: CGRect(x: 5.0, y: 10.0,
                                          width: view.bounds.size.width - 5.0,
                                          height: 64.0))
    textField?.autoresizingMask = .flexibleWidth
    textField?.addTarget(self, action: #selector(textFieldDidChange(textField:)),
                         for: .editingChanged)
    let placeholder = NSAttributedString(string: "Type a query...")

    textField?.attributedPlaceholder = placeholder

    resultText = UITextView(frame: CGRect(x: 0, y: 65.0,
                                          width: view.bounds.size.width,
                                          height: view.bounds.size.height - 65.0))
    resultText?.backgroundColor = UIColor(white: 0.95, alpha: 1.0)
    resultText?.text = "No Results"
    resultText?.isEditable = false

    self.view.addSubview(textField!)
    self.view.addSubview(resultText!)
  }

  @objc func textFieldDidChange(textField: UITextField) {
    fetcher?.sourceTextHasChanged(textField.text!)
  }

}

extension ViewController: GMSAutocompleteFetcherDelegate {
  func didAutocomplete(with predictions: [GMSAutocompletePrediction]) {
    let resultsStr = NSMutableString()
    for prediction in predictions {
      resultsStr.appendFormat("\n Primary text: %@\n", prediction.attributedPrimaryText)
      resultsStr.appendFormat("Place ID: %@\n", prediction.placeID)
    }

    resultText?.text = resultsStr as String
  }

  func didFailAutocompleteWithError(_ error: Error) {
    resultText?.text = error.localizedDescription
  }
}

Objective-C

#import "FetcherSampleViewController.h"
#import <GooglePlaces/GooglePlaces.h>
#import <GoogleMapsBase/GoogleMapsBase.h>

@interface FetcherSampleViewController () <GMSAutocompleteFetcherDelegate>

@end

@implementation FetcherSampleViewController {
  UITextField *_textField;
  UITextView *_resultText;
  GMSAutocompleteFetcher* _fetcher;
}

- (void)viewDidLoad {
  [super viewDidLoad];

  self.view.backgroundColor = [UIColor whiteColor];
  self.edgesForExtendedLayout = UIRectEdgeNone;

  // Set bounds to inner-west Sydney Australia.
  CLLocationCoordinate2D neBoundsCorner = CLLocationCoordinate2DMake(-33.843366, 151.134002);
  CLLocationCoordinate2D swBoundsCorner = CLLocationCoordinate2DMake(-33.875725, 151.200349);

  GMSAutocompleteFilter *autocompleteFilter = [[GMSAutocompleteFilter alloc] init];
  autocompleteFilter.locationRestriction =
        GMSPlaceRectangularLocationOption(neBoundsCorner, swBoundsCorner);

  // Create the fetcher.
  _fetcher = [[GMSAutocompleteFetcher alloc] initWithBounds:nil
                                                     filter:filter];
  _fetcher.delegate = self;

  // Set up the UITextField and UITextView.
  _textField = [[UITextField alloc] initWithFrame:CGRectMake(5.0f,
                                                             0,
                                                             self.view.bounds.size.width - 5.0f,
                                                             44.0f)];
  _textField.autoresizingMask = UIViewAutoresizingFlexibleWidth;
  [_textField addTarget:self
                 action:@selector(textFieldDidChange:)
       forControlEvents:UIControlEventEditingChanged];
  _resultText =[[UITextView alloc] initWithFrame:CGRectMake(0,
                                                            45.0f,
                                                            self.view.bounds.size.width,
                                                            self.view.bounds.size.height - 45.0f)];
  _resultText.backgroundColor = [UIColor colorWithWhite:0.95f alpha:1.0f];
  _resultText.text = @"No Results";
  _resultText.editable = NO;
  [self.view addSubview:_textField];
  [self.view addSubview:_resultText];
}

- (void)textFieldDidChange:(UITextField *)textField {
  NSLog(@"%@", textField.text);
  [_fetcher sourceTextHasChanged:textField.text];
}

#pragma mark - GMSAutocompleteFetcherDelegate
- (void)didAutocompleteWithPredictions:(NSArray *)predictions {
  NSMutableString *resultsStr = [NSMutableString string];
  for (GMSAutocompletePrediction *prediction in predictions) {
      [resultsStr appendFormat:@"%@\n", [prediction.attributedPrimaryText string]];
  }
  _resultText.text = resultsStr;
}

- (void)didFailAutocompleteWithError:(NSError *)error {
  _resultText.text = [NSString stringWithFormat:@"%@", error.localizedDescription];
}

@end

Tokens de sessão

Os tokens de sessão agrupam as fases de consulta e seleção de uma pesquisa de preenchimento automático de usuários em uma sessão discreta para fins de faturamento. A sessão começa quando o usuário começa a digitar uma consulta e é concluída quando ele seleciona um lugar. Cada sessão pode ter várias consultas, seguidas por uma seleção de lugares. Quando uma sessão é concluída, o token deixa de ser válido. O app precisa gerar um token novo para cada sessão. Recomendamos o uso de tokens de sessão para todas as sessões de preenchimento automático programático (quando você usa o controlador de tela cheia ou o controlador de resultados, a API cuida disso automaticamente).

O SDK do Places para iOS usa um GMSAutocompleteSessionToken para identificar cada sessão. Seu app precisa transmitir um novo token no início de cada sessão e, em seguida, transmitir esse mesmo token com um ID de local na chamada seguinte para fetchPlacefromPlaceID: para recuperar o Place Details do local selecionado pelo usuário.

Saiba mais sobre tokens de sessão.

Use o código a seguir para gerar um novo token:

let token: GMSAutocompleteSessionToken = GMSAutocompleteSessionToken.init()

Limites de uso

Como mostrar atribuições no app

  • Se o app usa o serviço de preenchimento automático de forma programática, a IU precisa exibir uma atribuição "Tecnologia do Google" ou aparecer em um mapa com marca do Google.
  • Se o app usa o controle de IU de preenchimento automático, nenhuma ação adicional é necessária (a atribuição necessária é exibida por padrão).
  • Se você recuperar e exibir outras informações do lugar depois de conseguir um lugar por ID, também será necessário exibir atribuições de terceiros.

Para mais detalhes, consulte a documentação sobre atribuições.

Como controlar o indicador de atividade de rede

Para controlar o indicador de atividade de rede na barra de status do aplicativo, implemente os métodos de delegação opcionais adequados à classe de preenchimento automático que você está usando e ative e desative o indicador de rede por conta própria.

  • Para o GMSAutocompleteViewController, implemente os métodos delegados didRequestAutocompletePredictions: e didUpdateAutocompletePredictions:.
  • Para o GMSAutocompleteResultsViewController, implemente os métodos delegados didRequestAutocompletePredictionsForResultsController: e didUpdateAutocompletePredictionsForResultsController:.
  • Para o GMSAutocompleteTableDataSource, implemente os métodos delegados didRequestAutocompletePredictionsForTableDataSource: e didUpdateAutocompletePredictionsForTableDataSource:.

Ao implementar esses métodos e definir [UIApplication sharedApplication].networkActivityIndicatorVisible como YES e NO, respectivamente, a barra de status corresponderá corretamente à IU de preenchimento automático.

Restringir resultados do preenchimento automático

Você pode definir o controle de IU de preenchimento automático para restringir os resultados a uma região geográfica específica e/ou filtrar os resultados para um ou mais tipos de lugar ou para um ou mais países. Para restringir os resultados, faça o seguinte:

  • Para preferir (vieses) nos resultados na região definida, defina locationBias em GMSAutocompleteFilter. Alguns resultados de fora da região definida ainda podem ser retornados. Se locationRestriction também for definido, o locationBias será ignorado.
  • Para mostrar apenas resultados (restringir) na região definida, defina locationRestriction no GMSAutocompleteFilter (somente resultados dentro da região definida serão retornados).

    • Observação:essa restrição é aplicada apenas a rotas inteiras. Os resultados sintéticos localizados fora dos limites retangulares podem ser retornados com base em uma rota que se sobreponha à restrição do local.
  • Para retornar apenas resultados que estejam em conformidade com um determinado tipo de lugar, defina type em GMSAutocompleteFilter. Por exemplo, especificar TypeFilter.ADDRESS fará com que o widget retorne apenas resultados com um endereço preciso.

  • Para retornar apenas resultados dentro de até cinco países especificados, defina countries na GMSAutocompleteFilter.

Direcionar os resultados para uma região específica

Para preferir (vieses) nos resultados na região definida, defina locationBias em GMSAutocompleteFilter, conforme mostrado aqui:

  northEast = CLLocationCoordinate2DMake(39.0, -95.0);
  southWest = CLLocationCoordinate2DMake(37.5, -100.0);
  GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
  filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);

Restringir os resultados a uma região específica

Para mostrar apenas (restringir) resultados dentro da região definida, defina locationRestriction no GMSAutocompleteFilter, conforme mostrado aqui:

  northEast = CLLocationCoordinate2DMake(39.0, -95.0);
  southWest = CLLocationCoordinate2DMake(37.5, -100.0);
  GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
  filter.locationRestriction = GMSPlaceRectangularLocationOption(northEast, southWest);

Filtrar resultados por país

Para filtrar os resultados em até cinco países especificados, defina countries em GMSAutocompleteFilter, conforme mostrado aqui:

  GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
  filter.countries = @[ @"au", @"nz" ];

Filtrar resultados por tipo de lugar ou coleção de tipos

Para restringir os resultados a um determinado tipo ou coleção de tipos, defina a propriedade types de GMSAutoCompleteFilter. Use essa propriedade para especificar os filtros listados nas tabelas 1, 2 e 3 em Place Types. Se nada for especificado, todos os tipos serão retornados.

Para especificar um tipo ou filtro de coleção de tipos:

  • Use a propriedade types para especificar até cinco valores de type da Tabela 1 e da Tabela 2 mostrados nos Tipos de lugares. Os valores de tipo são definidos pelas constantes em GMSPlaceType.

  • Use a propriedade types para especificar uma coleção de tipos da Tabela 3, mostrada em Tipos de lugar. Os valores da coleção de tipo são definidos pelas constantes em GMSPlaceType.

    Somente um tipo da Tabela 3 é permitido na solicitação. Se você especificar um valor na Tabela 3, não será possível especificar um na Tabela 1 ou na Tabela 2. Se você fizer isso, ocorrerá um erro.

Por exemplo, para retornar apenas resultados que estejam em conformidade com um determinado tipo de lugar, defina types em GMSAutocompleteFilter. O exemplo a seguir mostra como configurar o filtro para retornar somente resultados com um endereço preciso:

  GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
  filter.types = @[ kGMSPlaceTypeAirport, kGMSPlaceTypeAmusementPark ];

Otimização do Place Autocomplete

Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço Place Autocomplete.

Aqui estão algumas diretrizes gerais:

  • A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget do Autocomplete da API Maps JavaScript, o widget do Autocomplete do SDK do Places para Android ou Controle de IU do Autocomplete do SDK do Places para iOS.
  • Entender os campos de dados essenciais do Place Autocomplete desde o início.
  • Os campos de direcionamento de local e restrição de local são opcionais, mas podem afetar bastante a performance do preenchimento automático.
  • Use o tratamento de erros para garantir que o aplicativo faça uma degradação simples se a API retornar um erro.
  • Verifique se o app continua funcionando quando não há seleção e que oferece às pessoas uma maneira de continuar.

Práticas recomendadas de otimização de custos

Otimização básica de custos

Para otimizar o custo do uso do serviço Place Autocomplete, use máscaras de campo nos widgets Place Details e Place Autocomplete para retornar apenas os campos de dados de lugar necessários.

Otimização avançada de custos

Faça a implementação programática do Place Autocomplete para acessar preços por solicitação e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details. O preço por solicitação combinado com a API Geocoding vai ser mais econômico que o preço por sessão se as duas condições a seguir forem atendidas:

  • Se você só precisa da latitude/longitude ou do endereço do local selecionado pela pessoa, a API Geocoding fornece essas informações por menos do que uma chamada do Place Details.
  • Se os usuários selecionarem uma previsão de preenchimento automático em média com quatro solicitações desse tipo, o preço por solicitação poderá ser mais econômico que o custo por sessão.
Se quiser ajuda para escolher a implementação do Place Autocomplete de acordo com o que você precisa, selecione a guia correspondente à resposta à pergunta abaixo.

Seu aplicativo requer outras informações além do endereço e da latitude/longitude da previsão selecionada?

Sim, mais detalhes são necessários

Use o Place Autocomplete com base em sessões com o Place Details.
Como seu app exige detalhes do lugar, como nome, status comercial ou horário de funcionamento, a implementação do preenchimento automático precisa usar um token de sessão (de forma programática ou integrada aos widgets do JavaScript, Android ou iOS) a um total de US$ 0,017 por sessão, além de SKU de dados do Places relevantes, dependendo dos campos de dados de lugares que você solicita.1

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Place Autocomplete e do Place Details na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos de dados de lugares necessários.

Implementação programática
Use um token de sessão com suas solicitações do Place Autocomplete. Ao solicitar Place Details sobre a previsão selecionada, inclua os seguintes parâmetros:

  1. O ID de lugar da resposta do Place Autocomplete
  2. O token de sessão usado na solicitação do Place Autocomplete
  3. O parâmetro fields especificando os campos de dados de lugar necessários.

Não, apenas o endereço e o local são necessários

A API Geocoding pode ser uma opção mais econômica que o Place Details para seu aplicativo, dependendo da performance do Place Autocomplete. A eficiência do preenchimento automático de cada aplicativo varia de acordo com o que as pessoas inserem, onde o aplicativo está sendo usado e se as práticas recomendadas de otimização de performance foram seguidas.

Para responder à pergunta a seguir, analise quantos caracteres a pessoa digita em média antes de selecionar uma previsão do Place Autocomplete no seu aplicativo.

As pessoas selecionam, em média, uma previsão do Place Autocomplete em até quatro solicitações?

Sim

Implementar o Place Autocomplete de forma programática sem tokens de sessão e chamar a API Geocoding na previsão de lugar selecionada.
A API Geocoding oferece endereços e coordenadas de latitude/longitude por US$ 0,005 a cada solicitação. Fazer quatro solicitações de Place Autocomplete: por solicitação custa US$ 0,01132. Portanto, o custo total de quatro solicitações, além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, é de US$ 0,01632, menor que o preço de preenchimento automático por sessão de US$ 0,017.1

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Não

Use o Place Autocomplete com base em sessões com o Place Details.
Como a média de solicitações que você espera fazer antes de alguém selecionar uma previsão do Place Autocomplete é maior que o custo do preço por sessão, a implementação do Place Autocomplete precisa usar um token de sessão para as solicitações do Place Autocomplete e a respectiva solicitação do Place Details por um total de US$ 0,017 a cada sessão.1

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Place Autocomplete e do Place Details na previsão selecionada. Especifique o parâmetro fields para garantir a solicitação apenas dos campos de dados básicos.

Implementação programática
Use um token de sessão com suas solicitações do Place Autocomplete. Ao solicitar Place Details sobre a previsão selecionada, inclua os seguintes parâmetros:

  1. O ID de lugar da resposta do Place Autocomplete
  2. O token de sessão usado na solicitação do Place Autocomplete
  3. O parâmetro fields que especifica campos de dados básicos como endereço e geometria

Considere atrasar as solicitações do Place Autocomplete
É possível adiar uma solicitação do Place Autocomplete até que a pessoa digite os três ou quatro primeiros caracteres, fazendo com que o aplicativo gere menos solicitações. Por exemplo, fazer solicitações do Place Autocomplete para cada caractere depois que o usuário digita o terceiro caractere significa que, se ele digitar 7 caracteres e selecionar uma previsão em que você fez uma solicitação da API Geocoding, o custo total vai ser de US$ 0,01632 (4 × US$ 0,00283 do Autocomplete por solicitação + US$ 0,005 do Geocoding).1

Se for possível usar o atraso de solicitações para deixar sua solicitação programática média abaixo de quatro, siga as orientações para ter uma performance eficiente no Place Autocomplete com a API Geocoding. Atrasar solicitações pode ser percebido como latência pelo usuário, que talvez queira ver previsões a cada vez que pressionar uma nova tecla.

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.


  1. Os custos listados aqui estão em USD. Consulte a página Faturamento da Plataforma Google Maps para saber tudo sobre os preços.

Práticas recomendadas de performance

As diretrizes a seguir descrevem como otimizar a performance do Place Autocomplete:

  • Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Place Autocomplete. A preferência de idioma não é necessária com widgets porque eles usam o que está definido no navegador ou no dispositivo móvel do usuário.
  • Se o Place Autocomplete estiver acompanhado por um mapa, é possível direcionar o local por janela de visualização do mapa.
  • Quando a pessoa não escolhe uma das previsões do Autocomplete, geralmente porque nenhuma delas revisões é o endereço que ela quer, você pode reutilizar a entrada original para tentar receber resultados mais relevantes:
    • Se quiser que o usuário insira apenas informações de endereço, reutilize a entrada original dele em uma chamada para a API Geocoding.
    • Se quiser que o usuário insira consultas para um lugar específico por nome ou endereço, use uma solicitação do Find Place. Se os resultados forem esperados apenas em uma região específica, use o direcionamento de local.
    Outros cenários em que é melhor voltar para a API Geocoding são:
    • Usuários que inserem endereços de sublocal em países onde a compatibilidade do Place Autocomplete com esse tipo de endereço é parcial (como República Tcheca, Estônia e Lituânia). Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no Place Autocomplete.
    • Usuários que digitam endereços com prefixos de trechos de via, como "23-30 29th St, Queens", na cidade de Nova York, ou "47-380 Kamehameha Hwy, Kaneohe", na ilha de Kauai, no Havaí.

Solução de problemas

Embora uma grande variedade de erros possa ocorrer, a maioria dos erros que seu app provavelmente receberá é causada por erros de configuração (por exemplo, a chave de API incorreta foi usada ou a chave de API foi configurada incorretamente) ou erros de cota (o app excedeu a cota). Consulte Limites de uso para mais informações sobre cotas.

Os erros que ocorrem no uso dos controles de preenchimento automático são retornados no método didFailAutocompleteWithError() dos vários protocolos delegados. A propriedade code do objeto NSError fornecido está definida como um dos valores da enumeração GMSPlacesErrorCode.