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

Trợ lý Google sử dụng 3 định dạng ý định mà ứng dụng chỉ đườ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 Trợ lý Google bằng cách khai báo các bộ lọc ý định được nêu chi tiết trong 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 Intent của ứng dụng điều hướng Trợ lý 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

Luồng dữ liệu ý định

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

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 các giá trị này 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ê trong trang này đều có biến thể ngoại tuyến. Bạn có thể phân biệt các lớp này bằng cách thêm .offline vào giao thức của chúng. Ví dụ: ý định điều hướng sử dụng giao thức geo.offline. Các bộ lọc ý định này trong tệp kê khai cho biết khả năng của ứng dụng trong việc hỗ trợ các thao tác này khi không có mạ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ể. Đích đến này có thể là một vị trí (địa chỉ) hoặc nhiều vị trí (ví dụ: quán cà phê và trạm xăng). Dữ liệu ý đị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 ứ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 đề xuất của ứng dụng: Bắt đầu điều hướng đến vị trí đã chỉ định hoặc người dùng được yêu cầu chọn trong số nhiều tuỳ 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 để Trợ lý Google biết rằng ứng dụng chỉ đường của bạn có thể nhận được ý định chỉ đườ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 chỉ đường được cung cấp.

Truy vấn 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:

  • Truy vấn vị trí

    Tham chiếu đến vị trí mà người dùng đang cố gắng điều hướng đế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 được truy vấn của người dùng.

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

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

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

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

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

Tham số tuỳ chọn

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.

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

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

Ví dụ: geo:47.61594547836694,-122.20373173098756?q=575+Bellevue+Square,+Bellevue,+WA+98004&intent=add_a_stop Giải thích: 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 [47,6, -122,2].

Tránh

Xác định những điều cần tránh trong hoạt động điều hướng.

Khoá thông 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, tránh đường thu phí và phà.

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

Chế độ di chuyển đại diện cho phương thức di chuyển do người dùng chỉ định trong truy vấn.

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

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

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

Mục nhập

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 ý định 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 đang lái xe.

Định dạng ý định

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

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

Thao tác: android.intent.action.VIEW

Lược đồ: geo

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

Hành vi đề 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.

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 để Trợ lý Google biết rằng ứng dụng chỉ đườ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

Các tham số sau đây dự kiến sẽ có trong dữ liệu ý định tìm kiếm được cung cấp.

Truy vấn vị trí

Truy vấn vị trí là vị trí mà người dùng đang tìm kiếm khi lái xe. Truy vấn này có thể không chính xác hoặc nằm dọc theo tuyến đường điều hướ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ư cửa hàng cà phê hoặc trường cao đẳng, nhưng cũng có thể có các đại lượng như -gần tôi hoặc -có điểm xếp hạng cao nhất.

Ví dụ: geo:0,0?q=restaurants+nearby
Giải thích: Người dùng muốn tìm kiếm nhà hàng lân cận.

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

Sử dụng ý định tuỳ chỉnh cho các hành động tuỳ chỉnh như báo cáo tai nạn và kết thúc điều hướ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

Thao tác: 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 trong tệp kê khai của ứng dụng để cho Trợ lý Google biết rằng ứng dụng chỉ đườ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

Các thông số sau đây dự kiến sẽ có trong dữ liệu ý định Hành động tuỳ chỉnh được cung cấp:

Loại thao tác

Thuộc tính này xác định loại thao tác 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
    Giải thích: Người dùng muốn báo cáo một vụ tai nạn lớn.

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

  • geo.action:?act=exit_navigation
    Giải thích: Người dùng muốn thoát khỏi thao tác điều hướ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 chỉ đườ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ả ví dụ về cặp khoá-giá trị trong truy vấn phản hồi:

Luồng dữ liệu ý định hành động tuỳ chỉnh

Hình 2. Luồng dữ liệu ý định hành động tuỳ chỉnh.

Cặp khoá-giá trị: 

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

Mọi hành động tuỳ chỉnh luôn có tham số act làm khoá. Trong mã ví dụ nêu trên, một số hành động 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ợ hai giá trị là minor và major.

Các giá trị có thể dùng

Bảng này liệt kê các giá trị có thể có mà Trợ lý Google 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 chỉ đường.

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 phà.
allow_highways Thay đổi lựa chọn ưu tiên về tuyến đường để cho phép đi đường cao tốc.
allow_tolls Thay đổi lựa chọn ưu tiên về tuyến đường để cho phép đường thu phí.
apply_electric_vehicle_connector_filter Chỉ hiển thị các địa điểm sạc xe điện khớp với giắc cắm của xe.
apply_electric_vehicle_fast_charging_filter Chỉ hiển thị các vị trí sạc xe điện là trạm sạc nhanh.
apply_electric_vehicle_payment_filter Chỉ hiện các địa điểm sạc xe điện yêu cầu thanh toán.
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í.
clear_search_results Xoá kết quả tìm kiếm trên bản đồ.
distance_to_destination Hiển thị khoảng cách đến điểm đến.
distance_to_next_turn Cho biết khoảng cách đến điểm rẽ tiếp theo.
eta Hiển thị thời gian đến dự kiến cho điểm đến.
exit_navigation Thoát hoặc huỷ 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ệ tinh.
hide_traffic Thay đổi chế độ cài đặt bản đồ để ẩn thông tin về tình trạng giao thông.
mute Tắt tiếng hướng dẫn bằng giọng nói.
query_current_road Cho biết người dùng đang đi trên con đường nào.
query_destination Cho biết đích đến là gì.
query_next_turn Cho biết hướng rẽ tiếp theo.
remove_electric_vehicle_connector_filter Xoá bộ lọc cho các vị trí sạc xe điện khớp với đầu nối của xe.
remove_electric_vehicle_fast_charging_filter Xoá bộ lọc cho các vị trí sạc xe điện là trạm sạc nhanh.
remove_electric_vehicle_payment_filter Xoá bộ lọc cho các vị trí sạc xe điện yêu cầu thanh toán.
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
resume_navigation Tiếp tục điều hướng.
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ị 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 thị thời gian đến dự kiến của điểm đến.
time_to_next_turn Hiển thị thời gian đến lượt rẽ tiếp theo.
unmute Bật hướng dẫn bằng giọng nói.