Configurar um projeto do Xcode

Depois de ativar o faturamento e criar uma chave de API, você estará pronto para configurar o projeto do Xcode que você usa para desenvolver seu app.

Etapa 1: instalar o software necessário

Se você quiser criar um projeto usando o SDK do Maps para iOS, faça o download e instale o seguinte:

• Xcode versão 13.0 ou mais recente

• Cocoapods ou Carthage

  Observação : embora seja possível instalar manualmente o SDK do Maps para iOS sem usar Cocoapods ou Carthage, a maioria dos desenvolvedores prefere usar um gerenciador de pacotes.

Etapa 2: criar o projeto Xcode e instalar o SDK do Maps para iOS

Usar o CocoaPods

O SDK do Maps para iOS está disponível como um pod do CocoaPods (em inglês). O CocoaPods é um gerenciador de dependências de código aberto para projetos Cocoa em Swift e Objective-C.

Se você ainda não tem essa ferramenta, instale-a no macOS executando o seguinte comando no terminal. Para saber mais, consulte o Guia de primeiros passos do CocoaPods (em inglês).

sudo gem install cocoapods

Crie um Podfile para o SDK do Maps para iOS e instale a API e as dependências dela:

1. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o na máquina local. Se você não tem experiência com o desenvolvimento para iOS:
   1. Crie um novo projeto.
   2. Selecione o modelo iOS > App.
   3. Na tela de opções do projeto:
      1. Digite o Nome do projeto.
      2. Registre o valor do campo Identificador do pacote. Use esse valor para restringir sua chave de API abaixo.
      3. Defina a Interface do projeto como Storyboard.
      4. Defina o Idioma como Swift ou Objective-C.
2. Crie um arquivo chamado Podfile no seu diretório do projeto para definir as dependências.
3. Edite o Podfile e adicione suas dependências com as versões. Veja um exemplo que inclui a dependência necessária para o SDK do Maps para iOS:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '13.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '7.4.0'
   end
   

   Execute o pod outdated regularmente para detectar quando houver uma versão mais recente e garantir que você tenha sempre a versão mais recente. Se necessário, faça upgrade para a versão 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 vai atualizar todas as APIs especificadas em Podfile para a versão mais recente.

Usar Cartago

Observação : no momento, o Carthage não oferece suporte a bibliotecas criadas para uma versão mínima do iOS 13 ou mais recente. Isso significa que a versão mais recente compatível do SDK do Maps para iOS é a 6.2.1.

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

1. Instale o Carthage. Como há vários métodos, consulte o arquivo README do Carthage para ver as etapas exatas.
2. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o na máquina local. Se você não tem experiência com o desenvolvimento para iOS:
   1. Crie um novo projeto.
   2. Selecione o modelo iOS > App.
   3. Na tela de opções do projeto:
      1. Digite o Nome do projeto.
      2. Registre o valor do campo Identificador do pacote. Use esse valor para restringir sua chave de API abaixo.
      3. Defina a Interface do projeto como Storyboard.
      4. Defina o Idioma como Swift ou Objective-C.
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 suas dependências com as versões:
   

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

   Execute o carthage outdated regularmente para detectar quando houver uma versão mais recente e garantir que você tenha sempre a versão mais recente. Se necessário, faça upgrade para a versão mais recente.
5. Salve o Cartfile.
6. Em uma janela de terminal, acesse o diretório que contém o 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 salvos em Carthage/Build/iOS.
9. Arraste os pacotes a seguir para o projeto: quando solicitado, selecione Copy items if needed, use the same version as above.
   • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.xcframework
   • (Apenas para clientes do plano Premium) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.xcframework
10. Clique com o botão direito do mouse em GoogleMaps.xcframework no projeto e selecione Show In Finder.
11. Arraste GoogleMaps.bundle da pasta Resources para o diretório de nível superior do projeto Xcode. Quando solicitado, verifique se a opção Copiar itens na pasta do grupo de destino não está selecionada.
12. Selecione o projeto no Project Navigator e escolha o local de destino do aplicativo.
13. Abra a guia Fases de compilação para o destino do seu aplicativo e, em Vincular binário com bibliotecas, adicione os seguintes frameworks e bibliotecas:
    • Accelerate.framework
    • CoreData.framework
    • CoreGraphics.framework
    • CoreImage.framework
    • CoreLocation.framework
    • CoreTelephony.framework
    • CoreText.framework
    • GLKit.framework
    • ImageIO.framework
    • libc++.tbd
    • libz.tbd
    • Metal.framework
    • OpenGLES.framework
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework

14. Escolha seu projeto, em vez de um destino específico, e abra a guia Build Settings. Na seção Other Linker Flags, adicione -ObjC. Se essas configurações não estiverem visíveis, altere o filtro na barra Build Settings de Basic para All.

15. Para instalar o SDK do Places para iOS, consulte Primeiros passos com o SDK do Places para iOS.

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 vai atualizar todas as APIs especificadas no Cartfile para a versão mais recente.

Instalar manualmente

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

1. Faça o download dos arquivos de origem do SDK: GoogleMaps-7.4.0.
2. Descompacte-os.
3. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o na máquina local. Se você não tem experiência com o desenvolvimento para iOS:
   1. Crie um novo projeto.
   2. Selecione o modelo iOS > App.
   3. Na tela de opções do projeto:
      1. Digite o Nome do projeto.
      2. Registre o valor do campo Identificador do pacote. Use esse valor para restringir sua chave de API abaixo.
      3. Defina a Interface do projeto como Storyboard.
      4. Defina o Idioma como Swift ou Objective-C.
4. Arraste os pacotes a seguir para o projeto: quando solicitado, selecione Copy items if needed, use the same version as above.
   • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.xcframework
   • (Apenas para clientes do plano Premium) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.xcframework
5. Clique com o botão direito do mouse em GoogleMaps.xcframework no projeto e selecione Show In Finder.
6. Arraste GoogleMaps.bundle da pasta Resources para o diretório de nível superior do projeto Xcode. Quando solicitado, verifique se a opção Copiar itens na pasta do grupo de destino não está selecionada.
7. Selecione o projeto no Project Navigator e escolha o local de destino do aplicativo.
8. Abra a guia Fases de compilação para o destino do seu aplicativo e, em Vincular binário com bibliotecas, adicione os seguintes frameworks e bibliotecas:
   • Accelerate.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

9. Escolha seu projeto, em vez de um destino específico, e abra a guia Build Settings. Na seção Other Linker Flags, adicione -ObjC. Se essas configurações não estiverem visíveis, altere o filtro na barra Build Settings de Basic para All.

10. Para instalar o SDK do Places para iOS, consulte Primeiros passos com o SDK do Places para iOS.

Instalar o XCFramework

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

Com cartilagem

O SDK do Maps 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. Como há vários métodos, consulte o arquivo README do Carthage para ver as etapas exatas.
2. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o na máquina local. Se você não tem experiência com o desenvolvimento para iOS:
   1. Crie um novo projeto.
   2. Selecione o modelo iOS > App.
   3. Na tela de opções do projeto:
      1. Digite o Nome do projeto.
      2. Registre o valor do campo Identificador do pacote. Use esse valor para restringir sua chave de API abaixo.
      3. Defina a Interface do projeto como Storyboard.
      4. Defina o Idioma como Swift ou Objective-C.
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 suas dependências com as versões:

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

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

   cd <path-to-project>

7. Execute o comando carthage update. Isso vai instalar as APIs especificadas em Cartfile e as dependências que elas tiverem.
8. No Finder, no diretório do projeto, acesse os arquivos de framework salvos em Carthage/Build.
9. Arraste os XCFrameworks a seguir para seu projeto em Frameworks, Bibliotecas e Conteúdo incorporado. Selecione Não incorporar para cada XCFramework:
   • GoogleMaps-x.x.x/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/GoogleMapsCore.xcframework
   • (Apenas para clientes do plano Premium) GoogleMaps-x.x.x/GoogleMapsM4B.xcframework
10. Clique com o botão direito do mouse em GoogleMaps.xcframework no projeto e selecione Show In Finder.
11. Arraste GoogleMaps.bundle da pasta ios-arm64_x86_64-simulator/GoogleMaps.framework/Resources para o diretório de nível superior do projeto Xcode. Quando solicitado, verifique se a opção Copiar itens, se necessário não está selecionada.
12. Selecione o projeto no navegador de projetos e escolha o destino do aplicativo.
13. Abra a guia Fases de compilação para o destino do seu aplicativo e em Vincular binário com bibliotecas e adicione os seguintes frameworks e bibliotecas:
    • Accelerate.framework
    • CoreData.framework
    • CoreGraphics.framework
    • CoreImage.framework
    • CoreLocation.framework
    • CoreTelephony.framework
    • CoreText.framework
    • GLKit.framework
    • ImageIO.framework
    • libc++.tbd
    • libz.tbd
    • Metal.framework
    • OpenGLES.framework
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework

14. Escolha seu projeto, em vez de um destino específico, e abra a guia Build Settings. Na seção Outras sinalizações do vinculador, adicione -ObjC. Se essas configurações não estiverem visíveis, mude o filtro na barra Build Settings de Basic para All.

15. Se quiser instalar o XCFramework do SDK do Places para iOS, consulte Primeiros passos com o SDK do Places para iOS.

Manualmente

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

1. Faça o download dos arquivos de origem do SDK: GoogleMaps-7.4.0.
2. Descompacte-os. Navegue até a pasta Frameworks para acessar o XCFramework.
3. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o na máquina local. Se você não tem experiência com o desenvolvimento para iOS:
   1. Crie um novo projeto.
   2. Selecione o modelo iOS > App.
   3. Na tela de opções do projeto:
      1. Digite o Nome do projeto.
      2. Registre o valor do campo Identificador do pacote. Use esse valor para restringir sua chave de API abaixo.
      3. Defina a Interface do projeto como Storyboard.
      4. Defina o Idioma como Swift ou Objective-C.
4. Arraste os XCFrameworks a seguir para seu projeto em Frameworks, Bibliotecas e Conteúdo incorporado. Selecione Não incorporar para cada XCFramework:
   • GoogleMaps-x.x.x/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/GoogleMapsCore.xcframework
   • (Apenas para clientes do plano Premium) GoogleMaps-x.x.x/GoogleMapsM4B.xcframework
5. Clique com o botão direito do mouse em GoogleMaps.xcframework no projeto e selecione Show In Finder.
6. Arraste GoogleMaps.bundle da pasta ios-arm64_x86_64-simulator/GoogleMaps.framework/Resources para o diretório de nível superior do projeto Xcode. Quando solicitado, verifique se a opção Copiar itens, se necessário não está selecionada.
7. Selecione o projeto no navegador de projetos e escolha o destino do aplicativo.
8. Abra a guia Fases de compilação para o destino do seu aplicativo e em Vincular binário com bibliotecas e adicione os seguintes frameworks e bibliotecas:
   • Accelerate.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • OpenGLES.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

9. Escolha seu projeto, em vez de um destino específico, e abra a guia Build Settings. Na seção Outras sinalizações do vinculador, adicione -ObjC. Se essas configurações não estiverem visíveis, mude o filtro na barra Build Settings de Basic para All.

10. Se quiser instalar o XCFramework do SDK do Places para iOS, consulte Primeiros passos com o SDK do Places para iOS.

Etapa 3: adicionar sua chave de API ao projeto

Em Gerar uma chave de API, você gerou uma chave de API para seu app. Agora, adicione-a ao seu projeto do Xcode.

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

Observação :se você gravou o identificador do pacote do seu projeto ou o usou nas propriedades do projeto, é possível usá-lo para restringir a chave de API para uso somente em apps iOS com esse identificador específico do pacote. Consulte Como restringir chaves de API para mais informações.

Swift

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

1. Adicione a seguinte instrução de importação:

   import GoogleMaps

2. Adicione o seguinte ao método application(_:didFinishLaunchingWithOptions:) usando sua chave de API:

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. Se você também estiver usando a API Places, adicione a chave novamente da seguinte forma:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

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

1. Adicione a seguinte instrução de importação:

   @import GoogleMaps;

2. Adicione o seguinte ao método application:didFinishLaunchingWithOptions: usando sua chave de API:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. Se você também estiver usando a API Places, adicione a chave novamente da seguinte forma:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Etapa 4 (opcional): ativar o uso do framework de renderização do Metal

O SDK do Maps para iOS permite ativar o framework de renderização Metal da Apple. Para testar o renderizador Metal no seu app, chame [GMSServices setMetalRendererEnabled:YES] em Objective-C ou GMSServices.setMetalRendererEnabled(true) em Swift antes de criar visualizações de mapa.

Se você estiver instalando o SDK manualmente, adicione Metal.framework no Xcode.

Etapa 5: adicionar um mapa

O código abaixo demonstra como adicionar um mapa simples a um ViewController existente:

1. Adicione ou atualize métodos no ViewController padrão do seu app para criar e inicializar uma instância de GMSMapView.

   Substitua todas as instâncias de ViewController no código de exemplo pelo nome do seu controlador de visualização.

   Swift

   /*
    * Copyright 2020 Google Inc. All rights reserved.
    *
    *
    * 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 UIKit
   import GoogleMaps
   
   class ViewController: UIViewController {
   
       override func viewDidLoad() {
           super.viewDidLoad()
           // Do any additional setup after loading the view.
           // Create a GMSCameraPosition that tells the map to display the
           // coordinate -33.86,151.20 at zoom level 6.
           let camera = GMSCameraPosition.camera(withLatitude: -33.86, longitude: 151.20, zoom: 6.0)
           let mapView = GMSMapView.map(withFrame: self.view.frame, camera: camera)
           self.view.addSubview(mapView)
   
           // Creates a marker in the center of the map.
           let marker = GMSMarker()
           marker.position = CLLocationCoordinate2D(latitude: -33.86, longitude: 151.20)
           marker.title = "Sydney"
           marker.snippet = "Australia"
           marker.map = mapView
     }
   }
   
         

   Objective-C

   /*
   * Copyright 2020 Google Inc. All rights reserved.
   *
   *
   * 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 "ViewController.h"
   #import <GoogleMaps/GoogleMaps.h>
   
   @interface ViewController ()
   
   @end
   
   @implementation ViewController
   
   - (void)viewDidLoad {
       [super viewDidLoad];
     // Do any additional setup after loading the view.
     // Create a GMSCameraPosition that tells the map to display the
     // coordinate -33.86,151.20 at zoom level 6.
     GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:-33.86
                                                             longitude:151.20
                                                                  zoom:6];
     GMSMapView *mapView = [GMSMapView mapWithFrame:self.view.frame camera:camera];
     mapView.myLocationEnabled = YES;
     [self.view addSubview:mapView];
   
     // Creates a marker in the center of the map.
     GMSMarker *marker = [[GMSMarker alloc] init];
     marker.position = CLLocationCoordinate2DMake(-33.86, 151.20);
     marker.title = @"Sydney";
     marker.snippet = @"Australia";
     marker.map = mapView;
   }
   
   @end
   ViewController.m
         

2. Execute o aplicativo. Você verá um mapa com um único marcador centralizado em Sydney, Austrália. Se você consegue ver o marcador, mas o mapa não está visível, confirme se você informou a chave de API.

Etapa 6 (opcional): declarar os esquemas de URL usados pela API

A partir do iOS 9 e do Xcode 7, os apps podem declarar os esquemas de URL que pretendem abrir, especificando os esquemas no arquivo Info.plist. Quando o usuário clica no logotipo do Google no mapa, o SDK do Maps para iOS abre o app para dispositivos móveis, e o app pode declarar os esquemas de URL relevantes.

Para declarar os esquemas de URL usados pelo SDK do Maps para iOS, adicione as seguintes linhas ao seu Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>googlechromes</string>
    <string>comgooglemaps</string>
</array>

A captura de tela abaixo mostra a configuração na interface do usuário do Xcode:

Sem a declaração acima, os seguintes erros podem ocorrer quando o usuário toca no logotipo do Google no mapa:

-canOpenURL: failed for URL: "comgooglemaps://" - error: "This app is not allowed to query for scheme comgooglemaps"
-canOpenURL: failed for URL: "googlechromes://" - error: "This app is not allowed to query for scheme googlechromes"

Para eliminar esses erros, adicione a declaração ao Info.plist, conforme descrito acima.

A seguir

Agora que você tem uma chave de API e um projeto do Xcode, é possível criar e executar apps. O SDK do Maps para iOS oferece muitos tutoriais e apps de exemplo que podem ajudar você a começar. Confira mais detalhes em:

• Exemplos de código
• Tutoriais
  • Adicionar um mapa com um marcador
  • Selecionar o lugar atual e mostrar detalhes em um mapa
  • Geocodificação inversa
• Codelabs
• Soluções do Maps