Thiết lập dự án Xcode

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

Bạn có thể cài đặt SDK Bản đồ 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 SDK Bản đồ hiện có cho iOS.

Để 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-maps-sdk làm URL, nhấn 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. Nếu đang nâng cấp từ phiên bản thấp hơn 9.0.0, bạn phải xoá các phần phụ thuộc sau: GoogleMapsBase, GoogleMapsCore và GoogleMapsM4B sau khi nâng cấp. Không xoá phần phụ thuộc cho 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 nhúng. Sử dụng dấu trừ(-) để xoá khung sau:

   • GoogleMapsBase (Chỉ dành cho các bản nâng cấp từ phiên bản cũ hơn 9.0.0)
   • GoogleMapsCore (Chỉ dành cho các bản nâng cấp từ phiên bản cũ hơn 9.0.0)
   • GoogleMapsM4B (Chỉ dành cho các bản nâng cấp từ phiên bản cũ hơn 9.0.0)
2. 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).
3. Để 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á các phần phụ thuộc hiện có của SDK Bản đồ dành cho iOS được thêm bằng CocoaPods, hãy làm theo các bước sau:

1. Đóng không gian làm việc Xcode. Mở dòng lệnh và 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 các tệp này cho bất kỳ mục đích nào khác ngoài CocoaPods.

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
   • GoogleMapsBase (Chỉ dành cho các bản cài đặt trước phiên bản 9.2.0)
   • GoogleMapsCore (Chỉ dành cho các bản cài đặt trước phiên bản 9.2.0)
   • GoogleMapsM4B (Chỉ dành cho các bản cài đặt trước phiên bản 9.0.0)
2. Trong thư mục cấp cao nhất của dự án Xcode, hãy xoá gói GoogleMaps.

Cài đặt thủ công

Hướng dẫn này cho biết cách thêm XCFrameworks chứa SDK Maps cho iOS vào dự án theo cách thủ công 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 silicon của Apple.

1. Tải các tệp nhị phân và tài nguyên SDK sau đây xuống:
   • GoogleMaps
   • GoogleMapsM4B
   • GoogleMapsResources
2. Giải nén các tệp để truy cập vào XCFrameworks và tài nguyên.
3. 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 bắt đầu 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.
4. Mở thẻ Chung. Kéo XCFramework sau vào dự án của bạn trong phần Khung, Thư viện và Nội dung nhúng. Hãy nhớ chọn Do Not Embed (Không nhúng):
   • GoogleMaps.xcframework
5. Sao chép 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. 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.
6. 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.
7. Mở thẻ Build Phases (Giai đoạn xây dựng) cho mục tiêu của ứng dụng. 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
   • Contacts.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • OpenGLES.framework (Chỉ khi bạn đang sử dụng OpenGL)
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. 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 mục 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ả).

9. Để cài đặt SDK Địa điểm cho iOS XCFramework, hãy xem phần Bắt đầu sử dụng SDK Địa điểm cho iOS.

CocoaPods

SDK Bản đồ dành cho iOS có sẵn dưới dạng một nhóm 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 SDK Maps 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 bắt đầu 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ụ bao gồm phần phụ thuộc bạn cần cho SDK Bản đồ dành cho iOS:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '15.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '9.2.0'
   end

   Hãy nhớ thường xuyên chạy pod outdated để phát hiện thời điểm 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. 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 mà các API đó có thể 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.

Swift

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

1. Thêm câu lệnh nhập sau:

   import GoogleMaps

2. Thêm nội dung sau vào phương thức application(_:didFinishLaunchingWithOptions:) bằng khoá API:

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. Nếu bạn cũng đang sử dụng API Địa điểm, hãy thêm lại khoá của bạn như minh hoạ bên dưới:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

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

1. Thêm câu lệnh nhập sau:

   @import GoogleMaps;

2. Thêm nội dung sau vào phương thức application:didFinishLaunchingWithOptions: bằng khoá API:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. Nếu bạn cũng đang sử dụng API Địa điểm, hãy thêm lại khoá của bạn như minh hoạ bên dưới:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];