This page describes how to set up the utility library for the Maps SDK for iOS.
To try these utilities, you can either:
- Install and run the demo app. The demo app is a stand-alone project that contains all of the code required to try out the utilities.
- Install the utility library's into an existing Xcode project. Add these utilities in your own project.
Optionally install CocoaPods
The utility library is available as a CocoaPods pod named
Google-Maps-iOS-Utils
. 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:
sudo gem install cocoapods
For details, see the CocoaPods Getting Started guide.
Install and run the demo app
The utility library includes a demo app that you can install and then try out each utility.
Install the demo app by using one of these two methods:Use files from GitHub
- Download the code sample archive from GitHub and unpack the archive.
- Open a terminal window, navigate to the directory where you expanded the sample files, and
drill down into the appropriate samples directory for the language you want to use:
- For Swift, run
cd google-maps-ios-utils-master/samples/SwiftDemoApp
- For Objective-C, run
cd google-maps-ios-utils-master/samples/ObjCDemoApp
- For Swift, run
- Run the following command:
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.
Use CocoaPods v1.6.1
- Open a terminal window and install version 1.6.1:
sudo gem install cocoapods -v1.6.1
- Fetch the Google Maps files using Cocoapods:
pod try Google-Maps-iOS-Utils
Choose either Swift or Objective-C when prompted. CocoaPods updates your spec repositories, then opens the demo in a temporary Xcode project named
SwiftDemoApp.xcodeproj
orObjCDemoApp.xcodeproj
.
Add the API key to the demo app
In Get an API key, you generate an API key for your app. Now add that key to the Xcode project for the demo app.Swift
Add your API key to your AppDelegate.swift
as follows:
- Add the following import statement:
import GoogleMaps
- Edit the following line to add your API key between the double quotes:
// Change this key to a valid key registered with the demo app bundle id. let mapsAPIKey = ""
Objective-C
Add your API key to your AppDelegate.m
as follows:
- Add the following import statement:
@import GoogleMaps;
- Edit the following line to add your API key between the double quotes:
// Change this key to a valid key registered with the demo app bundle id. static NSString *const kMapsAPIKey = @"";
Build and run the demo app
After you add the API key, build and run the project:
- If you are running the Swift version of the demo, you can select which utility to view in the app.
- If you are running the Objective-C version of the demo, you see the demo of the marker clustering utility. You can then edit the Objective-C version of the demo to try each utility. See the Add a utility to your app section below for more information.
Install the utility library as an Xcode project
Follow these steps to add the utility library to your Xcode workspace:
Use CocoaPods
- 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 Single View Application.)
- If you don't already have a pod file for your project, create a file
named
Podfile
in your project directory. This file defines your project's dependencies. - Edit your project's pod file and add a dependency on the
Google-Maps-iOS-Utils
pod. Here is an example which includes the dependencies you need for the Maps SDK for iOS and the utility library:source 'https://github.com/CocoaPods/Specs.git' platform :ios, '13.0' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do use_frameworks! pod 'GoogleMaps', '7.4.0' pod 'Google-Maps-iOS-Utils', '4.1.0' end
- Run
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.
Note: The marker clustering utility is dependent on the
quadtree, but you can use the quadtree without marker clustering. If you want
only the quadtree utility, you can change
pod 'Google-Maps-iOS-Utils'
to
'Google-Maps-iOS-Utils/QuadTree'
in your pod file.
Use Carthage
- Install Carthage. There are several methods, so see the Carthage README file for exact steps.
- If you don't have an Xcode project yet, create one now and save it to your local machine. (If you're newer to iOS development, create a new project and select the iOS App template. In Xcode 11.7 or earlier, create a Single View Application.)
- Create a file named
Cartfile
in your project directory. This file defines your project's dependencies. - Edit the
Cartfile
and add the Maps SDK for iOS Utility Library dependency:
github "googlemaps/google-maps-ios-utils"
- Save the
Cartfile
. - In a terminal window, go to the directory containing the
Cartfile
:
cd <path-to-project>
- Run the update command:
carthage update --platform iOS
This will install the APIs specified in theCartfile
, along with any dependencies they may have. - In the Finder, in your project directory, go to the downloaded framework files under
Carthage/Build/iOS
. - Add the Maps SDK for iOS frameworks into your project by dragging the following bundles into your project.
(When prompted, select Copy items if needed, please use the same version as above.)
GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.framework
GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.framework
GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.framework
GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsUtils.framework
GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.framework
. - Right-click
GoogleMaps.framework
in your project, and select Show In Finder. - Drag the
Carthage/Build/iOS/GoogleMaps.framework/Resources/GoogleMaps.bundle
from theResources
folder into your project. When prompted, ensure Copy items into destination group's folder is not selected. - Select your project from the Project Navigator, and choose your application's target.
- Open the Build Phases tab for your application’s target, and within Link Binary with
Libraries, add the following frameworks:
Accelerate.framework
CoreData.framework
CoreGraphics.framework
CoreImage.framework
CoreLocation.framework
CoreTelephony.framework
CoreText.framework
GLKit.framework
ImageIO.framework
libc++.tbd
libz.tbd
OpenGLES.framework
QuartzCore.framework
SystemConfiguration.framework
UIKit.framework
Choose your project, rather than a specific target, and open the Build Settings tab. In the Other Linker Flags section, add
-ObjC
. If these settings are not visible, change the filter in the Build Settings bar from Basic to All.
Use Swift Package Manager
- 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 and select the iOS App template. On Xcode 11.7 or older, create a Single View Application.)
- Add the Maps SDK for iOS as a dependency. See Installing the SDK for options.
- In your Xcode project, navigate to File -> Swift Packages -> Add Package Dependency.
- In the presented window, enter the Maps SDK for iOS Utility Library repository URL
https://github.com/googlemaps/google-maps-ios-utils
and select Next. - At this point, you may be prompted to authenticate with your GitHub account. Follow the instructions to create a GitHub personal access token to continue the process.
- In the next window, select the Version radio option, select Exact from the dropdown list, enter the latest version of the Maps SDK for iOS Utility Library (e.g. "3.4.0") and select Next.
Add the API key to your app
See Set up an Xcode Project for instructions on generating an API key and adding it to your Xcode project.Build and run the project
After you add the API key, build and run the project.
Add a utility to your app
See the documentation on each utility for more information on using it in your app: