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

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 שזמין ב-Android.

מפתח הפרמטר: 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].

טיפ: אפשר להשתמש במעבד Android Automotive OS כדי לבדוק את הכוונות האלה.

הימנעות

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

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

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

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

מצב נסיעה

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

הערה: המצב הזה רלוונטי לכל גורמי הצורה, מלבד Android Automotive OS.

מפתח הפרמטר: 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

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

טיפ: לכוונה לאפליקציית ניווט ולכוונה לחיפוש יש סוגי פעולות שונים. הניווט הוא ACTION_NAVIGATE והחיפוש הוא ACTION_VIEW, כפי שמתואר במסנני ה-Intent של המניפסט.

מסנני 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	מבטלים את ההשתקה של ההנחיה הקולית.