Thiết lập dự án Xcode

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

Bạn có thể cài đặt Navigation SDK 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 Navigation SDK.

Để 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-navigation-sdk làm URL, nhấn Enter để kéo gói vào 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 Dependency Rule 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 "Exact Version" (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).

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

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 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 XCFramework chứa Navigation SDK cho iOS và SDK bản đồ dành cho iOS vào dự án theo cách thủ công, đồng thời định cấu hình chế đặ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 bộ vi mạch M1

Hãy làm theo các bước sau để cài đặt XCFramework cho Navigation SDK cho iOS, và SDK bản đồ dành cho iOS:

1. Tải xuống các tệp nhị phân và tệp tài nguyên SDK sau:
   • GoogleMaps
   • GoogleMapsResources
   • GoogleNavigation
   • GoogleNavigationResources
2. Khởi 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 và chọn iOS App template (Mẫu ứng dụng iOS).
3. Xoá tất cả các tham chiếu hiện có đến 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 Maps và Navigation (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.
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 Copy items into destination group's folder (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 bản dựng) rồi 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:
   • 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 (Tính năng), bật Background Modes (Chế độ nền) và bật các chế độ sau:
   • Audio, AirPlay, and Picture in Picture (Âm thanh, AirPlay và Hình trong hình)
   • Location updates (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. Trong phần Other Linker Flags, hãy thêm ‑ObjC cho cả debug và release. 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 rồi thêm các cặp khoá-giá trị sau:
    • Khoá: NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description (Quyền riêng tư – Mô tả về việc sử dụng vị trí khi đang sử dụng))
      Giá trị: "This app needs permission to use your location for turn-by-turn navigation." (Ứng dụng này cần có quyền sử dụng vị trí của bạn để dò đường đi từng chặng).
    • Khoá: NSLocationAlwaysAndWhenInUseUsageDescription (Privacy - Location Always and When In Use Usage Description (Quyền riêng tư – Mô tả về việc sử dụng vị trí luôn và khi đang sử dụng))
      Giá trị: "Ứng dụng này cần có quyền sử dụng vị trí của bạn để dò đường đi từng chặng."

CocoaPods

Navigation SDK cho iOS có sẵn dưới dạng một CocoaPods pod. CocoaPods là một trình quản lý phần phụ thuộc mã 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ừ 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 Navigation SDK cho iOS và sử dụng tệp 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 bây giờ và lưu vào máy cục bộ. Nếu bạn mới phát triển cho iOS:
   1. Tạo một dự án mới.
   2. Chọn mẫu iOS > App (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 bên dưới.
      3. Đặt Interface (Giao diện) của dự án thành Storyboard (Bảng phân cảnh).
      4. Đặt Language (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 chúng. Sau đây là một ví dụ bao gồm phần phụ thuộc mà bạn cần cho Navigation SDK cho iOS: # Cocoapods install reference #

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '16.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleNavigation', '10.10.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, 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. Lệnh 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 để khởi chạy Xcode. Kể từ thời điểm này, 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. Lệnh 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.

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"];