Bật API Không gian địa lý cho ứng dụng Android NDK (C)

Định cấu hình chế độ cài đặt của ứng dụng để có thể dùng API Không gian địa lý.

Điều kiện tiên quyết

Hãy đảm bảo bạn hiểu rõ các khái niệm cơ bản về AR và cách định cấu hình một phiên ARCore trước khi tiếp tục.

Nếu bạn muốn chạy một ứng dụng mẫu minh hoạ chức năng được mô tả ở đây, hãy xem bài viết Bắt đầu nhanh về không gian địa lý ARCore cho Android dành cho Java. Ứng dụng mẫu trong Quickstart được viết bằng Java. Các mã mẫu trong tài liệu này dành cho cùng một chức năng được viết bằng C.

Hãy xem phần Giới thiệu về API Không gian địa lý để biết thêm thông tin về API Không gian địa lý.

Nếu bạn mới phát triển bằng ARCore, hãy xem bài viết Bắt đầu để biết thông tin về các yêu cầu về phần mềm và phần cứng, các điều kiện tiên quyết cũng như các thông tin khác dành riêng cho những nền tảng bạn đang sử dụng.

Hãy đảm bảo rằng môi trường phát triển của bạn đáp ứng các yêu cầu của SDK ARCore, như mô tả trong phần Bắt đầu nhanh dành cho Java.

Bật API ARCore

Trước khi sử dụng Hệ thống định vị trực quan (VPS) trong ứng dụng, trước tiên, bạn phải bật API ARCore trong một dự án Google Cloud mới hoặc hiện có. Dịch vụ này chịu trách nhiệm lưu trữ, lưu trữ và phân giải neo không gian địa lý.

Ưu tiên phương thức uỷ quyền không cần khoá, nhưng hệ thống cũng hỗ trợ phương thức uỷ quyền Khoá API.

Thêm các thư viện bắt buộc vào ứng dụng

Sau khi cho phép ứng dụng gọi API ARCore, bạn phải thêm các thư viện để bật các tính năng Không gian địa lý trong ứng dụng của mình.

Trong tệp build.gradle của ứng dụng, hãy thiết lập Dịch vụ Google Play để bao gồm thư viện Vị trí Dịch vụ Play.

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

Bật tính năng Không gian địa lý trong cấu hình phiên

Trước khi tạo phiên, hãy thay đổi GeospatialMode trong cấu hình phiên thành ENABLED:

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

Khi chế độ Không gian địa lý được đặt thành ENABLED, ứng dụng vẫn được phép nhận thông tin địa lý từ Hệ thống định vị trực quan (VPS).

Nhắc người dùng cho phép sử dụng dữ liệu thiết bị

Các ứng dụng sử dụng API Không gian địa lý ARCore phải hiển thị cho người dùng lời nhắc xác nhận và cho phép sử dụng dữ liệu từ thiết bị của họ. Vui lòng xem bài viết Yêu cầu về quyền riêng tư của người dùng để biết thêm thông tin.

Kiểm tra khả năng tương thích của thiết bị

Không phải thiết bị nào hỗ trợ ARCore cũng hỗ trợ API Không gian địa lý, như mô tả trong phần quickstart dành cho Java.

Để kiểm tra khả năng tương thích trên thiết bị của người dùng, hãy gọi ArSession_isGeospatialModeSupported(). Nếu giá trị này trả về false, đừng cố gắng định cấu hình phiên (dưới đây), vì làm như vậy sẽ khiến ArStatus báo cáo AR_ERROR_UNSUPPORTED_CONFIGURATION.

Yêu cầu người dùng cấp quyền truy cập thông tin vị trí trong thời gian chạy

Ứng dụng của bạn phải yêu cầu quyền truy cập thông tin vị trí trong thời gian chạy.

Để sử dụng API Không gian địa lý ARCore, ứng dụng của bạn cần đăng ký các quyền bổ sung sau đây:

  • ACCESS_FINE_LOCATION để xác định chính xác vị trí của người dùng.

  • ACCESS_COARSE_LOCATION để xác định không chính xác vị trí của người dùng và để tuân thủ các yêu cầu về quyền riêng tư của người dùng. Tuy nhiên, không thể định cấu hình API Không gian địa lý để hoạt động với vị trí tương đối và các yêu cầu API sẽ không thành công khi người dùng đặt quyền này. Hãy xem mục bên dưới để biết thêm thông tin.

  • ACCESS_INTERNET để liên hệ với dịch vụ API Không gian địa lý ARCore.

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

Trên các thiết bị chạy Android phiên bản 12 trở lên, người dùng có thể yêu cầu ứng dụng của bạn chỉ được truy cập vào thông tin vị trí ước chừng. Để đáp ứng yêu cầu này, ứng dụng của bạn phải được định cấu hình quyền ACCESS_COARSE_LOCATION, cùng với ACCESS_FINE_LOCATION, như trình bày ở trên. Bạn phải định cấu hình cả hai quyền truy cập thông tin vị trí.

Tuy nhiên, khi người dùng chỉ định vị trí tương đối, làm như vậy sẽ ngăn API Không gian địa lý lấy được vị trí chính xác mà API này yêu cầu. Dịch vụ không gian địa lý sẽ không cho phép tự định cấu hình nếu ứng dụng của bạn chỉ cung cấp thông tin vị trí tương đối. Ứng dụng của bạn không được dùng API Không gian địa lý với thông tin vị trí tương đối.

Kiểm tra tính sẵn có về không gian địa lý tại vị trí hiện tại của thiết bị

Vì API Không gian địa lý sử dụng kết hợp VPS và GPS để xác định Vị trí không gian địa lý, nên bạn có thể sử dụng API này miễn là thiết bị có thể xác định được vị trí của mình. Trong các khu vực có độ chính xác thấp của GPS, chẳng hạn như không gian trong nhà và môi trường đô thị đông đúc, API sẽ dựa vào phạm vi VPS để tạo ra các tư thế có độ chính xác cao. Trong điều kiện thông thường, VPS có thể cung cấp độ chính xác vị trí khoảng 5 mét và độ chính xác quay là 5 độ. Sử dụng ArSession_checkVpsAvailabilityAsync() để xác định xem một vị trí nhất định có phủ sóng VPS hay không.

API Không gian địa lý cũng có thể được dùng trong những khu vực không có VPS. Trong môi trường ngoài trời có ít hoặc không có vật cản trên cao, GPS có thể đủ để tạo tư thế với độ chính xác cao.

Các bước tiếp theo