Thiết lập Geospatial API trong ứng dụng của bạn

Các thiết bị XR được hỗ trợ
Hướng dẫn này giúp bạn xây dựng các trải nghiệm cho những loại thiết bị XR sau.
Tìm hiểu về các loại thiết bị XR →
Kính thông minh XR có dây
Kính có màn hình
và âm thanh
Tìm hiểu về các loại thiết bị XR →

Để sử dụng Geospatial API trong ứng dụng, bạn phải thiết lập ứng dụng để truy cập vào ARCore API trên Google Cloud. API này chứa Dịch vụ định vị trực quan cung cấp thông tin định vị chính xác bằng cách sử dụng dữ liệu từ Chế độ xem đường phố của Google.

Hướng dẫn này giúp bạn thiết lập một dự án trên đám mây của Google Cloud đã bật đúng API và phương thức uỷ quyền để truy cập vào API.

Thiết lập một dự án trên Google Cloud hoặc sử dụng một dự án hiện có

Nếu bạn có một dự án Google Cloud hiện có, hãy chọn dự án đó.

Chuyển đến bộ chọn dự án

Nếu bạn chưa có dự án, hãy tạo một dự án.

Tạo dự án mới

Bật ARCore API

Để sử dụng ARCore API, bạn phải bật API này trong dự án của mình.

Bật ARCore API

Thiết lập quy trình uỷ quyền cho Google Cloud

Ứng dụng Android có thể giao tiếp với API ARCore bằng hai phương thức uỷ quyền khác nhau: Uỷ quyền không cần khoá (OAuth 2.0) – đây là phương thức được đề xuất và Uỷ quyền bằng khoá API:

  • Tính năng uỷ quyền không cần khoá sử dụng kết hợp tên gói của ứng dụng và vân tay số của khoá ký để uỷ quyền cho ứng dụng của bạn.

  • Khoá API là một chuỗi xác định một dự án trên đám mây của Google. Khoá API thường không được coi là an toàn vì khách hàng thường có thể truy cập vào khoá này. Hãy cân nhắc sử dụng tính năng uỷ quyền không cần khoá để giao tiếp với API ARCore.

Uỷ quyền không cần khoá

Để uỷ quyền cho ứng dụng của bạn bằng Xác thực không cần khoá, hãy tạo mã ứng dụng khách OAuth 2.0.

  1. Trong Google Cloud, hãy chuyển đến trang Thông tin đăng nhập.

    Chuyển đến phần Thông tin xác thực

  2. Nhấp vào Create credentials (Tạo thông tin xác thực), sau đó chọn OAuth client ID (Mã ứng dụng OAuth) trong trình đơn.

  3. Điền vào các trường bắt buộc như sau:

    • Loại ứng dụng: chọn Android.
    • Tên gói: sử dụng tên gói như đã khai báo trong AndroidManifest.xml.
    • Dấu vân tay chứng chỉ SHA-1: lấy dấu vân tay chứng chỉ SHA-1 theo hướng dẫn tại phần Xác thực ứng dụng.

  4. Nhấn vào Tạo.

Khoá API

Tạo khoá API trong Google Cloud Console bằng cách làm theo các bước sau:

  1. Trong Google Cloud Console, hãy chuyển đến trang Thông tin đăng nhập:

    Chuyển đến phần Thông tin xác thực

  2. Nhấp vào Tạo thông tin xác thực, rồi chọn Khoá API trong trình đơn.

  3. Thêm một quy định hạn chế về API cho ARCore API. Để biết thêm thông tin, hãy xem bài viết Áp dụng các quy tắc hạn chế đối với khoá API.

  4. Nhấp vào Tạo. Hộp thoại API key created (Đã tạo khoá API) sẽ hiển thị chuỗi cho khoá bạn mới tạo.

Trong Android Studio, hãy thêm khoá API mới vào dự án của bạn. Đưa khoá API vào phần tử <meta-data> trong phần tử <application> trong tệp AndroidManifest.xml của ứng dụng:

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

Yêu cầu cấp các quyền cần thiết

Để sử dụng Geospatial API trong ARCore với Jetpack XR, ứng dụng của bạn cần yêu cầu các quyền khi bắt đầu chạy sau đây:

Trên thiết bị di động, Geospatial API cũng yêu cầu các quyền sau:

Truy cập vào một phiên

Truy cập vào thông tin không gian địa lý thông qua một Session của Jetpack XR, mà ứng dụng của bạn phải tạo.

Định cấu hình phiên

Geospatial API không được bật theo mặc định trên các phiên XR. Ứng dụng của bạn phải bật tính năng này một cách rõ ràng bằng cách định cấu hình GeospatialMode trên Session. Có các chế độ sau:

  • GeospatialMode.SPATIAL: Geospatial API đã được bật. Geospatial API sử dụng dữ liệu của Hệ thống định vị trực quan (VPS), Hệ thống định vị toàn cầu (GPS) và cảm biến chuyển động của thiết bị để xác định tư thế không gian địa lý của thiết bị. Chế độ này không dùng được trên thiết bị Kính thông minh.
  • GeospatialMode.INERTIAL: Geospatial API được bật ở chế độ tiết kiệm pin. API Không gian địa lý chỉ sử dụng GPS và cảm biến chuyển động của thiết bị để xác định tư thế không gian địa lý của thiết bị. Chế độ này chỉ có trên các thiết bị Kính thông minh.
  • GeospatialMode.DISABLED: Geospatial API bị tắt; khi chuyển từ một chế độ khác sang chế độ này, Geospatial API sẽ giải phóng tất cả tài nguyên đã thu nạp và ngừng theo dõi.

Không phải thiết bị nào cũng hỗ trợ tất cả các chế độ Không gian địa lý. Hãy xem GeospatialMode để biết thêm thông tin. Sử dụng XrDevice.isGeospatialSupported để xem liệu một GeospatialMode nhất định có được hỗ trợ hay không.

Mã mẫu sau đây minh hoạ cách đặt GeospatialMode bằng Session.configure.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}

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

Những ứng dụng sử dụng Geospatial API với ARCore cho Jetpack XR phải hiển thị cho người dùng một 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ọ. Hãy xem các yêu cầu về quyền riêng tư của người dùng để biết thêm thông tin.

Sử dụng đối tượng Geospatial

Sau khi định cấu hình phiên, hãy lấy đối tượng Geospatial bằng Geospatial.getInstance. Chỉ sử dụng đối tượng Geospatial khi trạng thái của đối tượng là GeospatialTrackingState.RUNNING.

Các mã mẫu sau đây minh hoạ cách theo dõi trạng thái Địa không gian bằng cách sử dụng Geospatial.state.

Compose XR

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}

SceneCore

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}

Tìm hiểu về các giá trị độ chính xác

Khi được bật, Geospatial API sẽ cung cấp 3 giá trị độ chính xác: độ chính xác theo chiều ngang, chiều dọc và hướng. Các giá trị độ chính xác này được cập nhật theo thời gian và có thể chính xác hơn khi thu thập được nhiều dữ liệu hơn. Giá trị càng lớn thì độ chính xác càng thấp và được xác định là bán kính của mức độ tin cậy 68%. Nói cách khác, có 68% xác suất giá trị thực nằm trong bán kính đã cho của giá trị ước tính.

Sử dụng Geospatial.State.horizontalAccuracy, verticalAccuracy và orientationYawAccuracy để nhận các giá trị độ chính xác hiện tại.

Ứng dụng của bạn có thể cần một mức độ chính xác cụ thể để hoạt động đúng cách. Ví dụ: ứng dụng của bạn có thể muốn đợi cho đến khi độ chính xác theo chiều ngang nhỏ hơn 5 mét trước khi hiển thị nội dung ảo. Để tăng khả năng thu thập dữ liệu có độ chính xác cao hơn, ứng dụng của bạn nên hướng dẫn người dùng quan sát xung quanh, tốt nhất là nhìn vào các toà nhà hoặc các đặc điểm khác có độ chi tiết cao về hình ảnh có trong Chế độ xem đường phố của Google. Sử dụng Geospatial.checkVpsAvailability để xác định xem VPS có hoạt động tại vị trí đã cho hay không.

Các bước tiếp theo

Khi API không gian địa lý được thiết lập chính xác trong ứng dụng, ứng dụng của bạn có thể làm những việc sau: