Konfigurowanie projektu Xcode

Po włączeniu płatności i utworzeniu klucza interfejsu API możesz skonfigurować projekt Xcode, którego używasz do tworzenia aplikacji.

Informacje o wersji są dostępne dla każdej wersji.

Krok 1. Zainstaluj wymagane oprogramowanie

Aby utworzyć projekt za pomocą pakietu Maps SDK na iOS, musisz pobrać i zainstalować:

• Xcode w wersji 26.0 lub nowszej

Krok 2. Utwórz projekt Xcode i zainstaluj pakiet Maps SDK na iOS

Uwaga: pakiet Maps SDK na iOS zwiększa średni rozmiar pliku IPA o 5,7 MB w przypadku aplikacji przeznaczonych na konkretne urządzenia. Rozmiar pobierania aplikacji uniwersalnych może być większy.

Rozmiar instalacji pakietu SDK może się różnić. Na przykład rozmiar instalacji pakietu Maps SDK na iOS w wersji 9.0 wynosi około 18 MB.

Uwaga: w wersji 9.2.0 pakiety GoogleMapsCore i GoogleMapsBase są połączone w pakiet GoogleMaps XCFramework. Nie musisz niczego konfigurować.

Swift Package Manager

Pakiet Maps SDK na iOS można zainstalować za pomocą menedżera pakietów Swift. Aby dodać pakiet SDK, upewnij się, że usunięto wszystkie dotychczasowe zależności pakietu Maps SDK na iOS.

Aby dodać pakiet SDK do nowego lub istniejącego projektu:

1. Otwórz project lub workspace Xcode, a następnie kliknij File > Add Package Dependencies.
2. Wpisz adres URL https://github.com/googlemaps/ios-maps-sdk, naciśnij Enter , aby pobrać pakiet, i kliknij „Add Package” (Dodaj pakiet).
3. Aby zainstalować konkretną version, ustaw w polu Dependency Rule jedną z opcji opartych na wersji. W przypadku nowych projektów zalecamy określenie najnowszej wersji i użycie opcji „Exact Version” (Dokładna wersja). Gdy skończysz, kliknij „Add Package” (Dodaj pakiet).

Aby zaktualizować package w istniejącym projekcie:

1. Jeśli uaktualniasz wersję starszą niż 9.0.0, po uaktualnieniu musisz usunąć te zależności: GoogleMapsBase, GoogleMapsCore i GoogleMapsM4B. Nie usuwaj zależności GoogleMaps. Więcej informacji znajdziesz w informacjach o wersji 9.0.0.

   W ustawieniach konfiguracji projektu Xcode znajdź Frameworks, Libraries, and Embedded Content (Frameworki, biblioteki i treści osadzone). Użyj znaku minusa(-) , aby usunąć te platformy:

   • GoogleMapsBase (tylko w przypadku uaktualniania z wersji starszych niż 9.0.0)
   • GoogleMapsCore (tylko w przypadku uaktualniania z wersji starszych niż 9.0.0)
   • GoogleMapsM4B (tylko w przypadku uaktualniania z wersji starszych niż 9.0.0)
2. W Xcode kliknij „File > Packages > Update To Latest Package Versions” (Plik > Pakiety > Zaktualizuj do najnowszych wersji pakietów).
3. Aby sprawdzić instalację, otwórz sekcję Package Dependencies (Zależności pakietu) w Project Navigator (Nawigator projektu) i sprawdź pakiet oraz jego wersję.

Ważne: czasami nie można rozwiązać artefaktów lub mogą wystąpić błędy. W takim przypadku kliknij "File > Packages > Reset Package Cache" (Plik > Pakiety > Zresetuj pamięć podręczną pakietu).

Aby usunąć dotychczasowe zależności pakietu Maps SDK na iOS dodane za pomocą CocoaPods:

1. Zamknij obszar roboczy Xcode. Otwórz terminal i wykonaj to polecenie:

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

2. Jeśli nie używasz plików Podfile, Podfile.resolved i Xcode workspace do niczego innego niż CocoaPods, usuń je.

Aby usunąć dotychczasowy pakiet Maps SDK na iOS zainstalowany ręcznie: wykonaj następujące czynności:

1. W ustawieniach konfiguracji projektu Xcode znajdź Frameworks, Libraries, and Embedded Content (Frameworki, biblioteki i treści osadzone). Użyj znaku minusa(-) , aby usunąć te platformy:
   • GoogleMaps
   • GoogleMapsBase (tylko w przypadku instalacji starszych niż wersja 9.2.0)
   • GoogleMapsCore (tylko w przypadku instalacji starszych niż wersja 9.2.0)
   • GoogleMapsM4B (tylko w przypadku instalacji starszych niż wersja 9.0.0)
2. Usuń pakiet GoogleMaps z katalogu najwyższego poziomu projektu Xcode.

Instalacja ręczna

W tym przewodniku dowiesz się, jak ręcznie dodać do projektu XCFrameworki zawierające pakiet Maps SDK na iOS i skonfigurować ustawienia kompilacji w Xcode. XCFramework to pakiet binarny, którego można używać na wielu platformach, w tym na komputerach z procesorami Apple silicon.

1. Pobierz te pliki binarne i pliki zasobów pakietu SDK:
   • GoogleMaps
   • GoogleMapsResources
2. Rozpakuj pliki, aby uzyskać dostęp do XCFrameworków i zasobów.
3. Jeśli nie masz jeszcze projektu Xcode, utwórz go i zapisz na komputerze lokalnym. Jeśli dopiero zaczynasz tworzyć aplikacje na iOS:
   1. Utwórz nowy projekt.
   2. Wybierz szablon iOS > App (iOS > Aplikacja).
   3. Na ekranie opcji projektu:
      1. Wpisz Project Name (Nazwa projektu).
      2. Zapisz wartość pola Bundle identifier (Identyfikator pakietu). Możesz użyć tej wartości, aby ograniczyć klucz interfejsu API poniżej.
      3. Ustaw Interface (Interfejs) projektu na Storyboard (Scenorys).
      4. Ustaw Language (Język) na Swift lub Objective-C.
4. Otwórz kartę General (Ogólne). Przeciągnij te XCFrameworki do projektu w sekcji Frameworks, Libraries, and Embedded Content (Frameworki, biblioteki i treści osadzone). Pamiętaj, aby wybrać Do Not Embed:
   • GoogleMaps.xcframework
5. Skopiuj plik GoogleMaps.bundle z pobranego folderu GoogleMapsResources do katalogu najwyższego poziomu projektu Xcode. Gdy pojawi się prośba, wybierz Copy items into destination group's folder (Skopiuj elementy do folderu grupy docelowej).
6. Wybierz projekt w nawigatorze projektu i wybierz element docelowy aplikacji.
7. Otwórz kartę Build Phases (Fazy kompilacji) elementu docelowego aplikacji. W sekcji Link Binary with Libraries (Połącz plik binarny z bibliotekami) dodaj te frameworki i biblioteki:
   • 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 (tylko jeśli używasz OpenGL)
   • QuartzCore.framework
   • Security.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. Wybierz projekt, a nie konkretny element docelowy, i otwórz kartę Build Settings (Ustawienia kompilacji). W sekcji Linking - General -> Other Linker Flags (Łączenie – Ogólne – > Inne flagi konsolidatora) dodaj -ObjC do „Debug” (Debugowanie) i „Release” (Wydanie). Jeśli te ustawienia nie są widoczne, zmień filtr na pasku Build Settings (Ustawienia kompilacji) z Basic (Podstawowe) na All (Wszystkie).

9. Aby zainstalować XCFramework pakietu Places SDK na iOS, zobacz Wprowadzenie do pakietu Places SDK na iOS.

CocoaPods

Wycofane: od 18 sierpnia 2025 r. CocoaPods jest w trybie konserwacji i po II kwartale 2026 r. nie będziemy udostępniać kolejnych wersji CocoaPods. Zamiast tego używaj menedżera pakietów Swift.

Pakiet Maps SDK na iOS jest dostępny jako CocoaPods pod. CocoaPods to menedżer zależności open source dla projektów Cocoa w językach Swift i Objective-C

Jeśli nie masz jeszcze narzędzia CocoaPods, zainstaluj je w systemie macOS, wykonując w terminalu to polecenie. Więcej informacji znajdziesz w przewodniku dla początkujących CocoaPods.

sudo gem install cocoapods

Utwórz plik Podfile dla pakietu Maps SDK na iOS i użyj go do zainstalowania interfejsu API oraz jego zależności:

1. Jeśli nie masz jeszcze projektu Xcode, utwórz go i zapisz na komputerze lokalnym. Jeśli dopiero zaczynasz tworzyć aplikacje na iOS:
   1. Utwórz nowy projekt.
   2. Wybierz szablon iOS > App (iOS > Aplikacja).
   3. Na ekranie opcji projektu:
      1. Wpisz Project Name (Nazwa projektu).
      2. Zapisz wartość pola Bundle identifier (Identyfikator pakietu). Możesz użyć tej wartości, aby ograniczyć klucz interfejsu API poniżej.
      3. Ustaw Interface (Interfejs) projektu na Storyboard (Scenorys).
      4. Ustaw Language (Język) na Swift lub Objective-C.
2. Utwórz w katalogu projektu plik o nazwie Podfile. Ten plik określa zależności projektu.
3. Edytuj Podfile i dodaj zależności wraz z ich wersjami. Oto przykład, który zawiera zależność potrzebną do korzystania z pakietu Maps SDK na iOS:

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

   Regularnie uruchamiaj pod outdated, aby wykrywać nowsze wersje i mieć pewność, że zawsze używasz najnowszej wersji. W razie potrzeby, uaktualnij do najnowszej wersji.
4. Zapisz plik Podfile.

5. Otwórz terminal i przejdź do katalogu zawierającego plik Podfile:

   cd <path-to-project>

6. Uruchom polecenie pod install. Spowoduje to zainstalowanie interfejsów API określonych w pliku Podfile wraz z ich zależnościami.

   pod install

7. Zamknij Xcode, a następnie otwórz (kliknij dwukrotnie) plik .xcworkspace projektu, aby uruchomić Xcode. Od tej pory musisz używać pliku .xcworkspace do otwierania projektu.

Aby zaktualizować interfejs API w istniejącym projekcie:

1. Otwórz terminal i przejdź do katalogu projektu zawierającego plik Podfile.
2. Uruchom polecenie pod update. Spowoduje to zaktualizowanie wszystkich interfejsów API określonych w Podfile do najnowszej wersji.

Krok 3. Dodaj klucz interfejsu API do projektu

W sekcji Uzyskiwanie klucza interfejsu API wygenerowano klucz interfejsu API dla aplikacji. Teraz dodaj ten klucz do projektu Xcode.

W poniższych przykładach zastąp YOUR_API_KEY swoim kluczem interfejsu API.

Uwaga: jeśli zapiszesz identyfikator pakietu projektu lub uzyskasz go we właściwościach projektu, możesz użyć go do ograniczenia klucza interfejsu API do używania tylko w aplikacjach na iOS z tym konkretnym identyfikatorem pakietu. Więcej informacji znajdziesz w artykule Ograniczanie kluczy interfejsu API.

Swift

Dodaj klucz interfejsu API do pliku AppDelegate.swift w ten sposób:

1. Dodaj to stwierdzenie importu:

   import GoogleMaps

2. Dodaj to do metody application(_:didFinishLaunchingWithOptions:), używając klucza interfejsu API:

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. Jeśli używasz też interfejsu Places API, dodaj klucz ponownie w sposób pokazany tutaj:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

Dodaj klucz interfejsu API do pliku AppDelegate.m w ten sposób:

1. Dodaj to stwierdzenie importu:

   @import GoogleMaps;

2. Dodaj to do metody application:didFinishLaunchingWithOptions:, używając klucza interfejsu API:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. Jeśli używasz też interfejsu Places API, dodaj klucz ponownie w sposób pokazany tutaj:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Krok 4 (opcjonalny). Sprawdź plik manifestu prywatności Apple

Uwaga: poniższe informacje są istotne, gdy wdrażasz aplikację w sklepie internetowym.

Firma Apple wymaga, aby aplikacje w App Store zawierały szczegółowe informacje o ochronie prywatności. Aby uzyskać aktualne informacje, otwórz stronę Apple App Store Privacy Details.

Plik manifestu prywatności Apple jest zawarty w pakiecie zasobów pakietu SDK. Aby sprawdzić, czy plik manifestu prywatności został dołączony, i sprawdzić jego zawartość, utwórz archiwum aplikacji i wygeneruj raport o ochronie prywatności na podstawie tego archiwum.

Krok 5 (opcjonalny). Zadeklaruj schematy adresów URL używane przez interfejs API

Od wersji iOS 9 i Xcode 7 aplikacje mogą deklarować schematy adresów URL, które mają być otwierane, określając je w pliku Info.plist aplikacji. Pakiet Maps SDK na iOS otwiera aplikację mobilną Mapy Google, gdy użytkownik kliknie logo Google na mapie, dlatego Twoja aplikacja może deklarować odpowiednie schematy adresów URL.

Aby zadeklarować schematy adresów URL używane przez pakiet Maps SDK na iOS, dodaj te wiersze do pliku Info.plist:

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

Ten zrzut ekranu przedstawia konfigurację w interfejsie Xcode:

Jeśli nie zadeklarujesz schematów adresów URL, gdy użytkownik kliknie logo Google na mapie, mogą wystąpić te błędy:

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

Aby wyeliminować te błędy, dodaj deklarację do pliku Info.plist.

Co dalej?

Teraz, gdy masz klucz interfejsu API i projekt Xcode, możesz tworzyć i uruchamiać aplikacje. Pakiet Navigation SDK na iOS zawiera wiele samouczków i przykładowych aplikacji, które pomogą Ci zacząć. Więcej informacji znajdziesz w tych artykułach:

• Te samouczki są zalecane na początek:
  • Dodawanie mapy ze znacznikiem.
  • Wybieranie aktualnego miejsca i wyświetlanie szczegółów na mapie.
  • Odwrotne geokodowanie.
• Zapoznaj się z dostępnymi przykładami kodu i warsztatami programistycznymi.
• Aby poznać kompleksowe rozwiązania, zapoznaj się z dostępnymi rozwiązaniami Map.