Xcode-Projekt einrichten

Nachdem Sie die Abrechnung aktiviert und einen API-Schlüssel erstellt haben, können Sie das Xcode-Projekt für die Entwicklung Ihrer App einrichten.

Versionshinweise sind für jede Version verfügbar.

Schritt 1: Erforderliche Software installieren

Wenn Sie ein Projekt mit dem Maps SDK for iOS erstellen möchten, müssen Sie Folgendes herunterladen und installieren:

• Xcode Version 26.0 oder höher

Schritt 2: Xcode-Projekt erstellen und Maps SDK for iOS installieren

Hinweis: Das Maps SDK for iOS erhöht die durchschnittliche IPA-Größe für Apps, die für bestimmte Geräte entwickelt wurden, um 5,7 MB. Die Downloadgröße für universelle Apps kann größer sein.

Die Installationsgröße des SDK kann variieren. Die Installationsgröße für das Maps SDK for iOS Version 9.0 beträgt beispielsweise etwa 18 MB.

Hinweis: In Version 9.2.0 werden GoogleMapsCore und GoogleMapsBase in das GoogleMaps XCFramework zusammengeführt. Es ist keine zusätzliche Einrichtung erforderlich.

Swift Package Manager

Das Maps SDK for iOS kann über den Swift Package Manager installiert werden. Wenn Sie das SDK hinzufügen möchten, müssen Sie alle vorhandenen Abhängigkeiten des Maps SDK for iOS entfernen.

So fügen Sie das SDK einem neuen oder vorhandenen Projekt hinzu:

1. Öffnen Sie Ihr Xcode-project oder Ihren workspace und gehen Sie zu File > Add Package Dependencies.
2. Geben Sie https://github.com/googlemaps/ios-maps-sdk als URL ein, drücken Sie die Eingabetaste , um das Paket abzurufen, und klicken Sie auf „Add Package“ (Paket hinzufügen).
3. Wenn Sie eine bestimmte version installieren möchten, legen Sie für das Feld Dependency Rule eine der versionsbasierten Optionen fest. Für neue Projekte empfehlen wir, die neueste Version anzugeben und die Option „Exact Version“ (Genaue Version) zu verwenden. Klicken Sie nach Abschluss des Vorgangs auf „Add Package“ (Paket hinzufügen).

So aktualisieren Sie das package für ein vorhandenes Projekt:

1. Wenn Sie ein Upgrade von einer Version vor 9.0.0 durchführen, müssen Sie nach dem Upgrade die folgenden Abhängigkeiten entfernen: GoogleMapsBase, GoogleMapsCore und GoogleMapsM4B. Entfernen Sie nicht die Abhängigkeit für GoogleMaps. Weitere Informationen finden Sie in den Versionshinweisen zu Version 9.0.0.

   Suchen Sie in den Konfigurationseinstellungen Ihres Xcode-Projekts nach Frameworks, Libraries, und eingebettete Inhalte. Entfernen Sie das folgende Framework mit dem Minuszeichen(-):

   • GoogleMapsBase (nur für Upgrades von Versionen vor 9.0.0)
   • GoogleMapsCore (nur für Upgrades von Versionen vor 9.0.0)
   • GoogleMapsM4B (nur für Upgrades von Versionen vor 9.0.0)
2. Gehen Sie in Xcode zu „File > Packages > Update To Latest Package Versions“ (Datei > Pakete > Auf neueste Paketversionen aktualisieren).
3. Prüfen Sie die Installation unter Package Dependencies (Paketabhängigkeiten) im Project Navigator (Projektnavigator). Dort sehen Sie das Paket und seine Version.

Wichtig: Manchmal können Artefakte nicht aufgelöst werden oder es treten Fehler auf. Wählen Sie in diesem Fall "File > Packages > Reset Package Cache" aus.

So entfernen Sie vorhandene Abhängigkeiten des Maps SDK for iOS, die mit CocoaPods hinzugefügt wurden:

1. Schließen Sie Ihren Xcode-Arbeitsbereich. Öffnen Sie das Terminal und führen Sie den folgenden Befehl aus:

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

2. Entfernen Sie die Dateien Podfile, Podfile.resolved und den Xcode workspace, wenn Sie sie nur für CocoaPods verwenden.

So entfernen Sie vorhandene manuell installierte Versionen des Maps SDK for iOS: Folgen Sie dazu diesen Schritten:

1. Suchen Sie in den Konfigurationseinstellungen Ihres Xcode-Projekts nach Frameworks, Libraries, and Embedded Content (Frameworks, Bibliotheken und eingebettete Inhalte). Entfernen Sie das folgende Framework mit dem Minuszeichen(-) :
   • GoogleMaps
   • GoogleMapsBase (nur für Installationen vor Version 9.2.0)
   • GoogleMapsCore (nur für Installationen vor Version 9.2.0)
   • GoogleMapsM4B (nur für Installationen vor Version 9.0.0)
2. Entfernen Sie im Stammverzeichnis Ihres Xcode-Projekts das GoogleMaps Bundle.

Manuelle Installation

In diesem Leitfaden erfahren Sie, wie Sie die XCFrameworks mit dem Maps SDK for iOS manuell in Ihr Projekt einfügen und die Build-Einstellungen in Xcode konfigurieren. Ein XCFramework ist ein binäres Paket, das Sie auf mehreren Plattformen verwenden können, einschließlich Computern mit Apple-Silizium.

1. Laden Sie die folgenden SDK-Binärdateien und Ressourcendateien herunter:
   • GoogleMaps
   • GoogleMapsResources
2. Extrahieren Sie die Dateien, um auf die XCFrameworks und Ressourcen zuzugreifen.
3. Falls Sie noch kein Xcode-Projekt haben, erstellen Sie eines und speichern Sie es auf dem lokalen Rechner. Wenn Sie noch keine Erfahrung in der iOS-Entwicklung haben:
   1. Erstellen Sie ein neues Projekt.
   2. Wählen Sie die Vorlage iOS > App aus.
   3. Auf dem Bildschirm mit den Projektoptionen:
      1. Geben Sie den Projektnamen ein.
      2. Notieren Sie sich den Wert des Felds Bundle identifier (Paket-Identifikator). Sie können diesen Wert verwenden, um Ihren API-Schlüssel unten einzuschränken.
      3. Legen Sie für die Interface (Schnittstelle) des Projekts Storyboard fest.
      4. Legen Sie für die Language (Sprache) Swift oder Objective-C fest.
4. Öffnen Sie den Tab General (Allgemein). Ziehen Sie die folgenden XCFrameworks unter Frameworks, Libraries, and Embedded Content (Frameworks, Bibliotheken und eingebettete Inhalte) in Ihr Projekt. Stellen Sie sicher, dass Sie Do Not Embed auswählen:
   • GoogleMaps.xcframework
5. Kopieren Sie die Datei GoogleMaps.bundle aus den GoogleMapsResources heruntergeladenen in das Stammverzeichnis Ihres Xcode-Projekts. Wählen Sie bei Aufforderung Copy items into destination group's folder (Elemente in Ordner der Zielgruppe kopieren) aus.
6. Wählen Sie im Project Navigator (Projektnavigator) Ihr Projekt aus und geben Sie dann das Ziel Ihrer App an.
7. Öffnen Sie den Tab Build Phases (Build-Phasen) für das Ziel Ihrer App. Fügen Sie unter Link Binary with Libraries die folgenden Frameworks und Bibliotheken hinzu:
   • 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 (nur wenn Sie OpenGL verwenden)
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. Wählen Sie statt eines bestimmten Ziels Ihr Projekt aus und öffnen Sie den Build Settings Tab. Fügen Sie im Bereich Linking - General -> Other Linker Flags (Verknüpfung – Allgemein – > Weitere Verknüpfungsmerker) -ObjC zu „Debug“ und „Release“ hinzu. Falls die Einstellungen nicht angezeigt werden, filtern Sie in der Leiste Build Settings (Build-Einstellungen) nicht mehr nach Basic (Standard), sondern nach All (Alle).

9. Informationen zum Installieren des Places SDK for iOS XCFramework finden Sie im Startleitfaden zum Places SDK for iOS (in englischer Sprache).

CocoaPods

Eingestellt:CocoaPods befindet sich seit dem 18.08.2025 im Wartungsmodus. Nach dem 2. Quartal 2026 werden keine weiteren Versionen von CocoaPods veröffentlicht. Verwenden Sie stattdessen Swift Package Manager.

Das Maps SDK for iOS ist als CocoaPods Pod verfügbar. CocoaPods ist ein Open-Source-Abhängigkeitsmanager für Cocoa-Projekte in Swift und Objective-C

Falls Sie das Tool „CocoaPods“ noch nicht nutzen, installieren Sie es unter macOS, indem Sie den folgenden Befehl über das Terminal ausführen. Weitere Informationen finden Sie im Startleitfaden zu CocoaPods (in englischer Sprache).

sudo gem install cocoapods

Erstellen Sie eine Podfile für das Maps SDK for iOS und verwenden Sie sie, um die API und die zugehörigen Abhängigkeiten zu installieren:

1. Falls Sie noch kein Xcode-Projekt haben, erstellen Sie eines und speichern Sie es auf dem lokalen Rechner. Wenn Sie noch keine Erfahrung in der iOS-Entwicklung haben:
   1. Erstellen Sie ein neues Projekt.
   2. Wählen Sie die Vorlage iOS > App aus.
   3. Auf dem Bildschirm mit den Projektoptionen:
      1. Geben Sie den Projektnamen ein.
      2. Notieren Sie sich den Wert des Felds Bundle identifier (Paket-Identifikator). Sie können diesen Wert verwenden, um Ihren API-Schlüssel unten einzuschränken.
      3. Legen Sie für die Interface (Schnittstelle) des Projekts Storyboard fest.
      4. Legen Sie für die Language (Sprache) Swift oder Objective-C fest.
2. Erstellen Sie in Ihrem Projektverzeichnis eine Datei mit dem Namen Podfile. In dieser Datei sind die Abhängigkeiten des Projekts definiert.
3. Bearbeiten Sie die Podfile und fügen Sie die Abhängigkeiten zusammen mit ihren Versionen hinzu. Im Folgenden finden Sie ein Beispiel, das die Abhängigkeit enthält, die Sie für das Maps SDK for iOS benötigen:

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

   Führen Sie regelmäßig pod outdated aus, um zu erkennen, wann eine neuere Version verfügbar ist, damit Sie immer die aktuelle Version verwenden. Aktualisieren Sie bei Bedarf, auf die neueste Version.
4. Speichern Sie die Podfile.

5. Öffnen Sie ein Terminalfenster und suchen Sie das Verzeichnis mit der Podfile:

   cd <path-to-project>

6. Führen Sie den Befehl pod install aus. Dadurch werden die in der Podfile angegebenen APIs und ggf. zugehörige Abhängigkeiten installiert.

   pod install

7. Schließe Xcode und öffne dann mit einem Doppelklick die Datei .xcworkspace deines Projekts, um Xcode wieder zu starten. Ab jetzt musst du das Projekt über die .xcworkspace Datei aufrufen.

So aktualisieren Sie die API für ein vorhandenes Projekt:

1. Öffnen Sie ein Terminalfenster und gehen Sie zum Projektverzeichnis mit der Podfile.
2. Führen Sie den Befehl pod update aus. Dadurch werden alle in der Podfile angegebenen APIs auf die neueste Version aktualisiert.

Schritt 3: API-Schlüssel zum Projekt hinzufügen

Unter API-Schlüssel abrufen haben Sie einen API-Schlüssel für Ihre App generiert. Fügen Sie diesen Schlüssel jetzt Ihrem Xcode-Projekt hinzu.

Ersetzen Sie in den folgenden Beispielen YOUR_API_KEY durch Ihren API-Schlüssel.

Hinweis: Wenn Sie die Bundle-ID Ihres Projekts notiert oder sie aus den Projekteigenschaften abgerufen haben, können Sie damit Ihren API-Schlüssel so einschränken, dass er nur mit iOS-Apps mit dieser bestimmten Bundle-ID verwendet werden kann. Weitere Informationen finden Sie unter API-Schlüssel einschränken.

Swift

Füge deinen API-Schlüssel folgendermaßen in AppDelegate.swift ein:

1. Gib die folgende Importanweisung an:

   import GoogleMaps

2. Füge Folgendes in die Methode application(_:didFinishLaunchingWithOptions:) ein und verwende dabei deinen API-Schlüssel:

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. Wenn du auch die Places API verwendest, füge deinen Schlüssel wie hier gezeigt noch einmal ein:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

Füge deinen API-Schlüssel folgendermaßen in AppDelegate.m ein:

1. Gib die folgende Importanweisung an:

   @import GoogleMaps;

2. Füge Folgendes in die Methode application:didFinishLaunchingWithOptions: ein und verwende dabei deinen API-Schlüssel:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. Wenn du auch die Places API verwendest, füge deinen Schlüssel wie hier gezeigt noch einmal ein:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Schritt 4 (optional): Datenschutzmanifestdatei von Apple prüfen

Hinweis:Das Folgende ist relevant, wenn Sie Ihre App im Webstore bereitstellen.

Apple verlangt Angaben zum Datenschutz für Apps im App Store. Auf der Detailseite „Datenschutzdetails im Apple App Store“ finden Sie Updates und weitere Informationen.

Die Datenschutzmanifestdatei von Apple ist im Ressourcen-Bundle für das SDK enthalten. Wenn Sie prüfen möchten, ob die Datenschutzmanifestdatei enthalten ist, und ihren Inhalt prüfen möchten, erstellen Sie ein Archiv Ihrer App und generieren Sie einen Datenschutzbericht aus dem Archiv.

Schritt 5 (optional): URL-Schemes deklarieren, die von der API verwendet werden

Ab iOS 9 und Xcode 7 können Apps die URL-Schemes deklarieren, die sie öffnen möchten, indem sie die Schemes in der Datei Info.plist der App angeben. Das Maps SDK for iOS öffnet die Google Maps App für Mobilgeräte, wenn der Nutzer auf das Google-Logo auf der Karte klickt. Ihre App kann daher die relevanten URL-Schemes deklarieren.

Wenn Sie die vom Maps SDK for iOS verwendeten URL-Schemes deklarieren möchten, fügen Sie Ihrer Info.plist die folgenden Zeilen hinzu:

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

Der folgende Screenshot zeigt die Konfiguration in der Xcode-Benutzeroberfläche:

Ohne die oben genannte Deklaration können die folgenden Fehler auftreten, wenn der Nutzer auf das Google-Logo auf der Karte tippt:

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

Fügen Sie die Deklaration Ihrer Info.plist hinzu, um diese Fehler zu vermeiden.

Nächste Schritte

Da Sie nun einen API-Schlüssel und ein Xcode-Projekt haben, können Sie Apps erstellen und ausführen. Mit dem Navigation SDK for iOS erhalten Sie viele Anleitungen und Beispielanwendungen für einen einfacheren Einstieg. Weitere Informationen finden Sie hier:

• Die folgenden Anleitungen sind empfohlene Ausgangspunkte:
  • Karte mit einer Markierung hinzufügen.
  • Current Place auswählen und Details auf einer Map einblenden.
  • Umgekehrte Geocodierung.
• Sehen Sie sich die verfügbaren Codebeispiele und Codelabs an.
• Informationen zu End-to-End-Lösungen finden Sie unter Verfügbare Maps-Lösungen.