After you enable billing and create an API key, you're ready to set up the Xcode project that you use to develop your app.
Release notes are available for each release.
Step 1: Install the required software
To build a project using the Navigation SDK for iOS, you must download and install:
- Xcode version 15.0 or later
Step 2: Create the Xcode project and install the Navigation SDK
Swift Package Manager
The Navigation SDK can be installed via Swift Package Manager. To add the SDK, ensure you have removed any existing Navigation SDK dependencies.
To add the SDK to a new or existing project, follow these steps:
-
Open your Xcode
project
orworkspace
, then go to File > Add Package Dependencies. - Enter https://github.com/googlemaps/ios-navigation-sdk as the URL, press Enter to pull in the package, and click "Add Package".
-
To install a specific
version
, set the Dependency Rule field to one of the version-based options. For new projects, we recommend specifying the latest version and using the "Exact Version" option. Once complete, click "Add Package". -
From the Choose Package Products window, verify
GoogleNavigation
will be added to your designatedmain
target. Once complete, click "Add Package". -
To verify your installation, navigate to your target's
General
pane. In the Frameworks, Libraries, and Embedded Content you should see the installed packages. You can also view the "Package Dependencies" section of "Project Navigator" to verify the package and its version.
To update the package
for an existing project, follow these steps:
If you are upgrading from a version earlier than 9.0.0, you must remove the following dependencies:
GoogleMapsBase
,GoogleMapsCore
, andGoogleMapsM4B
after upgrading. Do not remove the dependency forGoogleMaps
. For more information, see the Version 9.0.0 Release Notes.From your Xcode project configuration settings, find Frameworks, Libraries, and Embedded Content. Use the minus sign(-) to remove the following framework:
GoogleMapsBase
(Only for upgrades from versions earlier than 9.0.0)GoogleMapsCore
(Only for upgrades from versions earlier than 9.0.0)GoogleMapsM4B
(Only for upgrades from versions earlier than 9.0.0)
- From Xcode, go to "File > Packages > Update To Latest Package Versions".
- To verify your installation, go to the Package Dependencies section of Project Navigator to verify the package and its version.
To remove existing Navigation SDK dependencies added using
CocoaPods
, follow these steps:
- Close your Xcode workspace. Open terminal and execute the following command:
sudo gem install cocoapods-deintegrate cocoapods-clean pod deintegrate pod cache clean --all
-
Remove the
Podfile
,Podfile.resolved
and the Xcodeworkspace
if you are not using them for anything other than CocoaPods.
-
From your Xcode project configuration settings, find Frameworks, Libraries,
and Embedded Content. Use the minus sign(-) to remove the following framework:
GoogleMaps.xcframework
GoogleMapsBase.xcframework
GoogleMapsCore.xcframework
GoogleNavigation.xcframework
-
From the top level directory of your Xcode project, remove the
GoogleMaps
bundle.
CocoaPods
The Navigation SDK for iOS is available as a CocoaPods pod. CocoaPods is an open source dependency manager for Swift and Objective-C Cocoa projects.
If you don't already have the CocoaPods tool, install it on macOS by running the following command from the terminal. For details, see the CocoaPods Getting Started guide.
sudo gem install cocoapods
Create a Podfile
for the Navigation SDK for iOS and use
it to install the API and its dependencies:
- If you don't have an Xcode project yet, create one now and save it to
your local machine. If you're new to iOS development:
- Create a new project.
- Select the iOS > App template.
- On the project options screen:
- Enter the Project Name.
- Record the value of the Bundle identifier field. You can use that value to restrict your API key below.
- Set the project Interface to Storyboard.
- Set the Language to Swift or Objective-C.
- Create a file named
Podfile
in your project directory. This file defines your project's dependencies. - Edit the
Podfile
and add your dependencies along with their versions. Here is an example which includes the dependency you need for the Navigation SDK for iOS: # Cocoapods install reference #source 'https://github.com/CocoaPods/Specs.git' platform :ios, '15.0' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GoogleNavigation', '9.0.0' end
Make sure to regularly runpod outdated
to detect newer versions. If necessary, upgrade to the latest version. - Save the
Podfile
. Open a terminal and go to the directory containing the
Podfile
:cd <path-to-project>
Run the
pod install
command. This installs the APIs specified in thePodfile
, along with any dependencies.pod install
Close Xcode, and then open (double-click) your project's
.xcworkspace
file to launch Xcode. From this time onwards, you must use the.xcworkspace
file to open the project.
To update the API for an existing project, follow these steps:
- Open a terminal and go to the project directory containing the
Podfile
. - Run the
pod update
command. This updates all the APIs specified in thePodfile
to the latest version.
Manual installation
This guide shows how to manually add the XCFrameworks containing the Navigation SDK for iOS, and the Maps SDK for iOS to your project and configure your build settings in Xcode. An XCFramework is a binary package that you can use on multiple platforms, including machines using the M1 chipset
Follow these steps to install the XCFrameworks for the Navigation SDK for iOS, and the Maps SDK for iOS:
- Download the following SDK binaries and resource files:
- Launch Xcode and either open an existing project, or create a new project. If you're new to iOS, create a new project and select the iOS App template.
- Remove all existing Maps, Navigation, and Places references from the project.
- Drag the following XCFrameworks into your project under
Frameworks, Libraries, and Embedded Content to install both the Maps
and Navigation SDKs (when prompted, select Copy items if needed):
GoogleMaps.xcframework
GoogleMapsBase.xcframework
GoogleMapsCore.xcframework
GoogleNavigation.xcframework
- Drag
GoogleMaps.bundle
from GoogleMapsResources you downloaded into the top level directory of your Xcode project. When prompted, ensure Copy items if needed is selected. - Drag
GoogleNavigation.bundle
from GoogleNavigationResources you downloaded into the top level directory of your Xcode project. When prompted, ensure Copy items into destination group's folder is selected. - Select your project from the Project Navigator, and choose your application's target.
- Open the Build Phases tab, and within
Link Binary with Libraries, add the following frameworks and libraries:
Accelerate.framework
AudioToolbox.framework
AVFoundation.framework
Contacts.framework
CoreData.framework
CoreGraphics.framework
CoreImage.framework
CoreLocation.framework
CoreTelephony.framework
CoreText.framework
GLKit.framework
ImageIO.framework
libc++.tbd
libxml2.tbd
libz.tbd
Metal.framework
OpenGLES.framework
QuartzCore.framework
Security.framework
SystemConfiguration.framework
UIKit.framework
UserNotifications.framework
WebKit.framework
- In your application's target, select the Capabilities tab,
turn on Background Modes, and enable the following modes:
- Audio, AirPlay, and Picture in Picture
- Location updates
- Choose your project, rather than a specific target, and open the Build
Settings tab. In the Other Linker Flags section,
add
‑ObjC
for both debug and release. If these settings are not visible, change the filter in the Build Settings bar from Basic to All. - Open
Info.plist
and add the following key-value pairs:- Key:
NSLocationWhenInUseUsageDescription
(Privacy - Location When In Use Usage Description)
Value: "This app needs permission to use your location for turn-by-turn navigation." - Key:
NSLocationAlwaysAndWhenInUseUsageDescription
(Privacy - Location Always and When In Use Usage Description)
Value: "This app needs permission to use your location for turn-by-turn navigation."
- Key:
Step 3: Inspect Apple Privacy Manifest file
Apple requires app privacy details for apps on the App Store. Visit the Apple App Store Privacy Details page for updates and more information.
The Apple Privacy Manifest file is included in the resources bundle for the SDK. To verify that the Privacy Manifest File has been included, and to inspect its contents, create an archive of your app and generate a privacy report from the archive.
Step 4: Add your API key to the project
The following examples show how to add the API key to your project in Xcode:
Swift
Add your API key to your AppDelegate.swift
as follows:
- Add the following import statements:
import GoogleMaps import GoogleNavigation
- Add the following to your
application(_:didFinishLaunchingWithOptions:)
method:GMSServices.provideAPIKey("YOUR_API_KEY")
Objective-C
Add your API key to your AppDelegate.m
as follows:
- Add the following import statements:
@import GoogleMaps; @import GoogleNavigation;
- Add the following to your
application:didFinishLaunchingWithOptions:
method:[GMSServices provideAPIKey:@"YOUR_API_KEY"];
Step 5: Add a map
This code demonstrates how to add a simple map to an existing ViewController
,
including some initial settings for navigation.
Before navigation can be enabled, the user must agree to the terms and
conditions. To prompt the user, call
GMSNavigationServices.showTermsAndConditionsDialogIfNeeded()
, then check to
see whether the terms have been accepted. If the user rejects the terms,
mapView.isNavigationEnabled = true
has no effect, and mapView.navigator
is
nil.
Swift
import UIKit import GoogleNavigation class ViewController: UIViewController { var mapView: GMSMapView! var locationManager: CLLocationManager! override func loadView() { locationManager = CLLocationManager() locationManager.requestAlwaysAuthorization() let options = GMSMapViewOptions() options.camera = camera options.frame = .zero mapView = GMSMapView(options: options) // Show the terms and conditions. let termsAndConditionsOptions = GMSNavigationTermsAndConditionsOptions(companyName: "Ride Share Co.") GMSNavigationServices.showTermsAndConditionsDialogIfNeeded(with: termsAndConditionsOptions) { termsAccepted in if termsAccepted { // Enable navigation if the user accepts the terms. self.mapView.isNavigationEnabled = true } else { // Handle the case when the user rejects the terms and conditions. } } view = mapView } // TODO: Add navigation code. }
Objective-C
#import "ViewController.h" @import GoogleNavigation; @interface ViewController () @end @implementation ViewController GMSMapView *_mapView; CLLocationManager *_locationManager; - (void)loadView { _locationManager = [[CLLocationManager alloc] init]; [_locationManager requestAlwaysAuthorization]; GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:47.67 longitude:-122.20 zoom:14]; GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init]; options.frame = CGRectZero; options.camera = camera; options.mapID = mapID; _mapView = [[GMSMapView alloc] initWithOptions:options]; // Show the terms and conditions. GMSNavigationTermsAndConditionsOptions *termsAndConditionsOptions = [[GMSNavigationTermsAndConditionsOptions alloc] initWithCompanyName:@"Ride Sharing Co."]; [GMSNavigationServices showTermsAndConditionsDialogIfNeededWithOptions:termsAndConditionsOptions callback:^(BOOL termsAccepted) { if (termsAccepted) { // Enable navigation if the user accepts the terms. _mapView.navigationEnabled = YES; } else { // Handle the case when the user rejects the terms and conditions. } }]; self.view = _mapView; } // TODO: Add navigation code. @end
Run your application. You should see a map centered over Kirkland, Washington.
If the map is not visible, try the following:
- Confirm that you have provided the correct API key.
- Check that NavSDK is enabled in Cloud Console.
- If the Nav SDK is installed, but your project does not use Nav SDK APIs, remove it from your binary.
If you are a Mobility Services customer
If you are a Mobility Services customer, learn about billing in the Mobility documentation. For more information about recording transactions, see Set up billing. To learn how to add transaction IDs to your Navigation SDK implementation, see Associate your service usage to Mobility transactions.
What's next
Now that you have an API key and an Xcode project, you can create and run apps. The Navigation SDK for iOS provides tutorials that can help you get started. For more details, see:
- Tutorials