Configurare un progetto Xcode

Dopo aver attivato la fatturazione e creato una chiave API, puoi configurare il progetto Xcode che utilizzi per sviluppare l'app.

Passaggio 1: installa il software richiesto

Per creare un progetto con l'SDK Maps per iOS, devi scaricare e installare:

  • Xcode 13.0 o versioni successive
  • Cocoapods o Cartagine

Passaggio 2. Crea il progetto XCode e installa l'SDK Maps per iOS

Utilizzare CocoaPods

L'SDK Maps per iOS è disponibile come pod CocoaPods. CocoaPods è un gestore di dipendenze open source per progetti Cocoa Swift e Objective-C.

Se non hai ancora lo strumento CocoaPods, installalo su macOS eseguendo il comando seguente dal terminale. Per maggiori dettagli, consulta la Guida introduttiva a CocoaPods.

sudo gem install cocoapods

Crea un Podfile per l'SDK Maps per iOS e utilizzalo per installare l'API e le sue dipendenze:

  1. Se non hai ancora un progetto Xcode, creane uno e salvalo sulla tua macchina locale. Se è la prima volta che sviluppi iOS:
    1. Crea un nuovo progetto.
    2. Seleziona il modello iOS > App.
    3. Nella schermata delle opzioni del progetto:
      1. Inserisci il Nome progetto.
      2. Registra il valore del campo Identificatore pacchetto. Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta il progetto Interface su Storyboard.
      4. Imposta la Lingua su Swift o Objective-C.
  2. Crea un file denominato Podfile nella directory del progetto. Questo file definisce le dipendenze del progetto.
  3. Modifica il Podfile e aggiungi le tue dipendenze insieme alle relative versioni. Ecco un esempio che include la dipendenza di cui hai bisogno per Maps SDK for iOS:
    source 'https://github.com/CocoaPods/Specs.git'
    
    platform :ios, '13.0'
    
    target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
      pod 'GoogleMaps', '7.2.0'
    end
    Assicurati di eseguire regolarmente pod outdated per rilevare quando è disponibile una versione più recente per assicurarti di essere sempre aggiornato. Se necessario, esegui l'upgrade alla versione più recente.
  4. Salva il Podfile.
  5. Apri un terminale e vai alla directory contenente Podfile:

    cd <path-to-project>
  6. Esegui il comando pod install. Verranno installate le API specificate in Podfile, insieme alle eventuali dipendenze che potrebbero avere.

    pod install
  7. Chiudi Xcode, quindi apri (fai doppio clic) sul file .xcworkspace del progetto per avviare Xcode. Da quel momento in poi, dovrai utilizzare il file .xcworkspace per aprire il progetto.

Per aggiornare l'API per un progetto esistente:

  1. Apri un terminale e vai alla directory del progetto contenente Podfile.
  2. Esegui il comando pod update. Tutte le API specificate in Podfile verranno aggiornate all'ultima versione.

Usa Cartagine

L'SDK Maps per iOS può essere utilizzato con Carthage, un semplice gestore decentralizzato delle dipendenze per i progetti Swift e Objective-C Cocoa.

  1. Installare Cartagine. Esistono diversi metodi, quindi consulta il file README di Cartagine per i passaggi esatti.
  2. Se non hai ancora un progetto Xcode, creane uno e salvalo sulla tua macchina locale. Se è la prima volta che sviluppi iOS:
    1. Crea un nuovo progetto.
    2. Seleziona il modello iOS > App.
    3. Nella schermata delle opzioni del progetto:
      1. Inserisci il Nome progetto.
      2. Registra il valore del campo Identificatore pacchetto. Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta il progetto Interface su Storyboard.
      4. Imposta la Lingua su Swift o Objective-C.
  3. Crea un file denominato Cartfile nella directory del progetto. Questo file definisce le dipendenze del progetto.
  4. Modifica il Cartfile e aggiungi le tue dipendenze insieme alle relative versioni:
    binary "https://dl.google.com/geosdk/GoogleMaps.json" == 6.2.1
    Assicurati di eseguire regolarmente carthage outdated per rilevare quando è disponibile una versione più recente e assicurarti di essere sempre aggiornato. Se necessario, esegui l'upgrade alla versione più recente.
  5. Salva il Cartfile.
  6. In una finestra del terminale, vai alla directory contenente Cartfile:
    cd <path-to-project>
  7. Esegui il comando carthage update. Verranno installate le API specificate in Cartfile, insieme alle eventuali dipendenze che potrebbero avere.
  8. Nel Finder, nella directory del progetto, vai ai file del framework scaricati in Carthage/Build/iOS.
  9. Trascina i seguenti pacchetti nel progetto: (quando richiesto, seleziona Copia elementi, se necessario, utilizza la stessa versione indicata sopra.)
    • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.framework
    • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.framework
    • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.framework
    • (Solo clienti con piano Premium) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.framework
  10. Fai clic con il tasto destro del mouse su GoogleMaps.framework nel progetto e seleziona Mostra nel Finder.
  11. Trascina GoogleMaps.bundle dalla cartella Resources nella directory di primo livello del tuo progetto Xcode. Quando richiesto, assicurati che l'opzione Copia elementi nella cartella del gruppo di destinazione non sia selezionata.
  12. Seleziona il progetto nel navigatore dei progetti e scegli la destinazione dell'applicazione.
  13. Apri la scheda Fasi di creazione per la destinazione dell'applicazione e, in Collega binaria con librerie, aggiungi i seguenti framework e librerie:
    • 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. Scegli il progetto, anziché un target specifico, e apri la scheda Impostazioni build. Nella sezione Altri flag del linker, aggiungi -ObjC. Se queste impostazioni non sono visibili, modifica il filtro nella barra Impostazioni build da Di base a Tutte.

  15. Per installare l'SDK Places per iOS, consulta la guida introduttiva all'SDK Places per iOS.

Per aggiornare l'API per un progetto esistente:

  1. Apri un terminale e vai alla directory del progetto contenente Cartfile.
  2. Esegui il comando carthage update. Tutte le API specificate in Cartfile verranno aggiornate alla versione più recente.

Installazione manuale

Questa guida mostra come aggiungere manualmente l'SDK Maps per iOS al tuo progetto e configurare le impostazioni di build in Xcode.

  1. Scarica i file di origine dell'SDK: Google Maps-7.2.0.
  2. Apri i file di origine.
  3. Se non hai ancora un progetto Xcode, creane uno e salvalo sulla tua macchina locale. Se è la prima volta che sviluppi iOS:
    1. Crea un nuovo progetto.
    2. Seleziona il modello iOS > App.
    3. Nella schermata delle opzioni del progetto:
      1. Inserisci il Nome progetto.
      2. Registra il valore del campo Identificatore pacchetto. Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta il progetto Interface su Storyboard.
      4. Imposta la Lingua su Swift o Objective-C.
  4. Trascina i seguenti pacchetti nel progetto: (quando richiesto, seleziona Copia elementi, se necessario, utilizza la stessa versione indicata sopra.)
    • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.framework
    • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.framework
    • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.framework
    • (Solo clienti con piano Premium) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.framework
  5. Fai clic con il tasto destro del mouse su GoogleMaps.framework nel progetto e seleziona Mostra nel Finder.
  6. Trascina GoogleMaps.bundle dalla cartella Resources nella directory di primo livello del tuo progetto Xcode. Quando richiesto, assicurati che l'opzione Copia elementi nella cartella del gruppo di destinazione non sia selezionata.
  7. Seleziona il progetto nel navigatore dei progetti e scegli la destinazione dell'applicazione.
  8. Apri la scheda Fasi di creazione per la destinazione dell'applicazione e, in Collega binaria con librerie, aggiungi i seguenti framework e librerie:
    • 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. Scegli il progetto, anziché un target specifico, e apri la scheda Impostazioni build. Nella sezione Altri flag del linker, aggiungi -ObjC. Se queste impostazioni non sono visibili, modifica il filtro nella barra Impostazioni build da Di base a Tutte.

  10. Per installare l'SDK Places per iOS, consulta la guida introduttiva all'SDK Places per iOS.

Installa XCFramework

Un XCFramework è un pacchetto binario che puoi utilizzare su più piattaforme, incluse le macchine che utilizzano il chipset M1, per installare l'SDK Maps per iOS. Questa guida mostra come aggiungere al tuo progetto l'XCFramework contenente l'SDK Maps per iOS e configurare le impostazioni della build in Xcode.

Con Cartagine

L'SDK Maps per iOS può essere utilizzato con Carthage, un semplice gestore decentralizzato delle dipendenze per i progetti Swift e Objective-C Cocoa.

  1. Installare Cartagine. Esistono diversi metodi, quindi consulta il file README di Cartagine per i passaggi esatti.
  2. Se non hai ancora un progetto Xcode, creane uno e salvalo sulla tua macchina locale. Se è la prima volta che sviluppi iOS:
    1. Crea un nuovo progetto.
    2. Seleziona il modello iOS > App.
    3. Nella schermata delle opzioni del progetto:
      1. Inserisci il Nome progetto.
      2. Registra il valore del campo Identificatore pacchetto. Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta il progetto Interface su Storyboard.
      4. Imposta la Lingua su Swift o Objective-C.
  3. Crea un file denominato Cartfile nella directory del progetto. Questo file definisce le dipendenze del progetto.
  4. Modifica il Cartfile e aggiungi le tue dipendenze insieme alle relative versioni:

    binary "https://dl.google.com/geosdk/GoogleMaps.json" == 6.2.1-beta
  5. Salva il Cartfile.
  6. In una finestra del terminale, vai alla directory contenente Cartfile:
    cd <path-to-project>
  7. Esegui il comando carthage update. Verranno installate le API specificate in Cartfile, insieme alle eventuali dipendenze che potrebbero avere.
  8. Nel Finder, nella directory del progetto, vai ai file del framework scaricati in Carthage/Build.
  9. Trascina il seguente XCFrameworks nel progetto in Frameworks, Libraries e Embedded Content. Assicurati di selezionare Do Not Embed (Non incorporare) per ogni XCFramework:
    • GoogleMaps-x.x.x/GoogleMapsBase.xcframework
    • GoogleMaps-x.x.x/GoogleMaps.xcframework
    • GoogleMaps-x.x.x/GoogleMapsCore.xcframework
    • (Solo clienti con piano Premium) GoogleMaps-x.x.x/GoogleMapsM4B.xcframework
  10. Fai clic con il tasto destro del mouse su GoogleMaps.xcframework nel progetto e seleziona Mostra nel Finder.
  11. Trascina GoogleMaps.bundle dalla cartella ios-arm64_x86_64-simulator/GoogleMaps.framework/Resources nella directory di primo livello del tuo progetto Xcode. Quando richiesto, assicurati che l'opzione Copia elementi se necessario non sia selezionata.
  12. Seleziona il progetto nel navigatore dei progetti e scegli la destinazione dell'applicazione.
  13. Apri la scheda Fasi della build per il target dell'applicazione e, in Link Binary con librerie, aggiungi i seguenti framework e librerie:
    • 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. Scegli il progetto, anziché un target specifico, e apri la scheda Impostazioni build. Nella sezione Altri flag del linker, aggiungi -ObjC. Se queste impostazioni non sono visibili, modifica il filtro nella barra Impostazioni build da Di base a Tutte.

  15. Per installare l'SDK Places per iOS XCFramework, consulta la guida introduttiva all'SDK Places per iOS.

Manualmente

Questa guida mostra come aggiungere manualmente l'SDK Maps per iOS al tuo progetto e configurare le impostazioni di build in Xcode.

  1. Scarica i file di origine dell'SDK: GoogleMaps-7.2.0-beta-xcframework.
  2. Apri i file di origine.
  3. Se non hai ancora un progetto Xcode, creane uno e salvalo sulla tua macchina locale. Se è la prima volta che sviluppi iOS:
    1. Crea un nuovo progetto.
    2. Seleziona il modello iOS > App.
    3. Nella schermata delle opzioni del progetto:
      1. Inserisci il Nome progetto.
      2. Registra il valore del campo Identificatore pacchetto. Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta il progetto Interface su Storyboard.
      4. Imposta la Lingua su Swift o Objective-C.
  4. Trascina il seguente XCFrameworks nel progetto in Frameworks, Libraries e Embedded Content. Assicurati di selezionare Do Not Embed (Non incorporare) per ogni XCFramework:
    • GoogleMaps-x.x.x/GoogleMapsBase.xcframework
    • GoogleMaps-x.x.x/GoogleMaps.xcframework
    • GoogleMaps-x.x.x/GoogleMapsCore.xcframework
    • (Solo clienti con piano Premium) GoogleMaps-x.x.x/GoogleMapsM4B.xcframework
  5. Fai clic con il tasto destro del mouse su GoogleMaps.xcframework nel progetto e seleziona Mostra nel Finder.
  6. Trascina GoogleMaps.bundle dalla cartella ios-arm64_x86_64-simulator/GoogleMaps.framework/Resources nella directory di primo livello del tuo progetto Xcode. Quando richiesto, assicurati che l'opzione Copia elementi se necessario non sia selezionata.
  7. Seleziona il progetto nel navigatore dei progetti e scegli la destinazione dell'applicazione.
  8. Apri la scheda Fasi della build per il target dell'applicazione e, in Link Binary con librerie, aggiungi i seguenti framework e librerie:
    • 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. Scegli il progetto, anziché un target specifico, e apri la scheda Impostazioni build. Nella sezione Altri flag del linker, aggiungi -ObjC. Se queste impostazioni non sono visibili, modifica il filtro nella barra Impostazioni build da Di base a Tutte.

  10. Per installare l'SDK Places per iOS XCFramework, consulta la guida introduttiva all'SDK Places per iOS.

Passaggio 3: aggiungi la chiave API al progetto

In Ottieni una chiave API, hai generato una chiave API per la tua app. Ora aggiungi questa chiave al tuo progetto Xcode.

Negli esempi seguenti, sostituisci YOUR_API_KEY con la chiave API.

Swift

Aggiungi la chiave API a AppDelegate.swift come segue:

  1. Aggiungi la seguente istruzione di importazione:
    import GoogleMaps
  2. Aggiungi quanto segue al metodo application(_:didFinishLaunchingWithOptions:), utilizzando la chiave API:
    GMSServices.provideAPIKey("YOUR_API_KEY")
  3. Se usi anche l'API Places, aggiungi di nuovo la chiave come mostrato qui:
    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

Aggiungi la chiave API a AppDelegate.m come segue:

  1. Aggiungi la seguente istruzione di importazione:
    @import GoogleMaps;
  2. Aggiungi quanto segue al metodo application:didFinishLaunchingWithOptions:, utilizzando la chiave API:
    [GMSServices provideAPIKey:@"YOUR_API_KEY"];
  3. Se usi anche l'API Places, aggiungi di nuovo la chiave come mostrato qui:
    [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

(Facoltativo) Passaggio 4: attiva l'utilizzo del framework di rendering Metal

L'SDK Maps per iOS ti consente di attivare il framework di rendering Metallo di Apple. Per provare il renderer metal nell'app, chiama [GMSServices setMetalRendererEnabled:YES] in Objective-C o GMSServices.setMetalRendererEnabled(true) in Swift prima di creare qualsiasi visualizzazione mappa.

Se installi l'SDK manualmente, devi anche assicurarti di aggiungere Metal.framework in XCode.

Passaggio 5: aggiungi una mappa

Il codice seguente mostra come aggiungere una mappa semplice a un elemento ViewController esistente:

  1. Aggiungi o aggiorna i metodi in ViewController predefinito dell'app per creare e inizializzare un'istanza di 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. Esegui la tua applicazione. Dovresti vedere una mappa con un singolo indicatore centrato su Sydney, in Australia. Se vedi l'indicatore, ma la mappa non è visibile, verifica di aver fornito la chiave API.

(Facoltativo) Passaggio 6: dichiara gli schemi URL utilizzati dall'API

A partire da iOS 9 e Xcode 7, le app possono dichiarare gli schemi URL che intendono aprire, specificando gli schemi nel file Info.plist dell'app. L'SDK Maps per iOS apre l'app per dispositivi mobili Google Maps quando l'utente fa clic sul logo Google nella mappa, dopodiché l'app può dichiarare gli schemi URL pertinenti.

Per dichiarare gli schemi URL utilizzati dall'SDK Maps per iOS, aggiungi le seguenti righe al tuo Info.plist:

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

Il seguente screenshot mostra la configurazione nell'interfaccia utente di Xcode:

Configurazione di LSApplicationQuerySchemes in Xcode

Senza la dichiarazione riportata sopra, possono verificarsi i seguenti errori quando l'utente tocca il logo Google sulla mappa:

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

Per eliminare questi errori, aggiungi la dichiarazione al tuo Info.plist come descritto sopra.

Passaggi successivi

Ora che hai una chiave API e un progetto Xcode, puoi creare ed eseguire app. L'SDK Maps per iOS fornisce molti tutorial e app di esempio che possono aiutarti a iniziare. Per maggiori dettagli, vedi: