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

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

סקירה כללית

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

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

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

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

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

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

• חבילה. התקשרות אל setPackage("com.google.android.apps.maps") מוודאת שאפליקציית מפות Google ל-Android מטפלת ב-Intent. אם החבילה לא מוגדרת, המערכת קובעת אילו אפליקציות יכולות לטפל ב-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);

חפש מיקום

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

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

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

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

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

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

פרמטרים

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

יעד סופי

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

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

נקודות ציון דרך

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

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

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

• ‫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

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