Configurar um projeto do Xcode

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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

    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:

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: