Sau khi bật tính năng thanh toán và tạo khoá API, bạn có thể thiết lập dự án Xcode mà bạn dùng để phát triển ứng dụng.
Ghi chú phát hành có sẵn cho mỗi bản phát hành.
Bước 1: Cài đặt phần mềm cần thiết
Để tạo một dự án bằng SDK Địa điểm dành cho iOS, bạn cần:
- Xcode phiên bản 15.0 trở lên
Bước 2: Tạo dự án Xcode và cài đặt SDK Địa điểm dành cho iOS
Trình quản lý gói Swift
Bạn có thể cài đặt SDK Địa điểm dành cho iOS thông qua Trình quản lý gói Swift. Để thêm SDK này, hãy đảm bảo bạn đã xoá mọi phần phụ thuộc hiện có của SDK Địa điểm dành cho iOS.
Để thêm SDK vào một dự án mới hoặc hiện có, hãy làm theo các bước sau:
-
Mở Xcode
project
hoặcworkspace
, sau đó chuyển đến File > Add Package Dependencies (Tệp > Thêm phần phụ thuộc gói). - Nhập https://github.com/googlemaps/ios-places-sdk làm URL, nhấn Enter để kéo gói vào và nhấp vào "Thêm gói".
-
Để cài đặt một
version
cụ thể, hãy đặt trường Quy tắc phần phụ thuộc thành một trong các tuỳ chọn dựa trên phiên bản. Đối với dự án mới, bạn nên chỉ định phiên bản mới nhất và sử dụng tuỳ chọn "Phiên bản chính xác". Sau khi hoàn tất, hãy nhấp vào "Thêm gói". -
Trong cửa sổ Choose Package Products (Chọn sản phẩm gói), hãy xác minh rằng
GooglePlaces
sẽ được thêm vào mục tiêumain
mà bạn chỉ định. Sau khi hoàn tất, hãy nhấp vào "Thêm gói". -
Để xác minh việc cài đặt, hãy chuyển đến ngăn
General
của mục tiêu. Trong Frameworks, Libraries và Embedded Content (Nội dung được nhúng), bạn sẽ thấy các gói đã cài đặt. Bạn cũng có thể xem phần "Package Dependencies" (Phần phụ thuộc của gói) trong "Project Navigator" (Trình điều hướng dự án) để xác minh gói và phiên bản của gói đó.
Để cập nhật package
cho một dự án hiện có, hãy làm theo các bước sau:
Nếu nâng cấp từ một phiên bản trước 9.0.0, thì bạn phải xoá các phần phụ thuộc sau:
GoogleMapsBase
,GoogleMapsCore
vàGoogleMapsM4B
sau khi nâng cấp. Đừng xoá phần phụ thuộc choGoogleMaps
. Để biết thêm thông tin, hãy xem Ghi chú phát hành phiên bản 9.0.0.Trong phần cài đặt cấu hình của dự án Xcode, hãy tìm Khung, Thư viện và Nội dung được nhúng. Sử dụng dấu trừ(-) để xoá khung sau:
GoogleMapsBase
(Chỉ dành cho các bản nâng cấp từ phiên bản trước 9.0.0)GoogleMapsCore
(Chỉ dành cho các bản nâng cấp từ phiên bản trước 9.0.0)GoogleMapsM4B
(Chỉ dành cho các bản nâng cấp từ phiên bản trước 9.0.0)
- Trong Xcode, hãy chuyển đến "File > Packages > Update To New Package Versions" (Tệp > Gói > Cập nhật lên phiên bản gói mới nhất).
- Để xác minh quá trình cài đặt, hãy chuyển đến phần Package Dependencies (Phần phụ thuộc của gói) trong Project Navigator (Trình điều hướng dự án) để xác minh gói và phiên bản của gói đó.
Để xoá SDK Địa điểm hiện có cho các phần phụ thuộc iOS đã thêm bằng
CocoaPods
, hãy làm theo các bước sau:
- Đóng không gian làm việc Xcode của bạn. Mở cửa sổ dòng lệnh rồi thực thi lệnh sau:
sudo gem install cocoapods-deintegrate cocoapods-clean pod deintegrate pod cache clean --all
-
Hãy xoá
Podfile
,Podfile.resolved
và Xcodeworkspace
nếu bạn không sử dụng chúng cho bất kỳ sản phẩm nào khác ngoài CocoaPods.
-
Trong phần cài đặt cấu hình của dự án Xcode, hãy tìm Khung, Thư viện và Nội dung được nhúng. Sử dụng dấu trừ(-) để xoá khung sau:
GooglePlaces.xcframework
-
Trong thư mục cấp cao nhất của dự án Xcode, hãy xoá gói
GooglePlaces
.
CocoaPods
SDK Địa điểm dành cho iOS được cung cấp dưới dạng nhóm CocoaPod, GooglePlaces, trong đó có tất cả chức năng về địa điểm.
CocoaPods là trình quản lý phần phụ thuộc nguồn mở cho các dự án Swift và Objective-C Cacao. Nếu bạn chưa có công cụ CocoaPods, hãy cài đặt công cụ này trên macOS bằng cách chạy lệnh sau từ cửa sổ dòng lệnh. Để biết thông tin chi tiết, hãy xem Hướng dẫn bắt đầu sử dụng CocoaPods.
sudo gem install cocoapods
Tạo một Podfile
cho SDK Địa điểm dành cho iOS và sử dụng SDK này để cài đặt SDK cũng như các phần phụ thuộc của SDK đó:
- Nếu bạn chưa có dự án Xcode, hãy tạo một dự án ngay bây giờ và lưu dự án đó vào máy cục bộ của bạn. Nếu bạn mới phát triển iOS, hãy tạo một dự án mới và chọn Mẫu ứng dụng iOS.
- Tạo một tệp có tên
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
Podfile
và thêm các phần phụ thuộc cùng với versions của các phần phụ thuộc đó. Sau đây là ví dụ chỉ định tên mục tiêu của ứng dụng và tên của nhómGooglePlaces
:source 'https://github.com/CocoaPods/Specs.git' platform :ios, '15.0' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GooglePlaces', '8.3.0' end
Hãy nhớ thường xuyên chạypod outdated
để phát hiện thời điểm có phiên bản mới hơn nhằm đảm bảo bạn luôn cập nhật thông tin mới nhất. - Lưu
Podfile
. Mở cửa sổ dòng lệnh rồi chuyển đến thư mục chứa
Podfile
:cd <path-to-project>
Chạy lệnh
pod install
. Thao tác này sẽ cài đặt các API được chỉ định trongPodfile
, cùng với mọi phần phụ thuộc có thể có trong các API đó.pod install
Đóng Xcode, sau đó mở (nhấp đúp) vào tệp
.xcworkspace
của dự án để chạy Xcode. Từ thời điểm này trở đi, bạn phải dùng tệp.xcworkspace
để mở dự án.
Để cập nhật API cho dự án hiện có, hãy làm theo các bước sau:
- Mở cửa sổ dòng lệnh rồi chuyển đến thư mục dự án có chứa
Podfile
. - Chạy lệnh
pod update
. Thao tác này sẽ cập nhật tất cả API được chỉ định trongPodfile
lên phiên bản mới nhất.
Cài đặt theo cách thủ công
Hướng dẫn này cho bạn biết cách thêm thủ công XCFramework có chứa SDK Địa điểm dành cho iOS vào dự án của bạn và định cấu hình các chế độ cài đặt bản dựng trong Xcode. XCFramework là một gói nhị phân mà bạn có thể sử dụng trên nhiều nền tảng, bao gồm cả các máy sử dụng Apple silicon.
- Tải các tệp nhị phân và tài nguyên SDK sau đây xuống:
- Giải nén các tệp để truy cập vào XCFramework và tài nguyên.
- Chạy Xcode rồi mở một dự án hiện có hoặc tạo một dự án mới. Nếu bạn mới phát triển iOS, hãy tạo một dự án mới và chọn Mẫu ứng dụng iOS.
- Xoá mọi gói Maps khỏi các bản phát hành trước khỏi dự án của bạn.
-
Mở thẻ Chung. Kéo XCFramework sau vào dự án của bạn trong phần Frameworks, Libraries and Embedded Content (Nội dung được nhúng). Đừng quên chọn Không nhúng:
GooglePlaces.xcframework
Kéo -
Sao chép
GooglePlaces.bundle
từ GooglePlacesResources mà bạn đã tải xuống thư mục cấp cao nhất của dự án Xcode. Hãy nhớ chọn Sao chép các mục vào thư mục của nhóm đích khi được nhắc. - Chọn dự án của bạn trên Project Navigator rồi chọn mục tiêu của ứng dụng.
-
Mở thẻ Tạo giai đoạn. Trong phần Link Binary with Libraries (Liên kết tệp nhị phân với thư viện), hãy thêm các khung và thư viện sau:
CoreGraphics.framework
CoreLocation.framework
libc++.tbd
libz.tbd
QuartzCore.framework
UIKit.framework
-
Chọn dự án của bạn thay vì một mục tiêu cụ thể rồi mở thẻ Build Settings (Cài đặt bản dựng). Trong phần Liên kết – Chung -> Cờ trình liên kết khác, hãy thêm
-ObjC
vào phần "Gỡ lỗi" và "Phát hành". Nếu các chế độ cài đặt này không xuất hiện, hãy thay đổi bộ lọc trong thanh Build Settings (Cài đặt bản dựng) từ Basic (Cơ bản) thành All (Tất cả).
GooglePlaces.bundle
từ GooglePlacesResources mà bạn đã tải xuống
GooglePlacesSwift
Bạn có thể cài đặt SDK Google PlacesSwift (Bản xem trước) bằng Trình quản lý gói Swift, CocoaPods và theo cách thủ công. Các bước cài đặt trong tất cả các quy trình đều phản ánh các bước nêu cho SDK Địa điểm dành cho iOS, với những điểm khác biệt sau đây:
- Cần có Xcode 15.3.
- Đối với Trình quản lý gói Swift, hãy thay thế cả các thực thể
GooglePlaces
bằngGooglePlacesSwift
. Điều này bao gồm cả các câu lệnh nhập. - Cập nhật số phiên bản thành 0.1.0.
- Thay thế các thực thể của https://github.com/googlemaps/ios-places-sdk bằng https://github.com/googlemaps/ios-places-swift-sdk.
- Nếu cài đặt theo cách thủ công, bạn cần thêm tệp XCFramework và tệp tài nguyên
GooglePlacesSwift
ngoài tệp XCFramework và tệp tài nguyên trên Google địa điểm.
Ví dụ: nếu sử dụng CocoaPods, Podfile
được chỉnh sửa sẽ như sau:
source 'https://github.com/CocoaPods/Specs.git' platform :ios, '15.3' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GooglePlacesSwift', '0.1.0' end
Bước 3: Kiểm tra tệp kê khai quyền riêng tư của Apple
Apple yêu cầu cung cấp thông tin chi tiết về quyền riêng tư trong ứng dụng đối với các ứng dụng trên App Store. Truy cập trang Chi tiết về quyền riêng tư trên App Store của Apple để xem nội dung cập nhật và biết thêm thông tin.
Tệp kê khai quyền riêng tư của Apple có trong gói tài nguyên cho SDK. Để xác minh rằng Tệp kê khai quyền riêng tư đã được đưa vào và để kiểm tra nội dung trong đó, hãy tạo một bản lưu trữ cho ứng dụng và tạo một báo cáo về quyền riêng tư từ bản lưu trữ đó.
Bước 4: Thêm khoá API vào ứng dụng
Trong các ví dụ sau, hãy thay thế YOUR_API_KEY
bằng khoá API.
Swift
Thêm khoá API vào AppDelegate.swift
như sau:
- Thêm câu lệnh nhập sau:
import GooglePlaces
- Thêm đoạn mã sau vào phương thức
application(_:didFinishLaunchingWithOptions:)
, thay thế YOUR_API_KEY bằng khoá API của bạn:GMSPlacesClient.provideAPIKey("YOUR_API_KEY")
Objective-C
Thêm khoá API vào AppDelegate.m
như sau:
- Thêm câu lệnh nhập sau:
@import GooglePlaces;
- Thêm đoạn mã sau vào phương thức
application:didFinishLaunchingWithOptions:
, thay thế YOUR_API_KEY bằng khoá API của bạn:[GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];
GooglePlacesSwift
Thêm khoá API vào AppDelegate.swift
như sau:
- Thêm câu lệnh nhập sau:
import GooglePlacesSwift
- Thêm đoạn mã sau vào phương thức
application(_:didFinishLaunchingWithOptions:)
, thay thế YOUR_API_KEY bằng khoá API của bạn:PlacesClient.shared.provideAPIKey("YOUR_API_KEY")
Bước 5: Bắt đầu viết mã
Các mã mẫu sau đây minh hoạ cách lấy địa điểm hiện tại.
Swift
import GooglePlaces import UIKit class GetStartedViewController : UIViewController { // Add a pair of UILabels in Interface Builder, and connect the outlets to these variables. @IBOutlet private var nameLabel: UILabel! @IBOutlet private var addressLabel: UILabel! private var placesClient: GMSPlacesClient! override func viewDidLoad() { super.viewDidLoad() placesClient = GMSPlacesClient.shared() } // Add a UIButton in Interface Builder, and connect the action to this function. @IBAction func getCurrentPlace(_ sender: UIButton) { let placeFields: GMSPlaceField = [.name, .formattedAddress] placesClient.findPlaceLikelihoodsFromCurrentLocation(withPlaceFields: placeFields) { [weak self] (placeLikelihoods, error) in guard let strongSelf = self else { return } guard error == nil else { print("Current place error: \(error?.localizedDescription ?? "")") return } guard let place = placeLikelihoods?.first?.place else { strongSelf.nameLabel.text = "No current place" strongSelf.addressLabel.text = "" return } strongSelf.nameLabel.text = place.name strongSelf.addressLabel.text = place.formattedAddress } } }
Objective-C
#import "GetStartedViewController.h" @import GooglePlaces; @interface GetStartedViewController () // Add a pair of UILabels in Interface Builder and connect the outlets to these variables @property (weak, nonatomic) IBOutlet UILabel *nameLabel; @property (weak, nonatomic) IBOutlet UILabel *addressLabel; @end @implementation GetStartedViewController { GMSPlacesClient *_placesClient; } - (void)viewDidLoad { [super viewDidLoad]; _placesClient = [GMSPlacesClient sharedClient]; } // Add a pair of UILabels in Interface Builder and connect the outlets to these variables. - (IBAction)getCurrentPlace:(UIButton *)sender { GMSPlaceField placeFields = (GMSPlaceFieldName | GMSPlaceFieldFormattedAddress); __weak typeof(self) weakSelf = self; [_placesClient findPlaceLikelihoodsFromCurrentLocationWithPlaceFields:placeFields callback:^(NSArray<GMSPlaceLikelihood *> * _Nullable likelihoods, NSError * _Nullable error) { __typeof__(self) strongSelf = weakSelf; if (strongSelf == nil) { return; } if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } GMSPlace *place = likelihoods.firstObject.place; if (place == nil) { strongSelf.nameLabel.text = @"No current place"; strongSelf.addressLabel.text = @""; return; } strongSelf.nameLabel.text = place.name; strongSelf.addressLabel.text = place.formattedAddress; }]; } @end
GooglePlacesSwift
struct ContentView: View { @State var place: Place? var body: some View { Button("Get Place") { // A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" let fetchPlaceRequest = FetchPlaceRequest( placeID: placeID, placeProperties: [.displayName, .formattedAddress] ) Task { switch await placesClient.fetchPlace(with: fetchPlaceRequest) { case .success(let place): self.place = place case .failure(let placesError): // Handle error } Text(swiftPlace?.displayName ?? "No place yet") .padding() Text(swiftPlace?.formattedAddress ?? "No place yet") .padding() } }
Các bước tiếp theo
Sau khi định cấu hình dự án, bạn có thể khám phá ứng dụng mẫu.