הטמעת כוונות של אפליקציות ניווט

Google Assistant משתמשת בשלושה פורמטים שונים של כוונות (intents) שאפליקציית הניווט יכולה לתמוך בהם. כדי להשיג יכולת פעולה הדדית ולשלב את האפליקציה עם Google Assistant, צריך להצהיר על מסנני ה-Intent שמפורטים בדף הזה במניפסט של האפליקציה. מידע נוסף על כוונות זמין במאמר Intent.

הכיתה Intent של אפליקציית הניווט של Assistant תומכת בכוונות הבאות:

  • כוונת ניווט
  • כוונת החיפוש
  • כוונת רכישה של פעולה בהתאמה אישית

זרימת נתוני הכוונה

איור 1. זרימת נתוני הכוונה.

פרמטרים בנתוני כוונת הרכישה

נתוני הכוונה עומדים בפורמט URI שמכיל פרמטרים שמבוססים על הכוונה שאתם מעבירים. חלק מהפרמטרים תמיד מוצגים בנתונים. כלומר, תמיד יהיה להם ערך מפורש. עם זאת, לפרמטרים אופציונליים לא תמיד מוגדר ערך בנתונים. מידע נוסף זמין במאמר בדיקת נתונים.

כוונות אופליין

לכל הכוונות שמוצגות בדף הזה יש וריאנטים אופליין זמינים. אפשר להבדיל ביניהם על ידי הוספת .offline לסכימה שלהם. לדוגמה, כוונה לניווט משתמשת בסכמה geo.offline. מסנני ה-Intent האלה במניפסט מצביעים על היכולת של האפליקציה לתמוך בפעולות האלה במצב אופליין.

משתמשים בכוונה ניווט כדי לענות לבקשה של משתמש לנווט ליעד ספציפי. היעד יכול להיות מיקום יחיד (כתובת) או כמה מיקומים (לדוגמה, בתי קפה ותחנות דלק). נתוני הכוונה עומדים בפורמט URI שצוין לכל כוונה.

פורמט הכוונה

בכיתה Intent נעשה שימוש בפורמט הבא לכוונה של אפליקציית ניווט:

קטגוריה: android.intent.category.DEFAULT

פעולה:

  • Android Auto ו-Android Automotive OS: androidx.car.app.action.NAVIGATE
  • גורמי צורה אחרים: android.intent.action.NAVIGATE

Scheme: geo

דוגמאות:

  • 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

הצעה להתנהגות האפליקציה: מתחיל הניווט למיקום שצוין או שהמשתמש מתבקש לבחור מבין כמה אפשרויות.

מסנני Manifest Intent

כדי ש-Google Assistant תדע שאפליקציית הניווט שלכם יכולה לקבל כוונות ניווט, צריך להצהיר על פורמט הכוונה הבא בקובץ המניפסט של האפליקציה.

כל גורמי הצורה, מלבד Android Auto ו-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 ו-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>

הפרמטרים שסופקו

הפרמטרים הבאים אמורים להיות זמינים בנתוני הכוונה של אפליקציית הניווט שסופקו.

שאילתה לגבי מיקום או קואורדינטות גיאוגרפיות

כל שאילתה של כוונת ניווט מכילה אחד מהפרמטרים האלה או את שניהם, בהתאם לסוג הנתונים המבוקשים:

  • שאילתת מיקום

    מתייחס למיקום שאליו המשתמש מנסה לנווט. משתמשים בנתונים האלה כדי לפתור את היעד של המשתמש.

    מפתח הפרמטר: q
    ערך: היעד של המשתמש שאליו בוצעה השאילתה.

    דוגמה: geo:0,0?q=Golden+Gate+Bridge
    פרשנות: המשתמש רוצה לנווט אל גשר הזהב.

  • קואורדינטות גיאוגרפיות (קו רוחב וקו אורך)

    קואורדינטות ספציפיות שבהן המשתמש משתמש לניווט.

    מפתח הפרמטר: geo:lat,long
    ערך: הקואורדינטות של המשתמש שהוזנו בשאילתה.

    דוגמה: geo:1.1,2.2?mode=w&intent=navigation
    פרשנות: המשתמש רוצה לנווט אל הקואורדינטות (1.1, 2.2).

פרמטרים אופציונליים

בקטע הזה מתוארים הפרמטרים האופציונליים שסופקו בנתוני הכוונה של אפליקציית הניווט.

כוונה

מגדיר את כוונת המשתמש. אם לא מגדירים את הפרמטר הזה, ברירת המחדל של כוונת המשתמש היא navigation.

מפתח הפרמטר: intent
ערכים אפשריים:

  • navigation [ערך ברירת מחדל] – מחליף את היעד ומתחיל את הניווט. אפשר להשתמש באפשרות הזו בשאילתות כמו navigate to x.
  • add_a_stop – הוספת העצירה ליעד הבא יחד עם היעדים הקודמים. אפשר להשתמש באפשרות הזו בשאילתות כמו add a stop at x.
  • directions – הצגת מסלול ללא הפעלת הניווט. אפשר להשתמש באפשרות הזו בשאילתות כמו directions to x.

דוגמה: geo:47.61594547836694,-122.20373173098756?q=575+Bellevue+Square,+Bellevue,+WA+98004&intent=add_a_stop פרשנות: המשתמש רוצה להוסיף עצירה ב-Bellevue Square, ‏ Bellevue, עם הקואורדינטות הנוכחיות [47.6, -122.2].

הימנעות

הגדרת דברים שכדאי להימנע מהם במהלך הניווט.

מפתח הפרמטר: avoid
ערכים אפשריים:

  • f – מעבורות
  • h – כבישים מהירים
  • t – כבישי אגרה

דוגמה: geo:0,0?q=googleplex&avoid=tf
פרשנות: המשתמש רוצה לנווט אל Googleplex תוך הימנעות מכבישי אגרה וממעבורות.

מצב נסיעה

מצב הנסיעה מייצג את אמצעי התחבורה שצוין בשאילתה על ידי המשתמש.

מפתח הפרמטר: mode
ערכים אפשריים:

  • b – אופניים
  • d – נסיעה
  • x – מונית
  • l – רכב דו-גלגלי
  • r – תחבורה ציבורית
  • w – הליכה

דוגמה: geo:0,0?q=Googleplex&mode=r
פרשנות: המשתמש רוצה לנווט אל Googleplex באמצעות תחבורה ציבורית.

הערך

משמש לרישום ביומן של מקור הנתונים.

ערכים אפשריים: assistant

דוגמה: geo:47.61594547836694,-122.20373173098756?entry=assistant

כוונת החיפוש

אתם יכולים להשתמש בכוונה לחיפוש כדי לחפש שאילתה ולהציג כמה תוצאות לאורך המסלול בזמן הנסיעה.

פורמט הכוונה

בכיתה Intent נעשה שימוש בפורמט הבא לכוונות החיפוש:

קטגוריה: android.intent.category.DEFAULT

פעולה: android.intent.action.VIEW

Scheme: geo

דוגמה: geo:0,0?q=restaurants+nearby

הצעה להתנהגות האפליקציה: פתיחת רשימה של מיקומים שתואמים לשאילתה של המשתמש.

מסנני Manifest Intent

כדי ש-Google Assistant תדע שאפליקציית הניווט שלכם יכולה לקבל כוונות חיפוש, צריך להצהיר על פורמט הכוונה הבא בקובץ המניפסט של האפליקציה:

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

הפרמטרים שסופקו

הפרמטרים הבאים אמורים להיות זמינים בנתוני כוונת החיפוש שסופקו.

שאילתה לגבי מיקום

שאילתת מיקום היא המיקום שהמשתמש מחפש בזמן הנהיגה. השאילתה הזו יכולה להיות לא מדויקת או לעבור לאורך מסלול ניווט פעיל.

מפתח הפרמטר: q
ערך: מונח החיפוש של המשתמש. המונח יכול להיות סוג מיקום כמו בית קפה או מכללה, אבל יכולים להיות בו גם מילות כמות כמו -ליד הבית שלי או -עם הדירוג הכי גבוה.

דוגמה: geo:0,0?q=restaurants+nearby
פרשנות: המשתמש רוצה לחפש מסעדות בקרבת מקום.

כוונת רכישה של פעולה בהתאמה אישית

שימוש בכוונה מותאמת אישית לפעולות בהתאמה אישית, כמו דיווח על תאונות וסיום הניווט. סוג הפעולה הראשית מוגדר על ידי פרמטר השאילתה act. אפשר להגדיר פרמטרים נוספים בהתאם לסוג הפעולה.

פורמט הכוונה

בכיתה Intent נעשה שימוש בפורמט הבא לכוונת פעולה בהתאמה אישית:

קטגוריה: android.intent.category.DEFAULT

פעולה: android.intent.action.VIEW

Scheme: geo.action

דוגמה: geo.action:?act=report&accident_type=major

מסנני Manifest Intent

כדי להודיע ל-Google Assistant שאפליקציית הניווט שלכם יכולה לקבל כוונות פעולה בהתאמה אישית, צריך להצהיר על פורמט הכוונה הבא בקובץ המניפסט של האפליקציה.

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

הפרמטרים שסופקו

הפרמטרים הבאים אמורים להיות זמינים בנתוני הכוונה של הפעולה בהתאמה אישית שסיפקתם:

סוג הפעולה

הוא מגדיר את סוג הפעולה המותאמת אישית שהמשתמש רוצה לבצע.

מפתח פרמטר: act

דוגמאות:

  • geo.action:?act=report_crash&accident_type=major
    פרשנות: המשתמש רוצה לדווח על תאונה חמורה.

  • geo.action:?act=mute
    פרשנות: המשתמש רוצה להשתיק את ההנחיות הקוליות.

  • geo.action:?act=exit_navigation
    פרשנות: המשתמש רוצה לצאת מהניווט הנוכחי.

הצעה להתנהגות האפליקציה: ביצוע הפעולה המבוקשת באפליקציית הניווט או הצגת הודעת פעולה שלא נתמכת.

באיור הבא מוצגת דוגמה לצמדי מפתח/ערך בשאילתת התגובה:

תהליך העברת הנתונים של כוונת הרכישה של פעולה בהתאמה אישית

איור 2. תהליך העברת הנתונים של כוונת הפעולה בהתאמה אישית.

צמד מפתח/ערך: 

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

לכל פעולה בהתאמה אישית יש תמיד פרמטר act בתור המפתח. בקוד לדוגמה שצוין למעלה, לפעולות מסוימות יכולים להיות צמדי מפתח/ערך נוספים. לדוגמה, act=report_crash תומך במפתחות הנוספים הבאים: accident_type ו-road_direction.

המפתח accident_type יכול לתמוך בשני ערכים, minor ו-major.

ערכים אפשריים

בטבלה מפורטים ערכים אפשריים ש-Google Assistant יכולה להעביר בתור הפעולה שהמשתמש מנסה לבצע באפליקציית הניווט.

ערך תיאור מפתחות פרמטרים אופציונליים ערכי פרמטרים אופציונליים
allow_ferries משנים את העדפת המסלול כך שתכלול מעבורות.
allow_highways משנים את העדפת המסלול כך שתכלול כבישים מהירים.
allow_tolls משנים את העדפת המסלול כך שתכלול דרכים עם תשלום.
apply_electric_vehicle_connector_filter הצגת מיקומי טעינה לרכב חשמלי שתואמים למחבר של הרכב.
apply_electric_vehicle_fast_charging_filter הצגת מיקומים של תחנות טעינה לרכבים חשמליים (EV) עם טעינה מהירה בלבד.
apply_electric_vehicle_payment_filter הצגת מיקומי טעינה לרכבים חשמליים (EV) שדורשים תשלום בלבד.
avoid_ferries שינוי העדפת המסלול כדי להימנע ממעבורות.
avoid_highways שינוי ההעדפה של המסלול כדי להימנע מכבישים מהירים.
avoid_tolls שינוי העדפת המסלול כדי להימנע מתשלום אגרה.
clear_search_results לנקות את תוצאות החיפוש במפה.
distance_to_destination הצגת המרחק ליעד.
distance_to_next_turn הצגת המרחק עד הפנייה הבאה.
eta הצגת זמן ההגעה המשוער ליעד.
exit_navigation לצאת מהניווט או לבטל אותו.
follow_mode שינוי תצוגת המפה למצב מעקב.
go_back חזרה לפעולה הקודמת במפה.
hide_satellite משנים את הגדרת המפה כדי להסתיר את פרטי הלוויין.
hide_traffic משנים את הגדרת המפה כדי להסתיר את מידע התנועה.
mute משביתים את ההנחיות הקוליות.
query_current_road הצגת הכביש הנוכחי שבו המשתמש נמצא.
query_destination הצגת היעד.
query_next_turn הצגת הפנייה הבאה.
remove_electric_vehicle_connector_filter הסרת הסינון של מיקומי טעינה לרכב חשמלי שתואמים למחבר של הרכב.
remove_electric_vehicle_fast_charging_filter הסרת המסנן של מיקומי טעינה לרכב חשמלי (EV) שמציעים טעינה מהירה.
remove_electric_vehicle_payment_filter להסיר את הסינון של מיקומי תחנות טעינה לרכב חשמלי (EV) שדורשים תשלום.
report_crash דיווח על תאונות. accident_type minor
major
road_direction this_side
other_side
report_hazard דיווח על סכנות. 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 דיווח על פעילות משטרתית. road_direction this_side
other_side
report_road_closure דיווח על חסימות כבישים. road_closure_type partial
full
report_traffic דיווח על עומס תנועה. traffic_type moderate
heavy
standstill
road_direction this_side
other_side
resume_navigation ממשיכים בניווט.
route_overview הצגת סקירה כללית של המסלול.
show_alternates הצגת מסלולים חלופיים.
show_directions_list הצגת מסלול מפורט.
show_satellite הצגת מידע מלוויין במפה.
show_traffic הצגת תנועה במפה.
time_to_destination הצגת זמן ההגעה המשוער ליעד.
time_to_next_turn הצגת זמן ההגעה המשוער לפנייה הבאה.
unmute מבטלים את ההשתקה של ההנחיה הקולית.