כוונות של מפות Google ל-Android Automotive

באמצעות כוונות של Android, אפשר להפעיל ניווט במפות Google ל-Android Automotive.

סקירה כללית

בדף הזה מתוארים ה-intents שבהם אפשר להשתמש עם מפות Google ל-Android Automotive. למידע מפורט על פיתוח ל-Android, אפשר לעיין במאמרים הבאים:

• כוונות ומסנני כוונות
• Intents נפוצים בפלטפורמת Android

בקשות לזיהוי כוונות

כדי להפעיל את מפות Google ל-Android Automotive באמצעות Intent, צריך קודם ליצור אובייקט Intent ולציין את הפעולה, ה-URI והחבילה שלו.

• פעולה. כל הכוונות של מפות Google נקראות כפעולת תצוגה, ACTION_VIEW.

• URI ‫Google Maps intents משתמשים במחרוזות עם קידוד URI שמציינות פעולה שנבחרה, יחד עם נתונים מסוימים לביצוע הפעולה.

• חבילה. התקשרות אל setPackage("com.google.android.apps.maps") מוודאת שאפליקציית מפות Google ל-Android מטפלת ב-Intent. אם החבילה לא מוגדרת, המערכת קובעת אילו אפליקציות יכולות לטפל ב-Intent. אם יש כמה אפליקציות זמינות, יכול להיות שתתבקשו לבחור באיזו אפליקציה להשתמש.

אחרי שיוצרים את הכוונה, אפשר לבקש מהמערכת להפעיל את האפליקציה הקשורה בכמה דרכים. שיטה נפוצה היא להעביר את ה-Intent לשיטה startActivity(). המערכת תפעיל את האפליקציה הנדרשת, במקרה הזה מפות Google, ותתחיל את Activity המתאים.

// Create a Uri from an intent string. Use the result to create an Intent.
Uri mapIntentUri =
Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
// Create an Intent from mapIntentUri. Set the action to ACTION_VIEW
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
// Make the Intent explicit by setting the Google Maps package
mapIntent.setPackage("com.google.android.apps.maps");
// Attempt to start an activity that can handle the Intent
startActivity(mapIntent);

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

כדי לוודא שאפליקציה זמינה לקבלת הכוונה, קוראים ל-resolveActivity() באובייקט Intent. אם התוצאה היא non-null, יש לפחות אפליקציה אחת שיכולה לטפל ב-Intent, ואפשר לקרוא בבטחה ל-startActivity(). אם התוצאה היא null, לא כדאי להשתמש ב-intent, ואם אפשר, כדאי להשבית את התכונה שמפעילה את ה-intent.

if (mapIntent.resolveActivity(getPackageManager()) != null) {
...
}

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

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
if (mapIntent.resolveActivity(getPackageManager()) != null) {
startActivity(mapIntent);
}

מחרוזות שאילתה מקודדות ב-URI

כל המחרוזות שמועברות אל כוונות השימוש במפות Google חייבות להיות מקודדות ב-URI. לדוגמה, המחרוזת "1st & Pike, Seattle" צריכה להפוך ל-1st%20%26%20Pike%2C%20Seattle. אפשר לקודד רווחים במחרוזת באמצעות %20 או להחליף אותם בסימן הפלוס (+).

אפשר להשתמש בשיטה android.net.Uri encode() כדי לקודד את המחרוזות. לדוגמה:

Uri mapIntentUri = Uri.parse("google.navigation:q=" + Uri.encode("1st & Pike, Seattle"));

הצגת מפה

אפשר להשתמש בכוונת geo: כדי להציג מפה במיקום מסוים וברמת זום מסוימת. לדוגמה:

geo:latitude,longitude?z=zoom

פרמטרים

• ‫latitude ו-longitude מגדירים את נקודת המרכז של המפה.

• ‫z מגדיר באופן אופציונלי את רמת הזום ההתחלתית של המפה. הערכים הקבילים נעים בין 0 (כל העולם) ל-21 (בניינים ספציפיים). המגבלה העליונה עשויה להשתנות בהתאם לנתוני המפה שזמינים במיקום שנבחר.

דוגמה

// Creates an intent that will load a map of San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

חפש מיקום

אפשר להשתמש ב-Intent הזה כדי להציג שאילתות חיפוש באזור תצוגה שצוין:

geo:latitude,longitude?q=query
geo:0,0?q=my+street+address

פרמטרים

בנוסף לפרמטרים שמשמשים להצגת מפה, חיפוש Google תומך בפרמטר הזה:

• ‫q מגדיר את המקומות שיוצגו במפה. חובה לציין את הפרמטר q בכל בקשות החיפוש. אפשר להזין מיקום כשם של מקום או ככתובת. המחרוזת צריכה להיות מוצגת בפורמט URL-escaped, כך שכתובת כמו "City Hall, New York, NY" תומר ל-City+Hall%2CNew+York%2CNY.

הטיה של תוצאות החיפוש באמצעות קואורדינטות

כשמחפשים מיקום ספציפי מאוד, לא חובה לציין את קווי הרוחב והאורך אם הם כלולים בפרמטר q. עם זאת, אם אתם לא יודעים את הכתובת המדויקת או שהשאילתה לא ברורה, אתם יכולים לנסות להטות את תוצאות החיפוש על ידי ציון קואורדינטה. לדוגמה, חיפוש של הכתובת "Main Street" עשוי להחזיר יותר מדי תוצאות:

// Searching for "101 Main Street" with no lat/long might return too many results
Uri gmmIntentUri = Uri.parse("geo:0,0?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

הוספת קו רוחב וקו אורך ל-URI של הכוונה משפיעה על התוצאות ומכוונת אותן לאזור מסוים:

// Searches for "101 Main Street" near San Francisco
Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?q=101+main+street");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

חיפוש לאורך המסלול

אם נשלח כוונת חיפוש geo:latitude,longitude?q=query במהלך הניווט, היא תפעיל חיפוש לאורך המסלול והמערכת תתעלם מקו הרוחב וקו האורך.

חיפוש קטגוריות מוגדרות מראש

כדי לתמוך בשילוב עם הרכב, מפות Google ברכב תומכות ב-Intent שמציג את הקטגוריות המוגדרות מראש האלה:

הכוונה של הקטגוריה היא בפורמט geo:lat,lng?c=category.

השימוש ב-c=<pre-defined category> לא תלוי בהגדרות הלוקאל של המשתמש. במפות Google מוצגות תוצאות רלוונטיות בהתאם ללוקאל המתאים לקטגוריה הזו. לדוגמה:

// Search for gas stations nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?c=gas_station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

חיפוש קטגורי אחר

אם מעבירים מונח חיפוש כללי (כמו 'מסעדות' או 'בתי קפה') בלוקאל של המשתמש, מערכת מפות Google ל-Android Automotive מחפשת כרטיסי מידע על עסקים שתואמים לקריטריונים. אם מצוינים קו רוחב וקו אורך ספציפיים בכוונת geo:, החיפוש מתבצע סביב המיקום הזה. אם לא צוין מיקום (למשל, geo:0,0), מערכת מפות Google מנסה למצוא כרטיסי מידע על עסקים בסביבה. לדוגמה:

// Search for restaurants nearby
Uri gmmIntentUri = Uri.parse("geo:0,0?q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

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

Uri gmmIntentUri = Uri.parse("geo:37.7749,-122.4194?z=10&q=restaurants");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, gmmIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

הפעלת מסלול מפורט

לעיון במסמכי תיעוד בנושא הפעלת ניווט מפורט במכשירי Android אחרים, אפשר לעבור אל הפעלת ניווט מפורט ב-Intents של מפות Google ל-Android.

אפשר להשתמש ב-Intent הזה כדי להפעיל את הניווט במפות Google עם הוראות ניווט מפורטות אל כתובת אחת או כמה כתובות או קואורדינטות שצוינו. ההוראות תמיד ניתנות מהמיקום הנוכחי של המשתמש.

google.navigation:q=a+street+address
google.navigation:q=latitude,longitude
google.navigation:place=placename

פרמטרים

כדי להתחיל בניווט, משתמשים ב-place או ב-q עם waypoints (אופציונלי). כדי לסמן נקודת עצירה כנקודת טעינה (אופציונלי), אפשר לעיין במאמר בנושא שליחת תוכנית נסיעה לרכב חשמלי למפות Google.

• ‫q מגדיר את נקודת הקצה לחיפושים של ניווט. זה יכול להיות קו רוחב וקו אורך או כתובת בפורמט של שאילתה. אם מדובר במחרוזת שאילתה שמחזירה יותר מתוצאה אחת, התוצאה הראשונה תיבחר.

• ‫place מגדיר את נקודת הסיום לבית או לעבודה. מציינים home כדי לנווט לבית של המשתמש, ומציינים work כדי לנווט למקום העבודה של המשתמש.

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

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

• ‫waypoints מציין מקום אחד או יותר שדרכו עובר המסלול אל היעד הסופי שצוין על ידי q. אפשר לציין כמה נקודות ציון באמצעות קו אנכי (|) כדי להפריד בין מקומות – לדוגמה, Berlin,Germany|Paris,France. אפשר להשתמש בכמה נקודות ציון שרוצים. נקודות הביניים יתווספו למסלול באותו סדר שבו הן מופיעות בכתובת ה-URL. כל נקודת ציון יכולה להיות כתובת או קואורדינטות של קו רוחב וקו אורך מופרדות בפסיקים. אפשר לכלול כתובות וקואורדינטות של קו רוחב וקו אורך באותה כוונה. מחרוזות צריכות להיות מוצפנות בפורמט URL, כך שנקודות ציון כמו Berlin,Germany|Paris,France צריכות להיות מומרות ל-Berlin%2CGermany%7CParis%2CFrance.

דוגמאות

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

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

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

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&avoid=tf");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

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

Uri mapIntentUri = Uri.parse("google.navigation:place=home");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

כדי להפעיל ניווט מפורט לשלוש הכתובות הבאות לפי הסדר, צריך להעביר את גן החיות טארונגה כיעד הסופי q, ואת Google Sydney ואת בית האופרה של סידני כנקודות עצירה:

1. Google Sydney

2. בית האופרה של סידני

3. גן החיות טארונגה, סידני, אוסטרליה

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7CSydney+Opera+House");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

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

Uri mapIntentUri = Uri.parse("google.navigation:q=Taronga+Zoo,+Sydney+Australia&waypoints=Google+Sydney%7C-33.856159,151.215256");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

שליחת תוכנית נסיעה ברכב חשמלי למפות Google

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

עצירות לטעינה, כוונות נסיעה:

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

‫Google משתמשת בשם תחנת הטעינה ובקווי הרוחב והאורך כדי למצוא מקום תואם של תחנת טעינה ולהציג נתונים מפורטים כמו סוגי מחברים, סכומים, מהירויות וזמינות בזמן אמת, אמצעי תשלום נתמכים ונקודות עניין (POI) של המארח. לדוגמה, הוראות נסיעה בחניונים חיצוניים בחלק האחרון של הניווט, שעות פתיחה, דירוגים. כדי לוודא שתחנות הטעינה תואמות לנתונים של Google, צריך להשתמש ב<brand name> ספציפי – לדוגמה, ChargePoint.

פרמטרים

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

יעד סופי

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

• ‫q: צריך להכיל את ערך קו הרוחב וקו האורך של תחנת הטעינה.
• ‫q_type: 1 מציין שהיעד הסופי הוא תחנת טעינה.
• ‫q_name: השם של היעד הסופי. חובה אם הערך של q_type הוא 1.
• ‫q_power_output_kw: מספר כפול של הספק המוצא של תחנת הטעינה בקילוואט. אופציונלי.

נקודות ציון

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

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

• ‫waypoints: רשימת נקודות ציון כמו שמתואר בכוונת הניווט המפורט. חייב להיות ערך של קו רוחב וקו אורך לנקודות ציון של תחנות טעינה.

• ‫waypoint_types: סוגים לכל נקודת ציון, שצוינו כמספר. ‫0 הוא כל עצירה (ערך ברירת מחדל) ו-1 היא תחנת הטעינה.

• ‫waypoint_names: שמות של נקודות ציון דרך. השדה הזה הוא חובה עבור עמדות טעינה.

• ‫waypoint_power_outputs_kw: מספרים כפולים של עוצמת תחנת הטעינה בקילוואט. עבור עמדות טעינה, אפשר לציין ערך אופציונלי של הספק בנקודת ביניים, שמשמש כחלופה אם לא נמצאה עמדה תואמת. חריץ ריק אומר שלא סופק ערך.

התנהגות שקשורה לחוויית המשתמש (UX)

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

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

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

• אם נמצאה התאמה, מערכת מפות Google משתמשת בנתונים של Google כדי להציג את עמדת הטעינה בממשק המשתמש ולספק המלצה לטעינה בעמדת הטעינה.

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

דוגמאות

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

ניווט ליעד סופי דרך כמה תחנות טעינה

הכוונה הבאה היא להגיע ליעד הסופי, Port Macquarie NSW, דרך שתי תחנות טעינה, ChargePoint ו-Evie.

היעדים לפי הסדר:

1. תחנת טעינה של ChargePoint (מיקום: ‎-32.9599188,151.6240806, הספק: ‎6.6kw)

2. תחנת טעינה של Evie (מיקום: ‎-31.9432539,152.4699808, הספק: ‎350kw)

3. Port Macquarie NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806%7C-31.9432539%2C152.4699808"
            + "&waypoint_types=1%7C1"
            + "&waypoint_names=ChargePoint+Charging+Station%7CEvie+Charging+Station"
            + "&waypoint_power_outputs_kw=6.6%7C350");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

הספק לא ידוע

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

היעדים לפי הסדר:

1. תחנת טעינה של ChargePoint (מיקום: ‎-32.9599188,151.6240806, הספק: לא ידוע)

2. Port Macquarie NSW

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=Port+Macquarie+NSW"
            + "&waypoints=-32.9599188%2C151.6240806"
            + "&waypoint_types=1"
            + "&waypoint_names=ChargePoint+Charging+Station");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

סימון יעד סופי כתחנת טעינה

כדי לסמן את היעד הסופי כתחנת טעינה, מציינים את הפרמטרים q_type, q_name ו-q_power_output_kw.

היעדים לפי הסדר:

1. גן החיות טארונגה, סידני, אוסטרליה

2. תחנת טעינה של ChargePoint (מיקום: ‎-32.9599188,151.6240806, מתח הטעינה הזמין: לא ידוע)

3. תחנת טעינה של Evie (מיקום: ‎-31.9432539,152.4699808, הספק: 350 קילוואט)

Uri mapIntentUri =
    Uri.parse(
        "google.navigation:q=-31.9432539,152.4699808&q_type=1&q_name=Evie+Charging+Station&q_power_output_kw=350"
            + "&waypoints=Taronga+Zoo%2C+Sydney+Australia%7C-32.9599188%2C151.6240806"
            + "&waypoint_types=0%7C1"
            + "&waypoint_names=%7CChargePoint+Charging+Station"
            + "&waypoint_power_outputs_kw=%7C");
Intent mapIntent = new Intent(Intent.ACTION_VIEW, mapIntentUri);
mapIntent.setPackage("com.google.android.apps.maps");
startActivity(mapIntent);

פעולות Intent

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