Configurar um projeto do Xcode

Siga as etapas deste guia para fazer o download do SDK do Places para iOS, adicionar a biblioteca e as dependências ao app e receber uma chave de API sem custos financeiros.

As Notas de lançamento estão disponíveis para cada versão.

Etapa 1: obter a versão mais recente do Xcode

Para criar um projeto usando o SDK do Places para iOS, você precisa de:

1. Xcode versão 14.0 ou posterior
2. Cocoapods ou Carthage.

Etapa 2: instalar o SDK

Para instalar a API em um novo projeto, siga estas etapas:

Usar CocoaPods

O SDK do Places para iOS está disponível como um pod do CocoaPod, GooglePlaces, que contém todas as funcionalidades de lugares.

O CocoaPods é um gerenciador de dependências de código aberto para projetos Cocoa em Swift e Objective-C. Se você ainda não tiver a ferramenta CocoaPods, instale-a no macOS executando o seguinte comando no terminal. Para mais detalhes, consulte o Guia de primeiros passos do CocoaPods.

sudo gem install cocoapods

Crie um Podfile para o SDK do Places para iOS e use-o para instalar o SDK e as dependências dele:

1. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o no computador local. Se você é novo no desenvolvimento para iOS, crie um novo projeto e selecione o modelo de app para iOS.
2. Crie um arquivo chamado Podfile no seu diretório do projeto para definir as dependências.
3. Edite a Podfile e adicione as dependências com as versões delas. Veja um exemplo que especifica o nome de destino do aplicativo e o nome do pod GooglePlaces:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '14.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GooglePlaces', '8.0.0'
   end
   

   Execute pod outdated regularmente para detectar quando houver uma versão mais recente e garantir que você tenha sempre a mais recente.
4. Salve o Podfile.

5. Abra um terminal e acesse o diretório que contém o Podfile:

   cd <path-to-project>

6. Execute o comando pod install. Isso instalará as APIs especificadas no Podfile e as respectivas dependências.

   pod install

7. Feche o Xcode e clique duas vezes no arquivo .xcworkspace do projeto para iniciar o programa. Depois disso, é preciso usar o arquivo .xcworkspace para abrir o projeto.

Para atualizar a API de um projeto existente, siga estas etapas:

1. Abra um terminal e acesse o diretório do projeto que contém o Podfile.
2. Execute o comando pod update. Isso atualizará todas as APIs especificadas no Podfile para a versão mais recente.

Usar Cartago

Observação : atualmente, o Carthage não é compatível com bibliotecas criadas para versões mínimas do iOS 13 e versões mais recentes. Isso significa que a versão compatível mais recente do SDK do Places para iOS é a 6.2.1.

O SDK do Places para iOS está disponível para uso com o Carthage, um gerenciador de dependências simples e descentralizado para projetos Cocoa em Swift e Objective-C.

1. Instale o Carthage. Existem vários métodos. Portanto, consulte o arquivo README do Carthage (em inglês) para ver as etapas exatas.
2. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o no computador local. Se você é novo no desenvolvimento para iOS, crie um novo projeto e selecione o modelo de app para iOS.
3. Crie um arquivo chamado Cartfile no seu diretório do projeto Esse arquivo define as dependências do projeto.
4. Edite o Cartfile e adicione as dependências com as respectivas versões:
   

    binary "https://dl.google.com/geosdk/GooglePlaces.json" == 6.2.1

   Execute o carthage outdated regularmente para detectar quando houver uma versão mais recente e garantir que você esteja sempre com a mais recente.
5. Salve o Cartfile.
6. Em uma janela de terminal, acesse o diretório que contém Cartfile:
   

   cd <path-to-project>

7. Execute o comando carthage update. Isso instalará as APIs especificadas no Cartfile e as respectivas dependências.
8. No Finder, no diretório do projeto, acesse os arquivos do framework salvos em Carthage/Build/iOS.
9. Arraste os seguintes pacotes para o projeto. Quando solicitado, selecione Copiar itens, se necessário:
   • GooglePlaces-x.x.x/Frameworks/GooglePlaces.xcframework
10. Clique com o botão direito do mouse em GooglePlaces.xcframework no projeto e selecione Show In Finder.
11. Arraste GooglePlaces.bundle da pasta Resources para o projeto. Quando solicitado, verifique se Copy items into destination group's folder não está selecionado.
12. Selecione o projeto no Project Navigator e escolha o local de destino do aplicativo.
13. Abra a guia Fases de compilação e, em Vincular binário às bibliotecas, adicione os seguintes frameworks e bibliotecas:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework

14. Escolha seu projeto, em vez de um destino específico, e abra a guia Build Settings.

15. Na seção Outras sinalizações do vinculador, adicione -ObjC. Se essas configurações não estiverem visíveis, altere o filtro na barra Build Settings de Basic para All.

Para atualizar a API de um projeto existente, siga estas etapas:

1. Abra um terminal e acesse o diretório do projeto que contém o Cartfile.
2. Execute o comando carthage update. Isso atualizará todas as APIs especificadas no Cartfile para a versão mais recente.

Instalar manualmente

Este guia mostra como adicionar manualmente a biblioteca GooglePlaces ao projeto e definir as configurações de compilação no Xcode.

1. Faça o download dos arquivos de origem do SDK: GooglePlaces-8.0.0
2. Descompacte-os.
3. Inicialize o Xcode e abra ou crie um projeto. Se você é novo no desenvolvimento para iOS, crie um novo projeto e selecione o iOS App template.
4. Remova todas as versões anteriores do Maps do projeto.
5. Arraste os seguintes pacotes para o projeto. Quando solicitado, selecione Copiar itens, se necessário:
   • GooglePlaces-x.x.x/Frameworks/GooglePlaces.xcframework
6. Clique com o botão direito do mouse em GooglePlaces.xcframework no projeto e selecione Show In Finder.
7. Arraste GooglePlaces.bundle da pasta Resources para o projeto. Quando solicitado, verifique se Copy items into destination group's folder não está selecionado.
8. Selecione o projeto no Project Navigator e escolha o local de destino do aplicativo.
9. Abra a guia Fases de compilação e, em Vincular binário às bibliotecas, adicione os seguintes frameworks e bibliotecas:
   • CoreGraphics.framework
   • CoreLocation.framework
   • libc++.tbd
   • libz.tbd
   • QuartzCore.framework
   • UIKit.framework

10. Escolha seu projeto, em vez de um destino específico, e abra a guia Build Settings.

11. Na seção Outras sinalizações do vinculador, adicione -ObjC. Se essas configurações não estiverem visíveis, altere o filtro na barra Build Settings de Basic para All.

Instalar o XCFramework

Um XCFramework é um pacote binário que pode ser usado em várias plataformas, incluindo máquinas usando o chipset M1, para instalar o SDK do Places para iOS. Este guia mostra como adicionar o XCFramework que contém o SDK do Places para iOS ao projeto e definir as configurações de compilação no Xcode.

Com Cartago

O SDK do Places para iOS está disponível para uso com o Carthage, um gerenciador de dependências simples e descentralizado para projetos Cocoa em Swift e Objective-C.

1. Instale o Carthage. Existem vários métodos. Portanto, consulte o arquivo README do Carthage (em inglês) para ver as etapas exatas.
2. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o na sua máquina local. Se você é novo no desenvolvimento para iOS, crie um novo projeto e selecione o modelo de app para iOS.
3. Crie um arquivo chamado Cartfile no seu diretório do projeto Esse arquivo define as dependências do projeto.

4. Edite o Cartfile e adicione as dependências com as versões:

   binary "https://dl.google.com/geosdk/GooglePlaces.json" == 6.2.1-beta

5. Salve o Cartfile.

6. Em uma janela de terminal, acesse o diretório que contém Cartfile:

   cd <path-to-project>

7. Execute o comando carthage update. Isso instalará as APIs especificadas no Cartfile e as respectivas dependências.
8. No Finder, no diretório do projeto, acesse os arquivos de framework baixados em Carthage/Build.
9. Arraste o seguinte XCFramework para o projeto em Frameworks, Bibliotecas e Conteúdo incorporado. Selecione Não incorporar:
   • GooglePlaces-x.x.x/GooglePlaces.xcframework
10. Clique com o botão direito do mouse em GooglePlaces.xcframework no seu projeto e selecione Show In Finder.
11. Arraste GooglePlaces.bundle da pasta ios-arm64/GooglePlaces.framework/Resources para o diretório de nível superior do seu projeto Xcode. Quando solicitado, certifique-se de que a opção Copiar itens na pasta do grupo de destino não esteja selecionada.
12. Selecione seu projeto no Project Navigator e escolha o destino do aplicativo.
13. Abra a guia Fases de compilação e, em Vincular binário às bibliotecas, e adicione os seguintes frameworks e bibliotecas:
    • CoreGraphics.framework
    • CoreLocation.framework
    • libc++.tbd
    • libz.tbd
    • QuartzCore.framework
    • UIKit.framework

14. Escolha seu projeto, em vez de um destino específico, e abra a guia Build Settings.

15. Na seção Outras sinalizações do vinculador, adicione -ObjC. Se essas configurações não estiverem visíveis, altere o filtro na barra Build Settings de Basic para All.

Manualmente

Este guia mostra como adicionar manualmente o SDK do Maps para iOS ao projeto e definir as configurações de compilação no Xcode.

1. Faça o download dos arquivos de origem do SDK: GooglePlaces-8.0.0.
2. Descompacte-os. Navegue até a pasta Frameworks para acessar o XCFramework.
3. Inicie o Xcode e abra um projeto existente ou crie um novo. Se você é novo no iOS, crie um novo projeto e selecione o iOS App template.
4. Arraste o seguinte XCFramework para o projeto em Frameworks, Bibliotecas e Conteúdo incorporado. Selecione Não incorporar:
   • GooglePlaces-x.x.x/GooglePlaces.xcframework
5. Clique com o botão direito do mouse em GooglePlaces.xcframework no seu projeto e selecione Show In Finder.
6. Arraste GooglePlaces.bundle da pasta ios-arm64/GooglePlaces.framework/Resources para o diretório de nível superior do seu projeto Xcode. Quando solicitado, certifique-se de que a opção Copiar itens na pasta do grupo de destino não esteja selecionada.
7. Selecione seu projeto no Project Navigator e escolha o destino do aplicativo.
8. Abra a guia Fases de compilação e, em Vincular binário às bibliotecas, e adicione os seguintes frameworks e bibliotecas:
   • CoreGraphics.framework
   • CoreLocation.framework
   • libc++.tbd
   • libz.tbd
   • QuartzCore.framework
   • UIKit.framework

9. Escolha seu projeto, em vez de um destino específico, e abra a guia Build Settings.

10. Na seção Outras sinalizações do vinculador, adicione -ObjC. Se essas configurações não estiverem visíveis, altere o filtro na barra Build Settings de Basic para All.

Etapa 3: adicionar a chave de API ao app

Nos exemplos a seguir, substitua YOUR_API_KEY pela sua chave de API.

Swift

Inclua sua chave de API ao AppDelegate.swift da seguinte maneira:

• Adicione a seguinte instrução de importação:

  import GooglePlaces

• Adicione o seguinte ao método application(_:didFinishLaunchingWithOptions:), substituindo YOUR_API_KEY pela chave de API:

  GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

Inclua sua chave de API ao AppDelegate.m da seguinte maneira:

• Adicione a seguinte instrução de importação:

  @import GooglePlaces;

• Adicione o seguinte ao método application:didFinishLaunchingWithOptions:, substituindo YOUR_API_KEY pela chave de API:

  [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Etapa 4: começar a escrever o código

Os exemplos de código a seguir demonstram como acessar o lugar atual.

Observação: como essa amostra requer acesso à localização do dispositivo para determinar o local atual, é necessário definir a chave NSLocationWhenInUseUsageDescription com o texto explicativo adequado no arquivo Info.plist do projeto. Para mais detalhes, consulte o guia sobre como acessar o lugar atual.

Swift

import GooglePlaces
import UIKit

class GetStartedViewController : UIViewController {

  // Add a pair of UILabels in Interface Builder, and connect the outlets to these variables.
  @IBOutlet private var nameLabel: UILabel!
  @IBOutlet private var addressLabel: UILabel!

  private var placesClient: GMSPlacesClient!

  override func viewDidLoad() {
    super.viewDidLoad()
    placesClient = GMSPlacesClient.shared()
  }

  // Add a UIButton in Interface Builder, and connect the action to this function.
  @IBAction func getCurrentPlace(_ sender: UIButton) {
    let placeFields: GMSPlaceField = [.name, .formattedAddress]
    placesClient.findPlaceLikelihoodsFromCurrentLocation(withPlaceFields: placeFields) { [weak self] (placeLikelihoods, error) in
      guard let strongSelf = self else {
        return
      }

      guard error == nil else {
        print("Current place error: \(error?.localizedDescription ?? "")")
        return
      }

      guard let place = placeLikelihoods?.first?.place else {
        strongSelf.nameLabel.text = "No current place"
        strongSelf.addressLabel.text = ""
        return
      }

      strongSelf.nameLabel.text = place.name
      strongSelf.addressLabel.text = place.formattedAddress
    }
  }
}
      

Objective-C

#import "GetStartedViewController.h"
@import GooglePlaces;

@interface GetStartedViewController ()
// Add a pair of UILabels in Interface Builder and connect the outlets to these variables
@property (weak, nonatomic) IBOutlet UILabel *nameLabel;
@property (weak, nonatomic) IBOutlet UILabel *addressLabel;
@end

@implementation GetStartedViewController {
  GMSPlacesClient *_placesClient;
}

- (void)viewDidLoad {
  [super viewDidLoad];
  _placesClient = [GMSPlacesClient sharedClient];
}

// Add a pair of UILabels in Interface Builder and connect the outlets to these variables.
- (IBAction)getCurrentPlace:(UIButton *)sender {
  GMSPlaceField placeFields = (GMSPlaceFieldName | GMSPlaceFieldFormattedAddress);

  __weak typeof(self) weakSelf = self;
  [_placesClient findPlaceLikelihoodsFromCurrentLocationWithPlaceFields:placeFields callback:^(NSArray<GMSPlaceLikelihood *> * _Nullable likelihoods, NSError * _Nullable error) {
    __typeof__(self) strongSelf = weakSelf;
    if (strongSelf == nil) {
      return;
    }

    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    }

    GMSPlace *place = likelihoods.firstObject.place;
    if (place == nil) {
      strongSelf.nameLabel.text = @"No current place";
      strongSelf.addressLabel.text = @"";
      return;
    }

    strongSelf.nameLabel.text = place.name;
    strongSelf.addressLabel.text = place.formattedAddress;
  }];
}

@end
      

Próximas etapas

Depois de configurar o projeto, é possível explorar os apps de amostra. Você precisará do Cocoapods v1.6.1 instalado.