Configurar um projeto do Xcode

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

As notas da versão estão disponíveis para cada lançamento.

Etapa 1: instalar o software necessário

Para criar um projeto usando o SDK do Maps para iOS, faça o download e instale:

• Xcode versão 15.0 ou mais recente

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

Observação: o SDK do Maps para iOS adiciona um tamanho médio de IPA de 5,7 MB para apps criados para dispositivos específicos. O tamanho de download de apps universais pode ser maior.

O tamanho da instalação do SDK pode variar. Por exemplo, o tamanho de instalação do SDK do Maps para iOS versão 9.0 é de cerca de 18 MB.

Observação: com a versão 9.2.0, o GoogleMapsCore e o GoogleMapsBase são consolidados no XCFramework do GoogleMaps. Não é necessário fazer nenhuma configuração extra.

Gerenciador de pacotes do Swift

O SDK do Maps para iOS pode ser instalado pelo Gerenciador de pacotes do Swift. Para adicionar o SDK, remova todas as dependências do SDK do Maps para iOS.

Importante: estas instruções pressupõem o uso do Xcode 15 ou mais recente, mas são semelhantes para versões anteriores do Xcode.

Para adicionar o SDK a um projeto novo ou existente, siga estas etapas:

1. Abra o Xcode project ou workspace e acesse File > Add Package Dependencies.
2. Insira https://github.com/googlemaps/ios-maps-sdk como o URL, pressione Enter para extrair o pacote e clique em "Adicionar pacote".
3. Para instalar um version específico, defina o campo Regra de dependência como uma das opções baseadas na versão. Para novos projetos, recomendamos especificar a versão mais recente e usar a opção "Versão exata". Quando terminar, clique em "Adicionar pacote".

Para atualizar o package de um projeto existente, siga estas etapas:

1. Se você estiver fazendo upgrade de uma versão anterior à 9.0.0, remova as seguintes dependências: GoogleMapsBase, GoogleMapsCore e GoogleMapsM4B após o upgrade. Não remova a dependência de GoogleMaps. Para mais informações, consulte as notas da versão 9.0.0.

   Nas configurações do projeto do Xcode, encontre Frameworks, bibliotecas e conteúdo incorporado. Use o sinal de menos(-) para remover o seguinte framework:

   • GoogleMapsBase (somente para upgrades de versões anteriores à 9.0.0)
   • GoogleMapsCore (somente para upgrades de versões anteriores à 9.0.0)
   • GoogleMapsM4B (somente para upgrades de versões anteriores à 9.0.0)
2. No Xcode, acesse "File > Packages > Update To Latest Package Versions".
3. Para verificar a instalação, acesse a seção Dependências do pacote do Project Navigator para verificar o pacote e a versão dele.

Importante:às vezes, os artefatos não podem ser resolvidos ou erros podem ocorrer. Nesse caso, selecione "File > Packages > Reset Package Cache".

Para remover as dependências do SDK do Maps para iOS adicionadas usando CocoaPods, siga estas etapas:

1. Feche o espaço de trabalho do Xcode. Abra o terminal e execute o seguinte comando:

   sudo gem install cocoapods-deintegrate cocoapods-clean 
   pod deintegrate 
   pod cache clean --all

2. Remova o Podfile, o Podfile.resolved e o workspace do Xcode se você não estiver usando-os para nada além do CocoaPods.

Para remover o SDK do Maps para iOS instalado manualmente, siga estas etapas:

1. Nas configurações do projeto do Xcode, encontre Frameworks, bibliotecas e conteúdo incorporado. Use o sinal de menos(-) para remover o seguinte framework:
   • GoogleMaps
   • GoogleMapsBase (somente para instalações anteriores à versão 9.2.0)
   • GoogleMapsCore (somente para instalações anteriores à versão 9.2.0)
   • GoogleMapsM4B (somente para instalações anteriores à versão 9.0.0)
2. No diretório de nível superior do projeto do Xcode, remova o pacote GoogleMaps.

Instalação manual

Neste guia, mostramos como adicionar manualmente o XCFrameworks que contém o SDK do Maps para iOS ao projeto e configurar as configurações de build no Xcode. Um XCFramework é um pacote binário que pode ser usado em várias plataformas, incluindo máquinas que usam Apple silicon.

1. Faça o download dos seguintes binários e arquivos de recursos do SDK:
   • GoogleMaps
   • GoogleMapsM4B
   • GoogleMapsResources
2. Extraia os arquivos para acessar os XCFrameworks e os recursos.
3. Se você ainda não tiver um projeto Xcode, crie um agora e salve-o no computador local. Se você não tem experiência com 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. Anote o valor do campo Identificador do pacote. Você pode usar esse valor para restringir sua chave de API abaixo.
      3. Defina a Interface do projeto como Storyboard.
      4. Defina Language como Swift ou Objective-C.
4. Abra a guia Geral. Arraste o seguinte XCFramework para o projeto em Frameworks, bibliotecas e conteúdo incorporado. Selecione Não incorporar:
   • GoogleMaps.xcframework
5. Copie o GoogleMaps.bundle do GoogleMapsResources que você fez o download no diretório de nível superior do projeto Xcode. Selecione Copiar itens para a pasta do grupo de destino quando solicitado.
6. Selecione o projeto no Project Navigator e escolha o destino do aplicativo.
7. Abra a guia Build phases do destino do app. Em Link Binary with Libraries, adicione os seguintes frameworks e bibliotecas:
   • Accelerate.framework
   • Contacts.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 (somente se você estiver usando o OpenGL)
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework

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

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

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 no computador local. Se você não tem experiência com 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. Anote o valor do campo Identificador do pacote. Você pode usar esse valor para restringir sua chave de API abaixo.
      3. Defina a Interface do projeto como Storyboard.
      4. Defina Language 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 as dependências com as versões. Confira 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, '16.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '9.4.0'
   end

   Execute pod outdated regularmente para detectar quando há uma versão mais recente e garantir que você sempre tenha 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 no Podfile para a versão mais recente.

Etapa 3: adicionar sua chave de API ao projeto

Em Gerar uma chave de API, você gerou uma chave de API para o app. Agora, adicione essa chave ao projeto do Xcode.

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

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

Swift

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

1. Adicione esta declaração import:

   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 maneira:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

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

1. Adicione esta declaração import:

   @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 maneira:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Etapa 4 (opcional): inspecionar o arquivo de manifesto de privacidade da Apple

Observação:as informações a seguir são relevantes quando você implanta o app na loja da Web.

A Apple exige detalhes de privacidade para apps na App Store. Acesse a página de Detalhes de privacidade da Apple App Store para conferir atualizações e mais informações.

O arquivo de manifesto de privacidade da Apple está incluído no pacote de recursos do SDK. Para verificar se o arquivo de manifesto de privacidade foi incluído e inspecionar o conteúdo dele, crie um arquivo do seu app e gere um relatório de privacidade com base nele.

Etapa 5 (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 do app. O SDK do Maps para iOS abre o app Google Maps para dispositivos móveis quando o usuário clica no logotipo do Google no mapa. Assim, seu app pode declarar os esquemas de URL relevantes.

Para declarar os esquemas de URL usados pelo SDK do Maps para iOS, adicione as linhas a seguir ao 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.

A seguir

Agora que você tem uma chave de API e um projeto do Xcode, já pode criar e executar apps. O SDK Navigation para iOS oferece vários tutoriais e apps de exemplo que podem ajudar você a começar. Confira mais detalhes em:

• Os tutoriais a seguir são pontos de partida recomendados:
  • Adicionar um mapa com um marcador.
  • Selecionar o lugar atual e mostrar detalhes em um mapa.
  • Geocodificação inversa.
• Confira os exemplos de código e os codelabs disponíveis.
• Para soluções completas, consulte as soluções do Maps disponíveis.