Thêm SDK Bản đồ cho Thư viện tiện ích iOS vào dự án Xcode
Làm theo các bước sau để thêm thư viện tiện ích vào không gian làm việc Xcode:
Sử dụng Trình quản lý gói Swift
Nếu bạn chưa có dự án Xcode, hãy tạo một dự án ngay và lưu dự án đó vào máy cục bộ.
(Nếu bạn mới bắt đầu phát triển iOS, hãy tạo một dự án mới rồi chọn mẫu Ứng dụng iOS. Trên Xcode 11.7 trở xuống, hãy tạo một Single View Application (Ứng dụng một chế độ xem).)
Thêm SDK Bản đồ dành cho iOS làm phần phụ thuộc. Hãy xem phần Cài đặt SDK để biết các tuỳ chọn.
Trong dự án Xcode, hãy chuyển đến File (Tệp) -> Swift Packages (Gói Swift) -> Add Package Dependency (Thêm phần phụ thuộc gói).
Trong cửa sổ hiển thị, hãy nhập URL kho lưu trữ Thư viện tiện ích SDK Maps cho iOS
https://github.com/googlemaps/google-maps-ios-utils rồi chọn Tiếp theo.
Tại thời điểm này, bạn có thể được nhắc xác thực bằng tài khoản GitHub. Làm theo hướng dẫn để tạo mã thông báo truy cập cá nhân trên GitHub nhằm tiếp tục quy trình.
Trong cửa sổ tiếp theo, hãy chọn tuỳ chọn Phiên bản, chọn Tới phiên bản chính tiếp theo trong danh sách thả xuống rồi nhập phiên bản mới nhất của SDK Maps cho Thư viện tiện ích iOS (ví dụ: "6.0.0").
Nhấp vào trình đơn thả xuống bên cạnh Thêm vào dự án, chọn dự án của bạn rồi chọn Thêm gói.
Sử dụng CocoaPods
Nếu bạn chưa có dự án Xcode, hãy tạo một dự án ngay và lưu dự án đó vào máy cục bộ. (Nếu bạn mới làm quen với việc phát triển iOS, hãy tạo một Ứng dụng có một thành phần hiển thị.)
Nếu bạn chưa có tệp pod cho dự án, hãy tạo một tệp có tên là Podfile trong thư mục dự án. Tệp này xác định các phần phụ thuộc của dự án.
Chỉnh sửa tệp pod của dự án và thêm phần phụ thuộc vào pod Google-Maps-iOS-Utils. Dưới đây là một ví dụ bao gồm các phần phụ thuộc bạn cần cho SDK Bản đồ dành cho iOS và thư viện tiện ích:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '16.0'
target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
use_frameworks!
pod 'GoogleMaps', '10.0.0'
pod 'Google-Maps-iOS-Utils', '6.1.2' # x-release-please-version
end
Chạy pod install.
Đóng Xcode, sau đó mở (nhấp đúp) tệp .xcworkspace của dự án để chạy Xcode. Từ thời điểm này trở đi, bạn phải sử dụng tệp .xcworkspace để mở dự án.
Lưu ý: Tiện ích cụm điểm đánh dấu phụ thuộc vào cây 4 chiều, nhưng bạn có thể sử dụng cây 4 chiều mà không cần cụm điểm đánh dấu. Nếu chỉ muốn sử dụng tiện ích quadtree, bạn có thể thay đổi pod 'Google-Maps-iOS-Utils' thành 'Google-Maps-iOS-Utils/QuadTree' trong tệp pod.
Thêm khoá API vào ứng dụng
Hãy xem phần Thiết lập dự án Xcode để biết hướng dẫn tạo khoá API và thêm khoá đó vào dự án Xcode.
Tạo bản dựng và chạy dự án
Sau khi thêm khoá API, hãy tạo và chạy dự án.
Sử dụng tiện ích trong ứng dụng
Hãy xem tài liệu về từng tiện ích để biết thêm thông tin về cách sử dụng tiện ích đó trong ứng dụng:
Mở cửa sổ dòng lệnh, chuyển đến thư mục mà bạn đã mở rộng các tệp mẫu và đi sâu vào thư mục mẫu thích hợp cho ngôn ngữ bạn muốn sử dụng:
Đối với Swift, hãy chạy cd google-maps-ios-utils-master/samples/SwiftDemoApp
Đối với Objective-C, hãy chạy cd google-maps-ios-utils-master/samples/ObjCDemoApp
Chạy lệnh sau:
pod install
Đóng Xcode, sau đó mở (nhấp đúp) tệp .xcworkspace của dự án để chạy Xcode. Từ thời điểm này trở đi, bạn phải sử dụng tệp .xcworkspace để mở dự án.
Thêm khoá API vào ứng dụng minh hoạ
Trong phần Tạo khoá API, bạn sẽ tạo một khoá API cho ứng dụng của mình. Bây giờ, hãy thêm khoá đó vào dự án Xcode cho ứng dụng minh hoạ.
Swift
Thêm khoá API vào AppDelegate.swift như sau:
Thêm câu lệnh nhập sau:
importGoogleMaps
Chỉnh sửa dòng sau để thêm khoá API của bạn vào giữa dấu ngoặc kép:
// Change this key to a valid key registered with the demo app bundle id.letmapsAPIKey=""
Objective-C
Thêm khoá API vào AppDelegate.m như sau:
Thêm câu lệnh nhập sau:
@importGoogleMaps;
Chỉnh sửa dòng sau để thêm khoá API của bạn vào giữa dấu ngoặc kép:
// Change this key to a valid key registered with the demo app bundle id.staticNSString*constkMapsAPIKey=@"";
Tạo bản dựng và chạy ứng dụng minh hoạ
Sau khi bạn thêm khoá API, hãy tạo và chạy dự án:
Nếu đang chạy phiên bản Swift của bản minh hoạ, bạn có thể chọn tiện ích để xem trong ứng dụng.
Nếu đang chạy phiên bản Objective-C của bản minh hoạ, bạn sẽ thấy bản minh hoạ về tiện ích cụm điểm đánh dấu. Sau đó, bạn có thể chỉnh sửa phiên bản Objective-C của bản minh hoạ để thử từng tiện ích.
Hãy xem phần Thêm tiện ích vào ứng dụng ở bên dưới để biết thêm thông tin.
[null,null,["Cập nhật lần gần đây nhất: 2025-07-26 UTC."],[[["\u003cp\u003eThis documentation guides you on setting up and utilizing the Google Maps SDK for iOS Utility Library, offering tools like marker clustering, quadtrees, and data rendering.\u003c/p\u003e\n"],["\u003cp\u003eYou can integrate the library into your Xcode project using Swift Package Manager or CocoaPods, then access utilities for enhanced map functionalities.\u003c/p\u003e\n"],["\u003cp\u003eA demo app is available for exploring these utilities; you can install it via GitHub or CocoaPods and add your API key for testing.\u003c/p\u003e\n"],["\u003cp\u003eBefore running the demo app or your own project, ensure you have a valid API key and potentially adjust bundle identifiers for application restrictions.\u003c/p\u003e\n"],["\u003cp\u003eDetailed instructions and code examples are provided for both Swift and Objective-C to facilitate seamless integration and usage of the library.\u003c/p\u003e\n"]]],["To integrate the Maps SDK for iOS Utility Library, you can add it to an existing Xcode project via Swift Package Manager or CocoaPods. This involves adding the library's repository URL or pod dependency, selecting the desired version, and running the installation. Alternatively, you can install and run a demo app by downloading the code from GitHub, installing the dependencies with `pod install`, and adding your API key. Finally you can build and run the project.\n"],null,["Select platform: [Android](/maps/documentation/android-sdk/utility/setup \"View this page for the Android platform docs.\") [iOS](/maps/documentation/ios-sdk/utility/setup \"View this page for the iOS platform docs.\")\n\nThis page describes how to set up the\n[utility library\nfor the Maps SDK for iOS](https://github.com/googlemaps/google-maps-ios-utils).\n\nTo try these utilities, you can either:\n\n- [Install the utility library's into an existing Xcode project](#get-utility). Add these utilities in your own project.\n- [Install and run the demo app](#get-demo). The demo app is a standalone project that contains all of the code required to try out the utilities.\n\nAdd the Maps SDK for iOS Utility Library to an Xcode project\n\nFollow these steps to add the utility library to your Xcode workspace: \n\nUse Swift Package Manager\n\n1. 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\n template** . On Xcode 11.7 or older, create a **Single View Application**.)\n2. Add the Maps SDK for iOS as a dependency. See [Installing the SDK](/maps/documentation/ios-sdk/config#download-sdk) for options.\n3. In your Xcode project, navigate to **File** -\\\u003e **Swift Packages** -\\\u003e **Add Package Dependency**.\n4. 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**.\n - At this point, you may be prompted to authenticate with your GitHub account. Follow the instructions to create a [GitHub\n personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) to continue the process.\n5. In the next window, select the **Version** radio option, select **Up to Next Major Version** from the drop-down list, and enter the latest [version](https://github.com/googlemaps/google-maps-ios-utils/releases) of the Maps SDK for iOS Utility Library (for example, \"6.0.0\").\n6. Click the drop-down next to **Add to Project** , select your project, and select **Add Package**.\n\nUse CocoaPods\n\n1. 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\n View Application*.)\n2. 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.\n3. 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: \n\n ```scdoc\n source 'https://github.com/CocoaPods/Specs.git'\n platform :ios, '16.0'\n\n target 'YOUR_APPLICATION_TARGET_NAME_HERE' do\n use_frameworks!\n pod 'GoogleMaps', '10.0.0'\n pod 'Google-Maps-iOS-Utils', '6.1.2' # x-release-please-version\n end\n ```\n4. Run `pod install`.\n5. 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.\n\n**Note:** The marker clustering utility is dependent on the\nquadtree, but you can use the quadtree without marker clustering. If you want\nonly the quadtree utility, you can change\n`pod 'Google-Maps-iOS-Utils'` to\n`'Google-Maps-iOS-Utils/QuadTree'` in your pod file.\n\nAdd the API key to your app See [Set up an Xcode Project](/maps/documentation/ios-sdk/config) for instructions on generating an API key and adding it to your Xcode project.\n\nBuild and run the project\n\nAfter you add the API key, build and run the project.\n\nUse a utility in your app\n\nSee the documentation on each utility for more information on using it in your app:\n\n- [Marker\n clustering](/maps/documentation/ios-sdk/utility/marker-clustering)\n- [Quadtree](/maps/documentation/ios-sdk/utility/quadtree)\n- [KML rendering](/maps/documentation/ios-sdk/utility/kml)\n- [GeoJSON rendering](/maps/documentation/ios-sdk/utility/geojson)\n- [Heatmap](/maps/documentation/ios-sdk/utility/heatmap)\n\nInstall and run the demo app\n\nThe utility library includes a demo app that you can install and then try out each utility.\nInstall the demo app: \n\nUse files from GitHub\n\n1. [Download\n the code sample archive](https://github.com/googlemaps/google-maps-ios-utils/archive/master.zip) from [GitHub](https://github.com/googlemaps/google-maps-ios-utils/tree/master/samples) and unpack the archive.\n2. 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:\n - For Swift, run `cd google-maps-ios-utils-master/samples/SwiftDemoApp`\n - For Objective-C, run `cd google-maps-ios-utils-master/samples/ObjCDemoApp`\n3. Run the following command: \n\n ```text\n pod install\n ```\n4. 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.\n\nAdd the API key to the demo app In [Get an API key](/maps/documentation/ios-sdk/get-api-key), you generate an API key for your app. Now add that key to the Xcode project for the demo app. **Note:** If your API key uses an **Application restriction** , ensure that you add the bundle identifier of your app to the key. For example, if you are running the demo app, the bundle identifier is `com.google.gmsutils.DemoApp`. See [Get an API key](/maps/documentation/ios-sdk/get-api-key) for more information on restricting a key. \n\nSwift\n\nAdd your API key to your `AppDelegate.swift` as follows:\n\n1. Add the following import statement: \n\n ```swift\n import GoogleMaps\n ```\n2. Edit the following line to add your API key between the double quotes: \n\n ```swift\n // Change this key to a valid key registered with the demo app bundle id.\n let mapsAPIKey = \"\"\n ```\n\nObjective-C\n\nAdd your API key to your `AppDelegate.m` as follows:\n\n1. Add the following import statement: \n\n ```objective-c\n @import GoogleMaps;\n ```\n2. Edit the following line to add your API key between the double quotes: \n\n ```objective-c\n // Change this key to a valid key registered with the demo app bundle id.\n static NSString *const kMapsAPIKey = @\"\";\n ```\n\nBuild and run the demo app\n\nAfter you add the API key, build and run the project:\n\n- If you are running the Swift version of the demo, you can select which utility to view in the app.\n- 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](#add_utility) section below for more information."]]
