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

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

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

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

זרימת נתונים של כוונות

איור 1. זרימת נתונים של כוונות.

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

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

התעניינות במיקום

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

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

פורמט הכוונה

המחלקות Intent משתמשות בפורמט הבא ל-intent של אפליקציית ניווט:

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

פעולה:

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

סכמה: 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

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

מסנני Intent בקובץ המניפסט

צריך להצהיר על פורמט הכוונה הבא בקובץ המניפסט של האפליקציה כדי ש-Gemini או 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 [ערך ברירת מחדל] – מחליף את היעד ומתחיל את הניווט. משתמשים בערך הזה בשאילתות כמו נווט אל x.
  • ‫add_a_stop – מוסיף את העצירה כיעד הבא יחד עם היעדים הקודמים. אפשר להשתמש בזה לשאילתות כמו add a stop at x (הוספת עצירה ב-x).
  • ‫directions – הצגת מסלול בלי להתחיל ניווט. אפשר להשתמש בזה לשאילתות כמו הוראות הגעה אל 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 – drive
  • 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

סכמה: geo

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

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

מסנני Intent בקובץ המניפסט

מצהירים על פורמט הכוונה הבא בקובץ המניפסט של האפליקציה כדי ש-Gemini או 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

סכמה: geo.action

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

מסנני Intent בקובץ המניפסט

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

<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.

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

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

ערך תיאור מפתחות פרמטרים אופציונליים ערכי פרמטרים אופציונליים
allow_ferries שינוי העדפות המסלול כדי לאפשר מעבורות.
allow_highways שינוי העדפת המסלול כדי לאפשר נסיעה בכבישים מהירים.
allow_tolls שינוי העדפות המסלול כדי לאפשר נסיעה בכבישי אגרה.
avoid_ferries משנים את העדפת המסלול כדי להימנע ממעבורות.
avoid_highways משנים את העדפת המסלול כדי להימנע מכבישים מהירים.
avoid_tolls משנים את העדפת המסלול כדי להימנע מכבישי אגרה.
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 הצגת הפנייה הבאה.
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
route_overview הצגת סקירה כללית של המסלול.
show_alternates הצגת מסלולים חלופיים.
show_directions_list הצגת הוראות מסלול מפורט.
show_satellite הצגת נתוני לוויין במפה.
show_traffic הצגת תנועה במפה
time_to_destination הצגת זמן ההגעה המשוער ליעד.
time_to_next_turn הצגת זמן ההגעה המשוער לפנייה הבאה.
unmute ביטול ההשתקה של ההנחיה הקולית.

אחזור סטטוס הניווט (Gemini בלבד)

כדי לוודא ש-Gemini יוכל לספק למשתמש מידע מדויק בזמן אמת כשמבקשים לדעת מה סטטוס הנסיעה, האפליקציה שלכם צריכה לספק מטא-נתונים של ניווט באמצעות שירות הרכב NavigationManager. בפרט, האפליקציה שלכם צריכה לספק את היכולות ואת הסכמת המשתמש לשיתוף המידע עם Gemini באמצעות NavigationManager.setVoiceAssistantCapabilities. להנחיות הטמעה, אפשר לעיין במאמר Communicate navigation metadata.