Thiết lập dự án Xcode

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 của mình.

Mỗi bản phát hành đều có Ghi chú phát hành.

Bước 1: Cài đặt phần mềm cần thiết

Để tạo dự án bằng cách sử dụ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, hãy đảm bảo bạn đã xoá mọi SDK Địa điểm hiện có dành cho các phần phụ thuộc iOS.

Để thêm SDK vào dự án mới hoặc dự án hiện có, hãy làm theo các bước sau:

  1. Mở Xcode project hoặc workspace, sau đó chuyển đến File > Add Package Dependencies (Tệp > Thêm phần phụ thuộc gói).
  2. Nhập https://github.com/googlemaps/ios-places-sdk làm URL, nhấn Enter để kéo gói và nhấp vào "Add Package" (Thêm gói).
  3. Để 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 lựa chọn dựa trên phiên bản. Đối với các 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 "Add Package" (Thêm gói).
  4. 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êu main được chỉ định. Sau khi hoàn tất, hãy nhấp vào "Add Package" (Thêm gói).
  5. Để xác minh chế độ cài đặt của bạn, hãy chuyển đến ngăn General của mục tiêu. Trong Khung, Thư viện và 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:

  1. Nếu đang nâng cấp từ phiên bản cũ hơn 9.0.0, bạn phải xoá các phần phụ thuộc sau: GoogleMapsBase, GoogleMapsCoreGoogleMapsM4B sau khi nâng cấp. Đừng xoá phần phụ thuộc của GoogleMaps. Để 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 dự án Xcode, hãy tìm Khung, Thư viện và Nội dung được nhúng. Sử dụng dấu trừ(-) để loại bỏ khung sau:

    • GoogleMapsBase (Chỉ dành cho bản nâng cấp từ các phiên bản cũ hơn 9.0.0)
    • GoogleMapsCore (Chỉ dành cho bản nâng cấp từ các phiên bản cũ hơn 9.0.0)
    • GoogleMapsM4B (Chỉ dành cho bản nâng cấp từ các phiên bản cũ hơn 9.0.0)
  2. Trên 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).
  3. Để xác minh việc cài đặt của bạn, hãy chuyển đến phần Package Dependencies (Phần phụ thuộc 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 được thêm vào bằng CocoaPods, hãy làm theo các bước sau:

  1. Đó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
  2. Xoá Podfile, Podfile.resolved và Xcode workspace nếu bạn không sử dụng chúng cho bất cứ mục đích nào khác ngoài CocoaPods.

Để xoá SDK Địa điểm hiện có dành cho iOS được cài đặt theo cách thủ công, hãy làm theo các bước sau:
  1. Trong phần cài đặt cấu hình dự án Xcode, hãy tìm Khung, Thư viện và Nội dung được nhúng. Dùng dấu trừ(-) để xoá khung sau:
    • GooglePlaces.xcframework
  2. Trên 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ó sẵn dưới dạng nhóm CocoaPod, GooglePlaces, chứa tất cả các tính năng về địa điểm.

CocoaPods là một trình quản lý phần phụ thuộc nguồn mở cho các dự án Swift và Target-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 trên 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 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 đó:

  1. 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 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.
  2. 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.
  3. Chỉnh sửa Podfile và thêm các phần phụ thuộc cùng với versions của chúng. Dưới đây là ví dụ chỉ định tên mục tiêu ứng dụng và tên của nhóm GooglePlaces:
    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ớ chạy pod outdated thường xuyên để phát hiện khi có một phiên bản mới nhất nhằm đảm bảo bạn luôn sử dụng phiên bản mới nhất.
  4. Lưu Podfile.
  5. Mở cửa sổ dòng lệnh rồi chuyển đến thư mục chứa Podfile:

    cd <path-to-project>
  6. Chạy lệnh pod install. Thao tác này sẽ cài đặt các API được chỉ định trong Podfile, cùng với mọi phần phụ thuộc có thể có.

    pod install
  7. Đóng Xcode, sau đó mở (nhấp đúp) vào tệp .xcworkspace của dự án để khởi 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.

Để cập nhật API cho một dự án hiện có, hãy làm theo các bước sau:

  1. Mở cửa sổ dòng lệnh rồi chuyển đến thư mục dự án chứa Podfile.
  2. Chạy lệnh pod update. Thao tác này sẽ cập nhật tất cả API được chỉ định trong Podfile 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 biết cách thêm XCFramework chứa SDK địa điểm dành cho iOS theo cách thủ công vào dự án của bạn và định cấu hình 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.

  1. Tải các tệp tài nguyên và tệp nhị phân của SDK sau đây xuống:
  2. Giải nén các tệp để truy cập vào XCFramework và tài nguyên.
  3. Chạy Xcode và 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.
  4. 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.
  5. Mở thẻ Chung. Kéo XCFramework sau đây vào dự án của bạn trong Frameworks, Libraries, and Embedded Content (Khung, Thư viện và Nội dung được nhúng). Hãy nhớ chọn Không nhúng:
    • GooglePlaces.xcframework
  6. Kéo GooglePlaces.bundle từ GooglePlacesResources mà bạn đã tải xuống
  7. Sao chép GooglePlaces.bundle từ GooglePlacesResources mà bạn đã tải xuống vào 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.
  8. Chọn dự án của bạn trên Project Navigator và chọn mục tiêu cho ứng dụng.
  9. Mở thẻ Tạo giai đoạn. Trong phần 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
  10. Chọn dự án của bạn chứ không phải 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à "Bản 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ả).

GooglePlacesSwift

Bạn có thể cài đặt SDK GooglePlacesSwift (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ả quy trình 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:

Ví dụ: nếu sử dụng CocoaPods, Podfile đã chỉnh sửa sẽ có dạng 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 về quyền riêng tư của Apple

Apple yêu cầu thông tin chi tiết về quyền riêng tư của ứng dụng đối với các ứng dụng trên App Store. Hãy truy cập trang Thông tin chi tiết về quyền riêng tư trong App Store của Apple để biết thông tin cập nhật và biết thêm thông tin.

Tệp kê khai về 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 về quyền riêng tư đã được đưa vào tệp kê khai về quyền riêng tư, cũng như để kiểm tra nội dung trong đó, hãy tạo một bản lưu trữ ứng dụng rồi tạo báo cáo về quyền riêng tư trong kho lưu trữ đó.

Bước 4: Thêm khoá API vào ứng dụng của bạn

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 của bạn như sau:

  • Thêm câu lệnh nhập sau:
    import GooglePlaces
  • Thêm mã sau vào phương thức application(_:didFinishLaunchingWithOptions:), thay thế YOUR_API_KEY bằng khoá API:
    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

Thêm khoá API vào AppDelegate.m của bạn như sau:

  • Thêm câu lệnh nhập sau:
    @import GooglePlaces;
  • Thêm mã sau vào phương thức application:didFinishLaunchingWithOptions:, thay thế YOUR_API_KEY bằng khoá API:
    [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

GooglePlacesSwift

Thêm khoá API vào AppDelegate.swift của bạn như sau:

  • Thêm câu lệnh nhập sau:
    import GooglePlacesSwift
  • Thêm mã sau vào phương thức application(_:didFinishLaunchingWithOptions:), thay thế YOUR_API_KEY bằng khoá API:
    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á các ứng dụng mẫu.