Triển khai ý định của ứng dụng chỉ đường

Gemini sử dụng 3 định dạng ý định mà ứng dụng điều hướng của bạn có thể hỗ trợ. Bạn có thể đạt được khả năng tương tác và tích hợp ứng dụng với Gemini bằng cách khai báo các bộ lọc ý định được trình bày chi tiết trên trang này trong tệp kê khai của ứng dụng. Để tìm hiểu thêm về ý định, hãy xem Intent.

Lớp ứng dụng điều hướng Gemini Intent hỗ trợ các ý định sau:

• Ý định điều hướng
• Mục đích tìm kiếm
• Ý định hành động tuỳ chỉnh

Lưu ý: Bạn không bắt buộc phải hỗ trợ cả 3 ý định để có khả năng tương tác, nhưng bạn nên hỗ trợ tất cả các ý định để mang lại trải nghiệm hoàn chỉnh cho người dùng.

Hình 1. Luồng dữ liệu về ý định.

Các tham số trong dữ liệu ý định

Dữ liệu ý định tuân theo định dạng URI chứa các tham số dựa trên ý định mà bạn đang truyền. Một số thông số luôn được cung cấp trong dữ liệu. Điều này có nghĩa là bạn có thể mong đợi chúng luôn có một giá trị rõ ràng. Tuy nhiên, các thông số không bắt buộc không phải lúc nào cũng có giá trị được đặt trong dữ liệu. Để biết thêm thông tin, hãy xem phần Kiểm thử dữ liệu.

Ý định ngoại tuyến

Tất cả ý định được liệt kê trên trang này đều có các biến thể ngoại tuyến. Bạn có thể phân biệt các ứng dụng này bằng cách thêm .offline vào lược đồ của chúng. Ví dụ: ý định điều hướng sử dụng lược đồ geo.offline. Các bộ lọc ý định này trong tệp kê khai cho biết khả năng hỗ trợ các thao tác này khi không có mạng của ứng dụng.

Ý định điều hướng

Sử dụng ý định điều hướng để thực hiện yêu cầu của người dùng về việc điều hướng đến một đích đến cụ thể. Vị trí này có thể là một địa điểm (địa chỉ) hoặc nhiều địa điểm (ví dụ: quán cà phê và trạm xăng). Dữ liệu về ý định tuân theo định dạng URI được chỉ định cho từng ý định.

Định dạng ý định

Lớp Intent sử dụng định dạng sau cho ý định của ứng dụng điều hướng:

Danh mục: android.intent.category.DEFAULT

Hành động:

• Android Auto và Android Automotive OS: androidx.car.app.action.NAVIGATE
• Các kiểu dáng khác: android.intent.action.NAVIGATE

Lược đồ: geo

Ví dụ:

• geo:0,0?q=Googleplex
• geo:0,0?q=1600+Amphitheatre+parkway&mode=b&intent=add_a_stop
• geo:0,0?q=coffee+shop&mode=w&intent=navigation
• geo:1.1,2.2?q=Starbucks+on+Main+Street&mode=w&intent=navigation

Hành vi được đề xuất của ứng dụng: Hoạt động điều hướng đến vị trí đã chỉ định bắt đầu hoặc người dùng được yêu cầu chọn trong số nhiều lựa chọn.

Bộ lọc ý định trong tệp kê khai

Khai báo định dạng ý định sau trong tệp kê khai của ứng dụng để Gemini biết rằng ứng dụng điều hướng của bạn có thể nhận được ý định điều hướng.

Tất cả hệ số hình dạng, ngoại trừ Android Auto và Android Automotive OS:

<intent-filter>
  <action android:name="android.intent.action.NAVIGATE" />
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:scheme="geo" />
</intent-filter>

Android Auto và Android Automotive OS:

<intent-filter>
  <action android:name="androidx.car.app.action.NAVIGATE" />
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:scheme="geo" />
</intent-filter>

Tham số được cung cấp

Các tham số sau đây dự kiến sẽ có trong dữ liệu ý định của ứng dụng điều hướng được cung cấp.

Cụm từ tìm kiếm vị trí hoặc toạ độ địa lý

Mỗi truy vấn ý định điều hướng đều chứa một hoặc cả hai tham số này, tuỳ thuộc vào loại dữ liệu được yêu cầu:

• Cụm từ tìm kiếm vị trí

  Đề cập đến vị trí mà người dùng đang cố gắng di chuyển đến. Sử dụng dữ liệu này để phân giải đích đến của người dùng.

  Khoá tham số: q
  Giá trị: Đích đến mà người dùng truy vấn.

  Ví dụ: geo:0,0?q=Golden+Gate+Bridge
  Diễn giải: Người dùng muốn chuyển đến Cầu Cổng Vàng.

• Toạ độ địa lý (vĩ độ và kinh độ)

  Đề cập đến các toạ độ cụ thể mà người dùng sử dụng để điều hướng.

  Khoá tham số: geo:lat,long
  Giá trị: Toạ độ được người dùng truy vấn.

  Ví dụ: geo:1.1,2.2?mode=w&intent=navigation
  Giải thích: Người dùng muốn chuyển đến toạ độ (1.1, 2.2).

Thông số không bắt buộc

Các tham số không bắt buộc được cung cấp trong dữ liệu ý định của ứng dụng chỉ đường được mô tả trong phần này.

Intent

Xác định ý định của người dùng. Nếu bạn không đặt tham số này, thì ý định mặc định của người dùng sẽ được coi là navigation.

Lưu ý: Lớp này khác với lớp Intent có trong Android.

Khoá tham số: intent
Các giá trị có thể:

• navigation [giá trị mặc định] – Thay thế đích đến và bắt đầu chỉ đường. Sử dụng chế độ này cho các câu hỏi như đi đến x.
• add_a_stop – Thêm điểm dừng làm đích đến tiếp theo cùng với các đích đến trước đó. Sử dụng tham số này cho các truy vấn như thêm điểm dừng tại x.
• directions – Hiển thị chỉ đường mà không bắt đầu đi theo chỉ dẫn. Sử dụng tính năng này cho các cụm từ tìm kiếm như chỉ đường đến x.

Ví dụ: geo:47.61594547836694,-122.20373173098756?q=575+Bellevue+Square,+Bellevue,+WA+98004&intent=add_a_stop Diễn giải: Người dùng muốn thêm một điểm dừng vào Bellevue Square, Bellevue, với toạ độ hiện tại là [47,6, -122,2].

Lưu ý: Bạn có thể dùng trình mô phỏng Android Automotive OS để kiểm thử các ý định này.

Tránh

Xác định những thứ cần tránh trong chỉ đường.

Khoá tham số: avoid
Các giá trị có thể:

• f – phà
• h – đường cao tốc
• t – phí cầu đường

Ví dụ: geo:0,0?q=googleplex&avoid=tf
Giải thích: Người dùng muốn đi đến Googleplex mà không phải trả phí cầu đường và phí phà.

Phương thức đi lại

Chế độ di chuyển thể hiện phương tiện đi lại mà người dùng chỉ định trong truy vấn.

Lưu ý: Chế độ này áp dụng cho tất cả các kiểu dáng thiết bị, ngoại trừ Android Automotive OS.

Khoá tham số: mode
Các giá trị có thể:

• b – xe đạp
• d – lái xe
• x – taxi
• l – xe mô tô hai bánh
• r – phương tiện công cộng
• w – đi bộ

Ví dụ: geo:0,0?q=Googleplex&mode=r
Diễn giải: Người dùng muốn đi đến Googleplex bằng phương tiện công cộng.

Lối vào

Dùng để ghi nhật ký nguồn của mục nhập.

Các giá trị có thể: trợ lý

Ví dụ: geo:47.61594547836694,-122.20373173098756?entry=assistant

Mục đích tìm kiếm

Sử dụng mục đích tìm kiếm để tìm kiếm một cụm từ tìm kiếm và hiển thị nhiều kết quả dọc theo tuyến đường khi lái xe.

Định dạng ý định

Lớp Intent sử dụng định dạng sau cho các ý định tìm kiếm:

Danh mục: android.intent.category.DEFAULT

Hành động: android.intent.action.VIEW

Lược đồ: geo

Ví dụ: geo:0,0?q=restaurants+nearby

Hành vi được đề xuất của ứng dụng: Mở danh sách các vị trí phù hợp với cụm từ tìm kiếm của người dùng.

Lưu ý: Ý định sử dụng ứng dụng chỉ đường và mục đích tìm kiếm có các loại hành động khác nhau. Điều hướng là ACTION_NAVIGATE trong khi Tìm kiếm là ACTION_VIEW như được nêu trong Bộ lọc ý định của tệp kê khai.

Bộ lọc ý định trong tệp kê khai

Khai báo định dạng ý định sau trong tệp kê khai của ứng dụng để Gemini biết rằng ứng dụng điều hướng của bạn có thể nhận được ý định tìm kiếm:

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:scheme="geo" />
</intent-filter>

Tham số được cung cấp

Bạn cần cung cấp các tham số sau trong dữ liệu mục đích tìm kiếm được cung cấp.

Cụm từ tìm kiếm vị trí

Cụm từ tìm kiếm vị trí là vị trí mà người dùng đang tìm kiếm khi lái xe. Cụm từ tìm kiếm này có thể không chính xác hoặc nằm dọc theo một tuyến đường đang hoạt động.

Khoá tham số: q
Giá trị: Cụm từ tìm kiếm của người dùng, có thể là một loại vị trí như quán cà phê hoặc trường cao đẳng nhưng cũng có thể có các từ bổ nghĩa như -gần tôi hoặc -được đánh giá cao nhất.

Ví dụ: geo:0,0?q=restaurants+nearby
Diễn giải: Người dùng muốn tìm kiếm các nhà hàng gần đó.

Ý định hành động tuỳ chỉnh

Sử dụng đối tượng có ý định tùy chỉnh cho các thao tác tuỳ chỉnh như báo cáo tai nạn và kết thúc chỉ đường. Loại hành động chính được xác định bằng tham số truy vấn act. Bạn có thể đặt các tham số bổ sung tuỳ thuộc vào loại hành động.

Định dạng ý định

Lớp Intent sử dụng định dạng sau cho ý định hành động tuỳ chỉnh:

Danh mục: android.intent.category.DEFAULT

Hành động: android.intent.action.VIEW

Lược đồ: geo.action

Ví dụ: geo.action:?act=report&accident_type=major

Bộ lọc ý định trong tệp kê khai

Khai báo định dạng ý định sau đây trong tệp kê khai của ứng dụng để cho Gemini biết rằng ứng dụng điều hướng của bạn có thể nhận được ý định hành động tuỳ chỉnh.

<intent-filter>
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT"/>
  <data android:scheme="geo.action" />
</intent-filter>

Tham số được cung cấp

Bạn cần cung cấp các tham số sau trong dữ liệu ý định Thao tác tuỳ chỉnh:

Loại thao tác

Tham số này xác định loại hành động tuỳ chỉnh mà người dùng muốn thực hiện.

Khoá tham số: act

Ví dụ:

• geo.action:?act=report_crash&accident_type=major
  Diễn giải: Người dùng muốn báo cáo một tai nạn nghiêm trọng.

• geo.action:?act=mute
  Diễn giải: Người dùng muốn tắt hướng dẫn bằng giọng nói.

• geo.action:?act=exit_navigation
  Diễn giải: Người dùng muốn thoát khỏi chế độ chỉ đường hiện tại.

Hành vi đề xuất của ứng dụng: Thực hiện hành động được yêu cầu trên ứng dụng điều hướng hoặc hiển thị thông báo về hành động không được hỗ trợ.

Hình sau đây mô tả một ví dụ về các cặp khoá-giá trị trong truy vấn phản hồi:

Hình 2. Luồng dữ liệu ý định của thao tác tuỳ chỉnh.

Cặp khoá-giá trị:

"act": "report_crash"
"road_direction": other_side"

Mọi thao tác tuỳ chỉnh luôn có một tham số act làm khoá. Trong đoạn mã ví dụ nêu trên, một số thao tác có thể có thêm các cặp khoá-giá trị. Ví dụ: act=report_crash hỗ trợ các khoá bổ sung sau: accident_type và road_direction.

Khoá accident_type có thể hỗ trợ 2 giá trị là minor và major.

Lưu ý: Các tham số bổ sung là không bắt buộc và có thể không xuất hiện trong mọi phản hồi theo ý định.

Các giá trị có thể

Bảng này liệt kê các giá trị có thể có mà Gemini có thể truyền dưới dạng hành động mà người dùng đang cố gắng thực hiện trên ứng dụng điều hướng.

Lưu ý: Nếu chỉ hỗ trợ một số thao tác trong số này, thì ứng dụng của bạn phải thông báo cho người dùng bất cứ khi nào họ yêu cầu một thao tác không được hỗ trợ.

Giá trị	Mô tả	Khoá tham số không bắt buộc	Giá trị tham số không bắt buộc
allow_ferries	Thay đổi lựa chọn ưu tiên về tuyến đường để cho phép đi phà.
allow_highways	Thay đổi lựa chọn ưu tiên về tuyến đường để cho phép đường cao tốc.
allow_tolls	Thay đổi lựa chọn ưu tiên về tuyến đường để cho phép đường có thu phí.
avoid_ferries	Thay đổi lựa chọn ưu tiên về tuyến đường để tránh phà.
avoid_highways	Thay đổi lựa chọn ưu tiên về tuyến đường để tránh đường cao tốc.
avoid_tolls	Thay đổi lựa chọn ưu tiên về tuyến đường để tránh trạm thu phí.
distance_to_destination	Hiển thị khoảng cách đến điểm đến.
distance_to_next_turn	Hiện khoảng cách đến ngã rẽ tiếp theo.
eta	Hiện Giờ đến dự kiến đến đích.
exit_navigation	Thoát hoặc huỷ chế độ chỉ đường.
follow_mode	Thay đổi chế độ xem bản đồ thành chế độ theo dõi.
go_back	Quay lại thao tác trước đó trên bản đồ.
hide_satellite	Thay đổi chế độ cài đặt bản đồ để ẩn thông tin về vệ tinh.
hide_traffic	Thay đổi chế độ cài đặt bản đồ để ẩn thông tin giao thông.
mute	Tắt tiếng hướng dẫn bằng giọng nói.
query_current_road	Cho biết con đường hiện tại mà người dùng đang đi.
query_destination	Cho biết đích đến.
query_next_turn	Cho biết ngã rẽ tiếp theo.
report_crash	Báo cáo sự cố.	accident_type	minor
			major
		road_direction	this_side
			other_side
report_hazard	Báo cáo mối nguy hiểm.	hazard_type	animal
			broken_traffic_light
			construction
			flooding
			fog
			hail
			ice
			missing_sign
			object_on_road
			pothole
			roadkill
			snow
			vehicle
			weather
		road_direction	this_side
			other_side
		location_on_road	on_road
			on_shoulder
report_police	Báo cáo hoạt động của cảnh sát.	road_direction	this_side
			other_side
report_road_closure	Báo cáo đường bị đóng.	road_closure_type	partial
			full
report_traffic	Báo cáo tình hình giao thông.	traffic_type	moderate
			heavy
			standstill
		road_direction	this_side
			other_side
route_overview	Hiển thị thông tin tổng quan về tuyến đường.
show_alternates	Hiện các tuyến đường thay thế.
show_directions_list	Hiện hướng dẫn từng chặng.
show_satellite	Hiện thông tin vệ tinh trên bản đồ.
show_traffic	Hiển thị tình hình giao thông trên bản đồ.
time_to_destination	Hiện Giờ đến dự kiến đến điểm đến.
time_to_next_turn	Hiện Giờ đến dự kiến đến lượt rẽ tiếp theo.
unmute	Bật tiếng hướng dẫn bằng giọng nói.

Truy xuất trạng thái điều hướng

Để đảm bảo Gemini có thể cung cấp thông tin chính xác theo thời gian thực cho người dùng khi họ hỏi về trạng thái chuyến đi, ứng dụng của bạn phải cung cấp siêu dữ liệu điều hướng bằng dịch vụ ô tô NavigationManager. Để biết hướng dẫn triển khai, hãy xem phần Truyền siêu dữ liệu chỉ đường.