Primeiros passos

Antes de começar a trabalhar com o Google Maps no iOS, é necessário baixar o Google Maps SDK for iOS e ter uma chave de API.

As notas da versão completas estão disponíveis para cada versão.

Se você estiver usando o Google Maps SDK for iOS com uma licença do Google Maps APIs Premium Plan, consulte o guia de primeiros passos do [Premium Plan.[premium-start]

Início rápido: Execute pod try GoogleMaps para experimentar o aplicativo de demonstração do SDK. Para saber mais, consulte o guia de exemplos de código.

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

Para compilar um projeto usando o Google Maps SDK for iOS, é preciso usar a versão 7.3 ou posterior do Xcode.

Etapa 2: instalar o SDK

Usar CocoaPods

A Google Maps SDK for iOS está disponível como um pod do CocoaPods. 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.

sudo gem install cocoapods

Crie um Podfile para a Google Maps SDK for iOS e use-o para instalar a API e suas dependências:

1. Se ainda não tiver um projeto Xcode, crie um agora e salve-o no computador local. (Se você tem pouca experiência com desenvolvimento para iOS, crie um Single View Application)
2. Crie um arquivo chamado Podfile no diretório do projeto. Esse arquivo define as dependências do projeto.
3. Edite o Podfile e adicione suas dependências. Veja um exemplo que contém as dependências necessárias para o Google Maps SDK for iOS e a Places API for iOS (opcional):

   source 'https://github.com/CocoaPods/Specs.git'
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps'
     pod 'GooglePlaces'
   end

   Os clientes do Plano premium também devem adicionar o pod “GoogleMaps/M4B”.

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. Assim, você instalará as APIs especificadas no Podfile junto com as respectivas dependências.

   pod install

7. Feche o Xcode e clique duas vezes para abrir o arquivo .xcworkspace do projeto e iniciar o Xcode. A partir desse momento, será preciso usar o arquivo .xcworkspace para abrir o projeto.

Instalar manualmente

Este guia mostra como adicionar a estrutura GoogleMaps ao projeto e ajustar as configurações de compilação no Xcode.

1. Baixe os arquivos de origem do SDK: GoogleMaps-2.0.1.
2. Descompacte os arquivos de origem.
3. Inicialize o Xcode e abra ou crie um projeto. Se você tem pouca experiência com o iOS, crie um Single View Application, desative Use Storyboards e ative Use Automatic Reference Counting.
4. Arraste os pacotes a seguir para o seu projeto (quando aparecer a tela de confirmação, selecione Copy items if needed):
   • Subspecs/Base/Frameworks/GoogleMapsBase.framework
   • Subspecs/Maps/Frameworks/GoogleMaps.framework
   • Subspecs/Maps/Frameworks/GoogleMapsCore.framework

   Os clientes do Plano premium também deve incluir Subspecs/M4B/Frameworks/GoogleMapsM4B.framework.

5. Clique com o botão direito em GoogleMaps.framework no projeto e selecione Show In Finder.
6. Arraste GoogleMaps.bundle da pasta Resources para o seu projeto. Quando aparecer a tela de confirmação, certifique-se de que a opção Copy items into destination group’s folder não esteja selecionada.
7. Selecione o projeto no Project Navigator e escolha o local de destino do aplicativo.
8. Abra a guia Build Phases e, dentro de Link Binary with Libraries, adicione os seguintes frameworks:
   • GoogleMapsBase.framework
   • GoogleMaps.framework
   • GoogleMapsCore.framework
   • GoogleMapsM4B.framework (apenas clientes do Plano premium)
   • Accelerate.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreLocation.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • OpenGLES.framework
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

9. Escolha o 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 da barra Build Settings de Basic para All.

10. Para instalar a Places API for iOS, dê uma olhada em Primeiros passos com a Places API for iOS.

Etapa 4: obter uma chave de API

Clique no botão abaixo para acessar um guia do processo de ativação do Google Maps SDK for iOS e obtenção de uma chave de API. Se o seu projeto já tem uma chave de API restrita ao iOS, você use-a.

Obter uma chave

Como alternativa, siga as etapas a seguir para obter uma chave de API:

1. Acesse o Google API Console.
2. Crie ou selecione um projeto.
3. Clique em Continue para ativar o Google Maps SDK for iOS.
4. Na página Credentials, obtenha uma chave de API.
   Observação: Se você tem uma chave restrita ao iOS, use-a. É possível usar a mesma chave com todos os aplicativos iOS dentro do mesmo projeto.
5. Na caixa de diálogo que exibe a chave de API, selecione Restrict key para adicionar uma restrição para iOS à chave de API.
6. Na seção Restrictions, selecione iOS apps e digite o identificador geral do seu aplicativo. Por exemplo: com.example.hellomap.
7. Clique em Save.

   A nova chave de API restrita ao iOS aparece na lista de chaves de API do projeto. Uma chave de API é uma string de caracteres, similar a:

   AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0

Também é possível procurar uma chave existente no Google API Console.

Para saber mais sobre como usar o Google API Console, consulte a Ajuda do API Console.

Etapa 5: adicionar a chave de API ao aplicativo

Swift

Adicione a chave de API a AppDelegate.swift da seguinte maneira:

1. Adicione a seguinte declaração import:

   import GoogleMaps

2. Adicione o seguinte ao método application(_:didFinishLaunchingWithOptions:), substituindo YOUR_API_KEY por sua chave de API:

   GMSServices.provideAPIKey("YOUR_API_KEY")

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

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

Adicione a chave de API a AppDelegate.m da seguinte maneira:

1. Adicione a seguinte declaração import:

   @import GoogleMaps;

2. Adicione o seguinte ao método application:didFinishLaunchingWithOptions:, substituindo YOUR_API_KEY por sua chave de API:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

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

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Etapa 6: adicionar um mapa

O código abaixo demonstra como adicionar um mapa simples a um ViewController. Se estiver criando um novo mapa, comece seguindo as instruções de instalação acima e crie um novo Single View Application, desativando Use Storyboards, mas ativando Use Automatic Reference Counting (ARC).

Agora, adicione ou atualize alguns métodos no ViewController padrão do seu aplicativo para criar e inicializar uma instância de GMSMapView.

Swift

import UIKit
import GoogleMaps

class YourViewController: UIViewController {

  // You don't need to modify the default init(nibName:bundle:) method.

  override func loadView() {
    // 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: CGRect.zero, camera: camera)
    mapView.isMyLocationEnabled = true
    view = 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

#import "YourViewController.h"
#import <GoogleMaps/GoogleMaps.h>

@implementation YourViewController

// You don't need to modify the default initWithNibName:bundle: method.

- (void)loadView {
  // 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:CGRectZero camera:camera];
  mapView.myLocationEnabled = YES;
  self.view = 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

Substitua todas as instâncias de YourViewController do exemplo acima pelo nome do seu controlador de visualizações.

Execute o aplicativo. Você deve ver um mapa com um marcador centralizado em Sydney, Austrália. Se o marcador for exibido, mas o mapa, não, verifique se você forneceu a chave de API.

Etapa 7: declarar os esquemas de URL usados pela API

A partir do iOS 9 e do Xcode 7, os aplicativos precisam declarar os esquemas de URL que pretendem abrir, especificando-os no arquivo Info.plist do aplicativo. O Google Maps SDK for iOS abre o aplicativo para dispositivos móveis do Google Maps quando o usuário clica no logotipo do Google no mapa. Portanto, o aplicativo precisa declarar os esquemas de URL relevantes.

Para declarar os esquemas de URL usados pelo Google Maps SDK for 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 erros a seguir ocorrem 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 como descrito acima.

Experimentar o projeto de demonstração do Google Maps SDK

Experimente as demonstrações do SDK usando pod try GoogleMaps. Para saber mais, consulte o guia de exemplos de código.

Atualizar de uma versão anterior

Siga estas instruções para atualizar um projeto existente para a versão mais recente do Google Maps SDK for iOS.

Observação: As versões 1.9.2 e anteriores da Google Maps SDK for iOS eram disponibilizadas como um arquivo zip contendo uma estrutura de trabalho estática. Além disso, existia a opção de instalar versões recentes de um pod do CocoaPods. A partir da versão 1.10.0, o Google Maps SDK for iOS está disponível para instalação apenas por meio do CocoaPods.

Se você já instalou o Google Maps SDK for iOS de um arquivo zip contendo uma estrutura de trabalho estática:

1. Remova todas as referências ao framework de trabalho anterior do projeto Xcode.
2. Siga as instruções da observação acima para instalar o Google Maps SDK for iOS usando o CocoaPods.
3. Faça as alterações necessárias para o upgrade. Consulte as notas de versão para obter uma lista das alterações em cada versão.
4. Limpe e recompile o projeto selecionando Product > Clean e Product > Build.

Se você já instalou o Google Maps SDK for iOS do pod do Google-Maps-iOS-SDK:

1. Altere o nome do pod para GoogleMaps.
2. Execute pod install.
3. Faça as alterações necessárias para o upgrade. Consulte as notas de versão para obter uma lista das alterações em cada versão.
4. Limpe e recompile o projeto selecionando Product > Clean e Product > Build.

Se você já instalou o Google Maps SDK for iOS do pod do GoogleMaps:

1. Verifique se há qualquer limitador de versão no Podfile e não deixe de remover ou atualizar a versão para garantir a obtenção da versão necessária. Consulte as notas de versão para obter uma lista dos números de versão.
2. Execute pod update.
3. Faça as alterações necessárias para o upgrade. Consulte as notas de versão para obter uma lista das alterações em cada versão.
4. Limpe e recompile o projeto selecionando Product > Clean e Product > Build.