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

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

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.

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.

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

Configuração de LSApplicationQuerySchemes no 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: