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.

Ghi chú phát hành được cung cấp cho từng 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 Navigation SDK cho iOS, bạn phải tải xuống và cài đặt:

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

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

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

Bạn có thể cài đặt SDK điều hướng 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 SDK Điều hướng.

Để 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:

  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-navigation-sdk làm URL, nhấn phím Enter để lấy gói, rồi 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 tuỳ 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 "Exact Version" (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ổ Choose Package Products (Chọn sản phẩm trong gói), hãy xác minh rằng GoogleNavigation sẽ được thêm vào mục tiêu main mà bạn chỉ định. Sau khi hoàn tất, hãy nhấp vào "Thêm gói".
  5. Để xác minh quá trình cài đặt, hãy chuyển đến ngăn General (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).
  2. Để 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) 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á Navigation SDK cho 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á khung sau:
    • GoogleMaps.xcframework
    • GoogleNavigation.xcframework
  2. Trong thư mục cấp cao nhất của dự án Xcode, hãy xoá gói GoogleMaps.

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 Navigation SDK cho iOS và SDK bản đồ dành cho iOS vào dự án theo cách thủ công, cũng như đị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ả những máy dùng chipset M1

Hãy làm theo các bước sau để cài đặt XCFrameworks cho SDK Điều hướng dành cho iOS và SDK Bản đồ dành cho iOS:

  1. Tải các tệp nhị phân và tệp tài nguyên SDK sau đây xuống:
  2. 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 sử dụng iOS, hãy tạo một dự án mới rồi chọn mẫu Ứng dụng iOS.
  3. Xoá tất cả các tệp tham chiếu hiện có về Maps, Navigation và Places khỏi dự án.
  4. Kéo các 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 nhúng) để cài đặt cả SDK Bản đồ và SDK Điều hướng (khi được nhắc, hãy chọn Copy items if needed (Sao chép các mục nếu cần)):
    • GoogleMaps.xcframework
    • GoogleNavigation.xcframework
  5. Kéo GoogleMaps.bundle từ GoogleMapsResources mà bạn đã tải xuống vào thư mục cấp cao nhất của dự án Xcode. Khi được nhắc, hãy đảm bảo bạn đã chọn Copy items if needed (Sao chép các mục nếu cần).
  6. Kéo GoogleNavigation.bundle từ GoogleNavigationResources mà bạn đã tải xuống vào thư mục cấp cao nhất của dự án Xcode. Khi được nhắc, hãy đảm bảo bạn đã chọn Sao chép các mục vào thư mục của nhóm đích.
  7. Chọn dự án của bạn trong Project Navigator (Trình điều hướng dự án) rồi chọn mục tiêu của ứng dụng.
  8. Mở thẻ Build Phases (Giai đoạn tạo) và trong mục 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:
    • Accelerate.framework
    • AudioToolbox.framework
    • AVFoundation.framework
    • CarPlay.framework
    • Contacts.framework
    • CoreData.framework
    • CoreGraphics.framework
    • CoreImage.framework
    • CoreLocation.framework
    • CoreTelephony.framework
    • CoreText.framework
    • GLKit.framework
    • ImageIO.framework
    • libc++.tbd
    • libxml2.tbd
    • libz.tbd
    • MapKit.framework
    • Metal.framework
    • OpenGLES.framework
    • QuartzCore.framework
    • Security.framework
    • SystemConfiguration.framework
    • UIKit.framework
    • UserNotifications.framework
    • WebKit.framework
  9. Trong mục tiêu của ứng dụng, hãy chọn thẻ Capabilities (Chức năng), bật Background Modes (Chế độ nền) và bật các chế độ sau:
    • Âm thanh, AirPlay và Hình trong hình
    • Thông báo cập nhật vị trí
  10. 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 Other Linker Flags (Cờ trình liên kết khác), hãy thêm ‑ObjC cho cả 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ả).
  11. Mở Info.plist và thêm các cặp khoá-giá trị sau:
    • Khoá: NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)
      Giá trị: "Ứng dụng này cần có quyền sử dụng thông tin vị trí của bạn để cung cấp tính năng đường đi từng chặng."
    • Khoá: NSLocationAlwaysAndWhenInUseUsageDescription (Privacy - Location Always and When In Use Usage Description)
      Giá trị: "Ứng dụng này cần có quyền sử dụng thông tin vị trí của bạn để cung cấp tính năng đường đi từng chặng."

Bước 3: Thêm khoá API vào dự án

Các ví dụ sau đây cho thấy cách thêm khoá API vào dự án trong Xcode:

Swift

Thêm khoá API vào AppDelegate.swift như sau:

  1. Thêm các câu lệnh nhập sau: 
    import GoogleMaps
import GoogleNavigation
  2. Thêm đoạn mã sau vào phương thức application(_:didFinishLaunchingWithOptions:): 
    GMSServices.provideAPIKey("YOUR_API_KEY")

Objective-C

Thêm khoá API vào AppDelegate.m như sau:

  1. Thêm các câu lệnh nhập sau: 
    @import GoogleMaps;
@import GoogleNavigation;
  2. Thêm đoạn mã sau vào phương thức application:didFinishLaunchingWithOptions:: 
    [GMSServices provideAPIKey:@"YOUR_API_KEY"];

Bước 4 (không bắt buộc): 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 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 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 và để kiểm tra nội dung của tệp này, hãy tạo một kho lưu trữ cho ứng dụng của bạn và tạo báo cáo về quyền riêng tư từ kho lưu trữ đó.

Nếu bạn là khách hàng của Dịch vụ di chuyển

Nếu bạn là khách hàng của Dịch vụ di chuyển, hãy tìm hiểu về thông tin thanh toán trong tài liệu về Dịch vụ di chuyển. Để biết thêm thông tin về cách ghi lại giao dịch, hãy xem phần Thiết lập thông tin thanh toán. Để tìm hiểu cách thêm mã giao dịch vào quá trình triển khai SDK điều hướng, hãy xem bài viết Liên kết mức sử dụng dịch vụ với các giao dịch di động.

Bước tiếp theo

Giờ đây, khi đã có khoá API và dự án Xcode, bạn có thể tạo và chạy ứng dụng. Navigation SDK cho iOS cung cấp các hướng dẫn có thể giúp bạn bắt đầu. Để biết thêm thông tin, hãy xem: