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.

Per ogni release sono disponibili le note di rilascio.

Passaggio 1: installa il software richiesto

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

• Xcode versione 15.0 o successive

Passaggio 2: crea il progetto Xcode e installa l'SDK Maps per iOS

Gestore pacchetti Swift

Maps SDK per 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.

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 il file Xcode project o workspace, quindi vai a 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 "Aggiungi pacchetto".
3. Per installare un elemento 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".
4. Nella finestra Scegli i prodotti del pacchetto, verifica che GoogleMaps (per le versioni precedenti alla 9.0.0, verifica GoogleMaps, GoogleMapsBase e GoogleMapsCore) verrà aggiunto alla destinazione main designata. Al termine, fai clic su "Aggiungi pacchetto".
5. Per verificare l'installazione, vai al riquadro General di destinazione. In Framework, librerie e contenuti incorporati dovresti vedere i pacchetti installati. Puoi anche visualizzare la sezione "Dipendenze pacchetto" di "Navigatore progetto" per verificare il pacchetto e la sua versione.

Per aggiornare 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 maggiori 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. Da Xcode, seleziona "File > Packages > Update to Latest Package Versions" (File > Pacchetti > Aggiorna alle versioni più recenti dei pacchetti).
3. Per verificare l'installazione, vai alla sezione 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 del 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 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 scopi diversi da CocoaPods.

Per rimuovere l'SDK Maps esistente per iOS 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 le installazioni precedenti alla versione 9.0.0)
   • GoogleMapsCore (solo per le installazioni precedenti alla versione 9.0.0)
   • GoogleMapsM4B (solo per le installazioni precedenti alla versione 9.0.0)
2. Rimuovi il bundle GoogleMaps dalla directory di primo livello del tuo progetto Xcode.

CocoaPods

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

Se non hai ancora lo strumento CocoaPods, installalo su macOS eseguendo questo 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 sue dipendenze:

1. Se non hai ancora un progetto Xcode, creane uno ora e salvalo sulla tua macchina locale. Se non hai familiarità con lo sviluppo di iOS:
   1. Creare 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 bundle. Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta il progetto Interface su Storyboard.
      4. Imposta il campo Lingua su Swift o Objective-C.
2. Crea un file denominato Podfile nella directory del tuo progetto. Questo file definisce le dipendenze del progetto.
3. Modifica Podfile e aggiungi le dipendenze insieme alle relative versions. 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', '8.4.0'
   end
   

   Assicurati di eseguire regolarmente pod outdated per rilevare se è disponibile una versione più recente, in modo da avere sempre quella più recente. Se necessario, esegui l'upgrade alla versione più recente.
4. Salva Podfile.

5. Apri un terminale e vai alla directory contenente Podfile:

   cd <path-to-project>

6. Esegui il comando pod install. Questa operazione installerà le API specificate in Podfile, insieme a tutte le eventuali dipendenze.

   pod install

7. Chiudi Xcode, quindi apri (doppio clic) il file .xcworkspace del tuo progetto per avviare Xcode. D'ora 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 l'Podfile.
2. Esegui il comando pod update. Tutte le API specificate in Podfile verranno aggiornate all'ultima versione.

Installazione manuale

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

1. Scarica i seguenti programmi binari dell'SDK e file di risorse:
   • GoogleMaps
   • GoogleMapsBase
   • GoogleMapsCore
   • GoogleMapsM4B
   • GoogleMapsResources
2. Estrai i file per accedere a XCFrameworks e alle risorse.
3. Se non hai ancora un progetto Xcode, creane uno ora e salvalo sulla tua macchina locale. Se non hai familiarità con lo sviluppo di iOS:
   1. Creare 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 bundle. Puoi utilizzare questo valore per limitare la chiave API di seguito.
      3. Imposta il progetto Interface su Storyboard.
      4. Imposta il campo Lingua su Swift o Objective-C.
4. Apri la scheda Generali. Trascina i seguenti XCFrameworks nel tuo progetto in Framework, librerie e contenuti incorporati. Assicurati di selezionare Do Not Embed (Non incorporare) per ogni XCFramework:
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
5. Copia GoogleMaps.bundle da GoogleMapsResources che hai scaricato nella directory di primo livello del tuo progetto Xcode. Quando richiesto, assicurati di selezionare Copia gli elementi nella cartella del gruppo di destinazione.
6. Seleziona il tuo progetto dal navigatore dei progetti e scegli il target della tua applicazione.
7. Apri la scheda Fasi di build per la destinazione dell'applicazione. All'interno di Collega binario con le 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 tuo progetto, anziché una destinazione specifica, e apri la scheda Impostazioni build. Nella sezione Collegamento - Generale -> Altri flag linker, aggiungi -ObjC a "Debug" e "Release". Se queste impostazioni non sono visibili, modifica il filtro nella barra Impostazioni build da Di base a Tutte.

9. Per installare Places SDK for iOS XCFramework, consulta la Guida introduttiva all'utilizzo di Places SDK per iOS.

Passaggio 3: esamina il file manifest della privacy di Apple

Apple richiede informazioni sulla privacy per le app disponibili sull'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 per la privacy sia stato incluso e per controllarne i contenuti, crea un archivio della tua app e genera una segnalazione sulla privacy dall'archivio.

Passaggio 4: 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 seguenti, sostituisci YOUR_API_KEY con la tua chiave API.

Nota: se hai registrato l'identificatore bundle del tuo progetto o lo hai ottenuto dalle proprietà del progetto, puoi utilizzarlo per limitare l'utilizzo della chiave API solo con le applicazioni iOS con quello specifico identificatore pacchetto. Consulta Limitazione delle chiavi API

per ulteriori informazioni.

Swift

Aggiungi la chiave API a AppDelegate.swift nel seguente modo:

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 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 nel seguente modo:

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 utilizzi anche l'API Places, aggiungi di nuovo la chiave come mostrato qui:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Passaggio 5: aggiungi una mappa

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 options = GMSMapViewOptions()
        options.camera = GMSCameraPosition.camera(withLatitude: -33.86, longitude: 151.20, zoom: 6.0)
        options.frame = self.view.bounds

        let mapView = GMSMapView(options: options)
        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.
  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
  options.camera = [GMSCameraPosition cameraWithLatitude:-33.8683
                                                        longitude:151.2086
                                                             zoom:6];
  options.frame = self.view.bounds;
  GMSMapView *mapView = [[GMSMapView alloc] initWithOptions:options];

  [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

(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, 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 e la tua app può quindi dichiarare gli schemi di URL pertinenti.

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

LSApplicationQueriesSchemes googlechromes comgooglemaps

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

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

• -canOpenURL: non riuscito per l'URL: "comgooglemaps://" - errore: "A questa app non è consentito eseguire query per lo schema comgooglemaps"
• -canOpenURL: non riuscito per l'URL: "googlechromes://" - errore: "A questa app non è consentito eseguire query per lo schema 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 le app. L'SDK di navigazione per iOS fornisce molti tutorial e app di esempio che possono aiutarti a iniziare. Per ulteriori dettagli, consulta:

• Esempi di codice
• Tutorial
  • Aggiungere una mappa con un indicatore
  • Seleziona il luogo attuale e mostra i dettagli su una mappa
  • Inverti geocodifica
• Codelab
• Soluzioni di Maps