Configurare un progetto Xcode

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

Per ogni release sono disponibili note di rilascio.

Passaggio 1: installa il software necessario

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

• Xcode versione 15.0 o successive

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

Nota: Maps SDK for iOS aggiunge una dimensione media dell'IPA di 5,7 MB per le app create per dispositivi specifici. Le dimensioni di download delle app universali potrebbero essere maggiori.

Le dimensioni dell'installazione dell'SDK possono variare. Ad esempio, la dimensione dell'installazione per Maps SDK per iOS versione 9.0 è di circa 18 MB.

Nota: con la versione 9.2.0, GoogleMapsCore e GoogleMapsBase vengono consolidati nel framework XC di GoogleMaps. Non è richiesta alcuna configurazione aggiuntiva.

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.

Importante: queste istruzioni presuppongono l'utilizzo di Xcode 15 o versioni successive, ma dovrebbero essere simili per le versioni precedenti di Xcode.

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

1. Apri Xcode project o workspace, quindi vai a File > Aggiungi dipendenze del pacchetto.
2. Inserisci https://github.com/googlemaps/ios-maps-sdk come URL, premi Invio per importare il pacchetto e fai clic su "Aggiungi pacchetto".
3. Per installare un version specifico, imposta il campo Regola di dipendenza su una delle opzioni basate sulla versione. Per i nuovi progetti, ti consigliamo di specificare la versione più recente e di utilizzare l'opzione "Versione esatta". Al termine, fai clic su "Aggiungi pacchetto".

Per aggiornare il package di un progetto esistente:

1. Se esegui l'upgrade da una versione precedente a 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 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 > Pacchetti > Aggiorna alle versioni più recenti dei pacchetti".
3. Per verificare l'installazione, vai alla sezione Dipendenze del pacchetto di Project Navigator per verificare il pacchetto e la relativa versione.

Importante: a volte gli elementi non possono essere risolti o possono verificarsi errori. In questo caso, seleziona "File > Pacchetti > Ripristina cache dei pacchetti".

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

1. Chiudi lo spazio 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 workspace di Xcode se non li utilizzi per altro che per CocoaPods.

Per rimuovere Maps SDK for iOS esistente installato manualmente:

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

Installazione manuale

Questa guida mostra come aggiungere manualmente al progetto gli XCFramework contenenti l'SDK Maps per iOS e configurare le impostazioni di compilazione 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 di risorse e binari dell'SDK:
   • GoogleMaps
   • GoogleMapsM4B
   • GoogleMapsResources
2. Estrai i file per accedere agli XCFrameworks e alle risorse.
3. Se non hai ancora un progetto Xcode, creane uno ora e salvalo sulla tua macchina locale. Se non hai esperienza nello 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 Identificatore pacchetto. Puoi utilizzare questo valore per limitare la tua chiave API di seguito.
      3. Imposta l'interfaccia del progetto su Storyboard.
      4. Imposta Lingua su Swift o Objective-C.
4. Apri la scheda Generale. Trascina il seguente XCFramework nel progetto in Framework, librerie e contenuti incorporati. Assicurati di selezionare Non incorporare:
   • GoogleMaps.xcframework
5. Copia GoogleMaps.bundle da GoogleMapsResources che hai scaricato nella directory di primo livello del progetto Xcode. Assicurati di selezionare Copia elementi nella cartella del gruppo di destinazione quando richiesto.
6. Seleziona il progetto dal Navigatore progetti e scegli la destinazione dell'applicazione.
7. Apri la scheda Fasi di compilazione per il target della tua applicazione. In Collega il file binario alle 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
   • OpenGLES.framework (solo se utilizzi OpenGL)
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. Scegli il progetto anziché un target specifico e apri la scheda Impostazioni di compilazione. Nella sezione Linking - General -> Other Linker Flags, aggiungi -ObjC a "Debug" e "Release". Se queste impostazioni non sono visibili, modifica il filtro nella barra Impostazioni di compilazione da Base a Tutte.

9. Per installare il XCFramework di Places SDK per iOS, consulta Iniziare a utilizzare Places SDK per iOS.

CocoaPods

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

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

sudo gem install cocoapods

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

1. Se non hai ancora un progetto Xcode, creane uno ora e salvalo sulla tua macchina locale. Se non hai esperienza nello 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 Identificatore pacchetto. Puoi utilizzare questo valore per limitare la tua chiave API di seguito.
      3. Imposta l'interfaccia del progetto su Storyboard.
      4. Imposta 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 dipendenze con le relative versioni. Ecco un esempio che include la dipendenza necessaria per Maps SDK for iOS:

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

   Assicurati di eseguire regolarmente pod outdated per rilevare se è disponibile una versione più recente e assicurarti di avere sempre la versione più recente. 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 nel file Podfile, insieme a eventuali dipendenze.

   pod install

7. Chiudi Xcode, quindi apri (fai doppio clic) il file .xcworkspace del progetto per avviare Xcode. Da questo 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. In questo modo, tutte le API specificate in Podfile verranno aggiornate alla versione più recente.

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 del pacchetto del tuo progetto o lo hai ottenuto dalle proprietà del progetto, puoi utilizzarlo per limitare l'utilizzo della chiave API solo alle applicazioni per iOS con quell'identificatore del pacchetto specifico. Per ulteriori informazioni, consulta la sezione 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 di seguito:

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

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

(Facoltativo) Passaggio 4: controlla il file manifest della privacy di Apple

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

Apple richiede dettagli sulla privacy delle app per le app nell'App Store. Per aggiornamenti e ulteriori informazioni, visita la pagina Dettagli sulla privacy dell'App Store di Apple.

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 ispezionarne i contenuti, crea un archivio della tua app e genera un report sulla privacy dall'archivio.

(Facoltativo) Passaggio 5: 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 specificandoli 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 riportata sopra, quando l'utente tocca il logo di Google sulla mappa possono verificarsi i seguenti errori:

• -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.

Passaggi successivi

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

• I seguenti tutorial sono punti di partenza consigliati:
  • Aggiungi una mappa con un indicatore.
  • Seleziona Posizione attuale e Mostra dettagli su una mappa.
  • Inversione della codifica geografica.
• Consulta gli esempi di codice e i codelabs disponibili.
• Per soluzioni end-to-end, consulta le soluzioni di Maps disponibili.