Configurare un progetto Xcode

Dopo aver abilitato la fatturazione e creato una chiave API, configura 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, scarica e installa:

  • Xcode versione 26.0 o successive

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

Le dimensioni di installazione dell'SDK variano. Ad esempio, le dimensioni di installazione di Maps SDK for iOS versione 9.0 sono di circa 18 MB.

Swift Package Manager

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

Per aggiungere l'SDK a un progetto nuovo o esistente, segui questi passaggi:

  1. Apri il tuo 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 inserire il pacchetto e fai clic su "Add Package" (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 l'ultima versione e di utilizzare l'opzione "Versione esatta". Al termine, fai clic su "Aggiungi pacchetto".
  4. Nella finestra Scegli i prodotti del pacchetto, verifica che GoogleMaps (per le versioni precedenti alla 9.0.0, verifica GoogleMaps, GoogleMapsBase e GoogleMapsCore) venga aggiunto al target main designato. Al termine, fai clic su "Aggiungi pacchetto".
  5. Per verificare l'installazione, vai al riquadro General (Generale) della destinazione. Nella sezione Frameworks, Libraries, and Embedded Content (Framework, librerie e contenuti incorporati) dovresti vedere i pacchetti installati. Puoi anche visualizzare la sezione "Dipendenze del pacchetto" di "Navigatore progetto" per verificare il pacchetto e la relativa versione.

Per aggiornare package per un progetto esistente, segui questi passaggi:

  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 saperne di più, 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 > Packages > Update To Latest Package Versions (File > Pacchetti > Aggiorna alle ultime versioni dei pacchetti).
  3. Per verificare l'installazione, vai alla sezione Package Dependencies (Dipendenze pacchetto) di Project Navigator (Navigatore progetto) per verificare il pacchetto e la relativa versione.

Per rimuovere le dipendenze esistenti di Maps SDK for iOS aggiunte utilizzando CocoaPods, segui questi passaggi:

  1. Chiudi l'area di lavoro di Xcode. Apri il terminale ed esegui questo 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 nient'altro oltre a CocoaPods.
Per rimuovere l'SDK Maps per iOS esistente installato manualmente, segui questi passaggi:
  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 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 bundle GoogleMaps.

Installazione manuale

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

  1. Scarica i seguenti file binari e di risorse dell'SDK:
  2. Estrai i file per accedere agli XCFramework e alle risorse.
  3. Se non hai ancora un progetto Xcode, creane uno ora e salvalo sulla tua macchina locale. Se non hai mai sviluppato per 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 l'interfaccia del progetto su Storyboard.
      4. Imposta Language (Lingua) su Swift o Objective-C.
  4. Apri la scheda Generale. Trascina i seguenti XCFramework nel progetto in Framework, librerie e contenuti incorporati. Assicurati di selezionare Non incorporare:
    • GoogleMaps.xcframework
  5. Copia il file GoogleMaps.bundle dalla directory GoogleMapsResources che hai scaricato nella directory di primo livello del progetto Xcode. Assicurati di selezionare Copia gli elementi nella cartella del gruppo di destinazione quando richiesto.
  6. Seleziona il progetto dal navigatore del progetto e scegli la destinazione dell'applicazione.
  7. Apri la scheda Build Phases (Fasi di creazione) per il target della tua 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 tuo progetto, anziché un target specifico, e apri la scheda Build Settings. Nella sezione Linking - General -> Other Linker Flags, aggiungi -ObjC a "Debug" e "Release". Se queste impostazioni non sono visibili, cambia il filtro nella barra Build Settings (Impostazioni build) da Basic (Di base) a All (Tutte).

  9. Per installare Places SDK for iOS XCFramework, consulta Inizia a utilizzare Places SDK for 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 la chiave al tuo progetto Xcode.

Negli esempi seguenti, sostituisci YOUR_API_KEY con la tua chiave API.

Swift

Aggiungi la chiave API al tuo 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 al tuo 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: esamina il file manifest della privacy di Apple

Apple richiede i dettagli sulla privacy delle app per le app presenti nell'App Store. Visita la pagina dei 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 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 dichiarano 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 al file Info.plist:

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

L'immagine seguente mostra la configurazione nell'interfaccia utente di Xcode:

Configurazione di &quot;LSApplicationQueriesSchemes&quot; in 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 al tuo Info.plist.

Passaggi successivi

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