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ó 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 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 15.0 trở lên

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

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 SDK Điều hướng hiện có.

Để 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 (Tệp) > Add Package Dependencies (Thêm phần phụ thuộc gói).
  2. Nhập https://github.com/googlemaps/ios-navigation-sdk làm URL, nhấn phím Enter để lấy gói và nhấp vào "Thêm gói".
  3. Để cài đặt một version cụ thể, hãy đặt trường Dependency Rule (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 "Phiên bản chính xác". Sau khi hoàn tất, hãy nhấp vào "Thêm 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. Để xác minh quá trình cài đặt, hãy chuyển đến phần Package Dependencies (Phần 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á 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 Khung, Thư viện và Nội dung 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 cho biết cách thêm XCFrameworks chứa Navigation SDK cho iOS và SDK Bản đồ cho iOS vào dự á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, bao gồm cả các máy sử dụng chipset M1

Hãy làm theo các bước sau để cài đặt XCFrameworks cho Navigation SDK dành cho iOS và SDK Maps dành cho iOS:

  1. Tải các tệp nhị phân và tài nguyên SDK sau đây xuống:
  2. 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 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ó đến Maps, Navigation và Places khỏi dự án.
  4. Kéo các XCFrameworks sau vào dự án của bạn trong phần Khung, Thư viện và Nội dung nhúng để cài đặt cả SDK Maps và SDK Điều hướng (khi được nhắc, hãy chọn 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 nhớ chọn 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 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:
    • Accelerate.framework
    • AudioToolbox.framework
    • AVFoundation.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
    • 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 tin cập nhật về vị trí
  10. Chọn dự á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 Other Linker Flags (Cờ trình liên kết khác), hãy thêm ‑ObjC cho cả chế độ gỡ lỗi và 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 (Quyền riêng tư – Mô tả việc sử dụng vị trí khi đang sử dụng)
      Giá trị: "Ứng dụng này cần quyền sử dụng thông tin vị trí của bạn để chỉ đường từng chặng."
    • Khoá: NSLocationAlwaysAndWhenInUseUsageDescription (Quyền riêng tư – Mô tả việc sử dụng thông tin vị trí mọi lúc và khi đang sử dụng)
      Giá trị: "Ứng dụng này cần quyền sử dụng thông tin vị trí của bạn để chỉ đường từng chặng."

CocoaPods

Navigation SDK cho iOS có sẵn dưới dạng một pod CocoaPods. 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 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ừ 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 Navigation SDK dành cho iOS và sử dụng SDK này để cài đặt API và các phần phụ thuộc của API:

  1. 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:
    1. Tạo dự án mới.
    2. Chọn mẫu iOS > Ứng dụng.
    3. Trên màn hình tuỳ chọn dự án:
      1. Nhập Project Name (Tên dự án).
      2. Ghi lại giá trị của trường Bundle identifier (Mã nhận dạng gói). Bạn có thể sử dụng giá trị đó để hạn chế khoá API của mình ở bên dưới.
      3. Đặt Giao diện của dự án thành Bảng phân cảnh.
      4. Đặt Ngôn ngữ thành Swift hoặc Objective-C.
  2. 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.
  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 các phần phụ thuộc đó. Dưới đây là ví dụ về phần phụ thuộc bạn cần cho Navigation SDK cho iOS: # Cocoapods install reference # 
    source 'https://github.com/CocoaPods/Specs.git'

platform :ios, '15.0'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GoogleNavigation', '10.0.0'
end
    Hãy nhớ thường xuyên chạy pod outdated để phát hiện các phiên bản mới hơn. Nếu cần, hãy nâng cấp lên 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.

    pod install

  7. Đó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.

Để 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 thiết bị đầu cuối và 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 dự án

Các ví dụ sau đây cho biết 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 nội dung 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 nội dung 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 Tuyên bố 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ư trong ứng dụng đối với 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 App Store của Apple để 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 của 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 đó, hãy tạo bản lưu trữ ứng dụng và tạo báo cáo quyền riêng tư từ bản lưu trữ.

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

Nếu bạn là khách hàng của Dịch vụ di động, hãy tìm hiểu về việc thanh toán trong tài liệu về Dịch vụ di động. Để 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 phần Liên kết việc sử dụng dịch vụ của bạn với các giao dịch Di chuyển.

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: