Configurare un progetto Xcode

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

Le note di rilascio sono disponibili per ogni release.

Passaggio 1: installa il software richiesto

Per creare un progetto utilizzando Maps SDK for iOS, devi scaricare e installare:

• Xcode versione 26.0 o successive

Passaggio 2: crea il progetto Xcode e installa Maps SDK for iOS

Nota: Maps SDK for iOS aggiunge una dimensione IPA media di 5,7 MB per le app create per dispositivi specifici. La dimensione del download per le app universali potrebbe essere maggiore.

La dimensione di installazione dell'SDK può variare. Ad esempio, la dimensione di installazione di Maps SDK for iOS versione 9.0 è di circa 18 MB.

Nota: con la versione 9.2.0, GoogleMapsCore e GoogleMapsBase vengono consolidate in GoogleMaps XCFramework. Non è richiesta nessuna ulteriore configurazione.

Swift Package Manager

Maps SDK for iOS può essere installato tramite Swift Package Manager. Per aggiungere l'SDK, assicurati di aver rimosso eventuali dipendenze di Maps SDK for iOS esistenti.

Per aggiungere l'SDK a un progetto nuovo o esistente:

1. Apri il project o workspace Xcode, quindi vai a File > Add Package Dependencies (File > Aggiungi dipendenze pacchetto).
2. Inserisci https://github.com/googlemaps/ios-maps-sdk come URL, premi Invio per estrarre il pacchetto e fai clic su "Add Package" (Aggiungi pacchetto).
3. Per installare una version specifica, imposta il campo Dependency Rule su una delle le opzioni basate sulla versione. Per i nuovi progetti, ti consigliamo di specificare la versione più recente e di utilizzare l'opzione "Exact Version" (Versione esatta). Al termine, fai clic su "Add Package" (Aggiungi pacchetto).

Per aggiornare il package per un progetto esistente:

1. Se esegui l'upgrade da una versione precedente alla 9.0.0, devi rimuovere le seguenti dipendenze: GoogleMapsBase, GoogleMapsCore, e GoogleMapsM4B dopo l'upgrade. Non rimuovere la dipendenza per GoogleMaps. Per ulteriori informazioni, consulta le note di rilascio della versione 9.0.0.

   Nelle impostazioni di configurazione del progetto Xcode, individua Frameworks, Libraries, e Embedded Content (Framework, librerie e contenuti incorporati). Utilizza il segno meno(-) per rimuovere il seguente framework:

   • GoogleMapsBase (solo per gli upgrade da versioni precedenti alla 9.0.0)
   • GoogleMapsCore (solo per gli upgrade da versioni precedenti alla 9.0.0)
   • GoogleMapsM4B (solo per gli upgrade da versioni precedenti alla 9.0.0)
2. In Xcode, vai a "File > Packages > Update To Latest Package Versions" (File > Pacchetti > Aggiorna alle versioni più recenti dei pacchetti).
3. Per verificare l'installazione, vai alla sezione Package Dependencies (Dipendenze pacchetto) di Project Navigator per verificare il pacchetto e la relativa versione.

Importante: a volte, gli artefatti non possono essere risolti o possono verificarsi errori. In questo caso, seleziona "File > Pacchetti > Reimposta cache pacchetto".

Per rimuovere le dipendenze di Maps SDK for iOS esistenti aggiunte utilizzando CocoaPods:

1. Chiudi l'area di lavoro Xcode. Apri il terminale ed esegui il seguente comando:

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

2. Rimuovi Podfile, Podfile.resolved e Xcode workspace se non li utilizzi per altro oltre a CocoaPods.

Per rimuovere Maps SDK for iOS esistente installato manualmente:

1. Nelle impostazioni di configurazione del progetto Xcode, individua Frameworks, Libraries, and Embedded Content (Framework, librerie e contenuti incorporati). Utilizza il segno meno(-) per rimuovere il seguente framework:
   • GoogleMaps
   • GoogleMapsBase (solo per le installazioni precedenti alla versione 9.2.0)
   • GoogleMapsCore (solo per le installazioni precedenti alla versione 9.2.0)
   • GoogleMapsM4B (solo per le installazioni precedenti alla versione 9.0.0)
2. Dalla directory di primo livello del progetto Xcode, rimuovi il GoogleMaps bundle.

Installazione manuale

Questa guida mostra come aggiungere manualmente gli XCFramework contenenti Maps SDK for iOS al tuo progetto e come configurare le impostazioni di build in Xcode. Un XCFramework è un pacchetto binario che puoi utilizzare su più piattaforme, incluse le macchine che utilizzano Apple Silicon.

1. Scarica i seguenti file binari e di risorse dell'SDK:
   • GoogleMaps
   • GoogleMapsResources
2. Estrai i file per accedere agli XCFramework e alle risorse.
3. Se non hai ancora un progetto Xcode, creane uno ora e salvalo su la tua macchina locale. Se non hai familiarità con lo sviluppo per iOS:
   1. Crea un nuovo progetto.
   2. Seleziona il modello iOS > App.
   3. Nella schermata delle opzioni del progetto:
      1. Inserisci il nome del progetto.
      2. Registra il valore del campo Bundle identifier (identificatore pacchetto). Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta l'interfaccia del progetto su Storyboard.
      4. Imposta la lingua su Swift o Objective-C.
4. Apri la scheda Generale. Trascina i seguenti XCFramework nel tuo progetto in Frameworks, Libraries, and Embedded Content (Framework, librerie e contenuti incorporati). Assicurati di selezionare Do Not Embed (Non incorporare):
   • GoogleMaps.xcframework
5. Copia GoogleMaps.bundle da GoogleMapsResources che hai scaricato nella directory di primo livello del progetto Xcode. Quando ti viene richiesto, assicurati di selezionare Copy items into destination group's folder (Copia gli elementi nella cartella del gruppo di destinazione).
6. Seleziona il tuo progetto dal navigatore del progetto e scegli il tuo target dell'applicazione.
7. Apri la scheda Build Phases (Fasi di build) per il target dell'applicazione. In Link Binary with Libraries (Collega binario con librerie), aggiungi i seguenti framework e librerie:
   • 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
   • MetricKit.framework
   • OpenGLES.framework (solo se utilizzi OpenGL)
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. Scegli il progetto, anziché un target specifico, e apri la scheda Build Settings. Nella sezione Linking - General -> Other Linker Flags (Collegamento - Generale - > Altri flag del linker), aggiungi -ObjC a "Debug" e "Release" (Rilascio). Se queste impostazioni non sono visibili, cambia il filtro nella barra Build Settings (Impostazioni di build) da Basic (Di base) a All (Tutti).

9. Per installare Places SDK for iOS XCFramework, consulta la guida introduttiva a Places SDK for iOS.

CocoaPods

Obsoleto: a partire dal 18/08/2025, CocoaPods è in modalità di manutenzione e non ne rilasceremo altre versioni dopo il secondo trimestre del 2026. Utilizza invece Swift Package Manager.

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

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

sudo gem install cocoapods

Crea un Podfile per Maps SDK for iOS e utilizza lo per installare l'API e le relative dipendenze:

1. Se non hai ancora un progetto Xcode, creane uno ora e salvalo su la tua macchina locale. Se non hai familiarità con lo sviluppo per iOS:
   1. Crea un nuovo progetto.
   2. Seleziona il modello iOS > App.
   3. Nella schermata delle opzioni del progetto:
      1. Inserisci il nome del progetto.
      2. Registra il valore del campo Bundle identifier (identificatore pacchetto). Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta l'interfaccia del progetto 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 Podfile e aggiungi le dipendenze insieme alle relative versioni. Ecco un esempio che include la dipendenza necessaria per il Maps SDK for iOS:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '16.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '10.10.0'
   end

   Esegui regolarmente pod outdated per rilevare quando è disponibile una versione più recente per assicurarti di utilizzare sempre l'ultima versione. Se necessario, esegui l'upgrade all'ultima versione.
4. Salva 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 a eventuali dipendenze they may have.

   pod install

7. Chiudi Xcode, quindi apri (fai doppio clic) il file .xcworkspace del progetto per avviare Xcode. Da questo momento in poi, devi 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. Verrà eseguito l'aggiornamento di tutte le API specificate in Podfile all'ultima versione.

Passaggio 3: aggiungi la chiave API al progetto

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

Negli esempi riportati di seguito, sostituisci YOUR_API_KEY con la tua chiave API.

Nota: se hai registrato l'identificatore pacchetto del tuo progetto o lo hai ottenuto dalle proprietà del progetto, puoi utilizzarlo per limitare la chiave API in modo che venga utilizzata solo con le applicazioni iOS con quell'identificatore pacchetto specifico. Per ulteriori informazioni, consulta Limitare le chiavi 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 tua chiave API:

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. Se utilizzi 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 tua chiave API:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. Se utilizzi anche l'API Places, aggiungi di nuovo la chiave come mostrato qui:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Passaggio 4 (facoltativo): esamina il file manifest della privacy di Apple

Nota: quanto segue è pertinente quando esegui il deployment dell'app nel web store.

Apple richiede i dettagli sulla privacy delle app nell'App Store. Visita la pagina Dettagli sulla privacy dell'App Store di Apple per aggiornamenti e ulteriori informazioni.

Il file manifest della privacy di Apple è incluso nel bundle di risorse per l'SDK. Per verificare che il file manifest della privacy sia stato incluso e per esaminarne i contenuti, crea un archivio dell'app e genera un report sulla privacy dall'archivio.

Passaggio 5 (facoltativo): 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. Maps SDK for iOS apre l'app mobile Google Maps quando l'utente fa clic sul logo Google sulla mappa, pertanto la tua app può dichiarare gli schemi URL pertinenti.

Per dichiarare gli schemi URL utilizzati da Maps SDK for iOS, aggiungi le seguenti righe a Info.plist:

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

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

Senza la dichiarazione precedente, 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 a Info.plist.

Passaggi successivi

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

• I seguenti tutorial sono punti di partenza consigliati:
  • Aggiungi una mappa con un indicatore.
  • Seleziona il luogo attuale e mostra i dettagli su una mappa.
  • Inversione della codifica geografica.
• Dai un'occhiata agli esempi di codice e ai codelab disponibili.
• Per le soluzioni end-to-end, esamina le soluzioni Maps disponibili.