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 đã sẵn sàng 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 từng bản phát hành.

Bước 1: Cài đặt phần mềm bắt buộc

Để tạo một dự án bằng Places SDK for iOS, bạn cần:

  • Xcode phiên bản 16.0 trở lên

Bước 2: Tạo dự án Xcode và cài đặt Places SDK cho iOS

Trình quản lý gói Swift

Bạn có thể cài đặt Places SDK 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 phần phụ thuộc hiện có của Places SDK cho iOS.

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

  1. Mở project hoặc workspace Xcode, sau đó chuyển đến File > Add Package Dependencies (Tệp > Thêm phần phụ thuộc của gói).
  2. 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 "Add Package" (Thêm gói).
  3. Để cài đặt một version cụ thể, hãy đặt trường Quy tắc về 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 lựa 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".
  4. Trong cửa sổ Chọn sản phẩm trong gói, hãy xác minh rằng GooglePlaces, GooglePlacesSwift hoặc cả hai sẽ được thêm vào mục tiêu chính được chỉ định. Sau khi hoàn tất, hãy nhấp vào Thêm gói.

    Nếu bạn đang cập nhật Google Places Swift từ URL GitHub không dùng nữa

    Quan trọng: URL GitHub để truy cập vào Google Places Swift đã thay đổi kể từ phiên bản 0.3.0. Nếu bạn đang cập nhật một phiên bản GooglePlacesSwift được truy cập thông qua URL cũ, https://github.com/googlemaps/ios-places-swift-sdk, hãy xoá phiên bản đó khỏi phần phụ thuộc gói của Xcode.

  5. Để xác minh quá trình cài đặt, hãy chuyển đến ngăn Chung của mục tiêu. Trong phần Frameworks, Libraries, and Embedded Content (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. Trong Xcode, hãy chuyển đến "File > Packages > Update To Latest Package Versions" (Tệp > Gói > Cập nhật lên phiên bản gói mới nhất).

    Nếu bạn đang cập nhật Google Places Swift từ URL GitHub không dùng nữa

    Quan trọng: URL GitHub để truy cập vào Google Places Swift đã thay đổi kể từ phiên bản 0.3.0. Nếu bạn đang cập nhật một phiên bản GooglePlacesSwift được truy cập thông qua URL cũ, https://github.com/googlemaps/ios-places-swift-sdk, hãy xoá phiên bản đó khỏi phần phụ thuộc gói của Xcode.

  2. Để xác minh quá trình cài đặt, hãy chuyển đến phần Package Dependencies (Phụ thuộc gói) của 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á Places SDK for iOS hiện có đượ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 Frameworks, Libraries, and Embedded Content (Khung, Thư viện và Nội dung được nhúng). Sử dụng dấu trừ(-) để xoá các khung sau:
    • GooglePlaces.xcframework
    • GooglePlacesSwift.xcframework
  2. Xoá gói GooglePlaces khỏi thư mục cấp cao nhất của dự án Xcode.

Cài đặt theo cách thủ công

Hướng dẫn này trình bày cách thêm XCFrameworks chứa Places SDK for iOS và Places Swift SDK for iOS vào dự án của bạn theo cách thủ công, đồng thời đị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, kể cả những máy dùng Apple silicon. Bạn có thể chọn thêm Places SDK cho iOS, Places Swift SDK cho iOS hoặc cả hai.

  1. Tải các tệp nhị phân và tệp tài nguyên SDK sau đây xuống:
  2. Nếu bạn đang cài đặt Places Swift SDK cho iOS, hãy cài đặt các tệp sau:
  3. Giải nén các tệp để truy cập vào XCFramework và tài nguyên.
  4. Khởi 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 bắt đầu phát triển cho iOS, hãy tạo một dự án mới và chọn mẫu Ứng dụng iOS.
  5. Xoá mọi gói Maps khỏi các bản phát hành trước trong dự án của bạn.
  6. Mở thẻ Chung. Kéo XCFramework sau đây vào dự án của bạn trong phần Frameworks, Libraries, and Embedded Content (Khung, thư viện và nội dung được nhúng). Nhớ chọn Không nhúng:
    • GooglePlaces.xcframework
    Nếu bạn đang cài đặt Places Swift SDK, hãy kéo XCFramework sau vào dự án của bạn trong phần Frameworks, Libraries, and Embedded Content (Khung, Thư viện và Nội dung được nhúng). Nhớ chọn Không nhúng:
    • GooglePlacesSwift.xcframework
  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. Nhớ chọn Copy items into destination group's folder (Sao chép các mục vào thư mục của nhóm đích) khi được nhắc.

    Nếu bạn đang cài đặt Places Swift SDK, hãy sao chép GooglePlacesSwift.bundle từ GooglePlacesSwiftResources mà bạn đã tải xuống vào thư mục cấp cao nhất của dự án Xcode. 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 trong Project Navigator (Trình điều hướng dự án) rồi chọn đích đến của ứng dụng.
  9. Mở thẻ Build Phases (Giai đoạn xây dựng). Trong 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

  10. Chọn dự án của bạn thay vì một mục tiêu cụ thể và mở thẻ Build Settings (Cài đặt bản dựng). Trong phần Linking – General -> Other Linker Flags (Liên kết – Chung –> Cờ trình liên kết khác), hãy thêm -ObjC vào "Debug" (Gỡ lỗi) và "Release" (Phát hành). Nếu bạn không thấy các chế độ cài đặt này, 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ả).

CocoaPods

Places SDK for iOS và Places Swift SDK for iOS có sẵn dưới dạng các nhóm CocoaPod, GooglePlaces và GooglePlacesSwift.

CocoaPods là một trình quản lý phần phụ thuộc nguồn mở cho các dự án Cocoa Swift và Objective-C. Nếu 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ừ thiết bị đầu cuối. Để 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 để cài đặt các SDK và phần phụ thuộc của chúng:

  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ộ. Nếu bạn mới bắt đầu phát triển cho 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 là Podfile trong thư mục dự án của bạ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 phiên bản của chúng. Sau đây là ví dụ chỉ định tên mục tiêu của ứng dụng và tên của các nhóm GooglePlaces và GooglePlacesSwift: 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '16.0'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GooglePlaces', '10.1.0'
  pod 'GooglePlacesSwift', '10.1.0'
end
     Đảm bảo bạn thường xuyên chạy pod outdated để phát hiện khi có phiên bản mới hơn nhằm đảm bảo bạn luôn 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 mà các API đó có thể có.

    pod install

  7. Đóng Xcode, rồi 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.

Để 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ở một 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ả các API được chỉ định trong Podfile lên phiên bản mới nhất.

Bước 3: 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 của bạn.

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 nội dung sau vào phương thức application(_:didFinishLaunchingWithOptions:) của bạn, thay thế YOUR_API_KEY bằng khoá API của bạn: 
    PlacesClient.provideAPIKey("YOUR_API_KEY")

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

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

Bước 4 (không bắt buộc): Kiểm tra tệp Tuyên bố về 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 cho các ứng dụng trên App Store. Hãy truy cập vào trang Thông tin chi tiết về quyền riêng tư trên Apple App Store để biết thông tin cập nhật và thông tin khác.

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

Các bước tiếp theo