סכימה של כתובת URL של מפות Google ל-iOS

במכשירים עם iOS מגרסה 9 ואילך, אפשר להשתמש בקישורים אוניברסליים כדי להפעיל את מפות Google כשיש לכם כתובת URL של מפות Google.

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

אין צורך במפתח Google API כדי להשתמש בסכמת כתובות URL של מפות Google.

קישורים אוניברסליים ומפות Google

מפות Google ל-iOS תומך בקישורים אוניברסליים במכשירים עם מערכת ההפעלה iOS 9 ומעלה.

אם כתובת ה-URL תואמת לביטוי הרגולרי הבא, ובמכשיר פועלת מערכת iOS בגרסה 9 ואילך, מומלץ להשתמש ישירות בשיטת openURL: .

(http(s?)://)?
((maps\.google\.{TLD}/)|
 ((www\.)?google\.{TLD}/maps/)|
 (goo.gl/maps/))
.*

לדוגמה,

UIApplication.shared.openURL(URL(string:"https://www.google.com/maps/@42.585444,13.007813,6z")!)

[[UIApplication sharedApplication] openURL:
   [NSURL URLWithString:@"https://www.google.com/maps/@42.585444,13.007813,6z"]];

סקירה

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

• comgooglemaps:// ו-comgooglemaps-x-callback:// – הסכימות האלה מאפשרות להשיק את אפליקציית מפות Google ל-iOS ולבצע אחת מכמה פעולות:

  • הצגת מפה במיקום ספציפי וברמת זום.
  • מחפשים מיקומים או מקומות ומציגים אותם במפה.
  • מבקשים מסלול ממיקום אחד למיקום אחר. אפשר להחזיר מסלולים בארבעה אמצעי תחבורה: נהיגה, הליכה, רכיבה על אופניים ותחבורה ציבורית.
  • מוסיפים ניווט לאפליקציה.
  • באמצעות iOS 8, צריך לבצע קריאה חוזרת (callback) כשהאפליקציה תושלם באמצעות comgooglemaps-x-callback://. בדרך כלל, קריאות חוזרות (callback) משמשות כדי להחזיר משתמש לאפליקציה שפותחה במקור את מפות Google ל-iOS. שימו לב שב-iOS 9, המערכת מספקת באופן אוטומטי קישור 'חזרה אל' בפינה השמאלית של שורת הסטטוס.

• comgooglemapsurl:// – התוכנית הזו מאפשרת להשיק את אפליקציית מפות Google ל-iOS באמצעות כתובת URL שנגזרת מהאתר של מפות Google למחשב. המשמעות היא שתוכלו לספק למשתמשים חוויה מובנית בנייד במקום לטעון רק את האתר של מפות Google.

  • כתובת ה-URL המקורית יכולה להיות של maps.google.com, של google.com/maps, או של כל דומיין מדינה תקין ברמה העליונה במקום com. אפשר גם להעביר כתובות URL להפניה אוטומטית של goo.gl/maps.
  • אפשר ליצור קריאה חוזרת באמצעות הפרמטרים x-source ו-x-success באמצעות סכימת כתובת ה-URL comgooglemapsurl://.

השקת אפליקציית מפות Google ל-iOS וביצוע פונקציה ספציפית

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

comgooglemaps://?parameters

או:

comgooglemaps-x-callback://?parameters

הפרמטרים מתוארים בפירוט בהמשך המסמך.

בדיקת הזמינות של אפליקציית מפות Google במכשיר

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

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps://")!)

[[UIApplication sharedApplication] canOpenURL:
    [NSURL URLWithString:@"comgooglemaps://"]];

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

if (UIApplication.shared.canOpenURL(URL(string:"comgooglemaps://")!)) {
  UIApplication.shared.openURL(URL(string:
    "comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic")!)
} else {
  print("Can't use comgooglemaps://");
}

if ([[UIApplication sharedApplication] canOpenURL:
     [NSURL URLWithString:@"comgooglemaps://"]]) {
  [[UIApplication sharedApplication] openURL:
   [NSURL URLWithString:@"comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic"]];
} else {
  NSLog(@"Can't use comgooglemaps://");
}

הצגת מפה

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

פרמטרים

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

• center: זוהי נקודת המרכז של אזור התצוגה במפה. בפורמט של מחרוזת latitude,longitude שמופרדת בפסיקים.
• mapmode: מגדיר את סוג המפה שמוצגת. אפשר להגדיר אותו ל: standard או streetview. אם לא מציינים זאת, ייעשה שימוש בהגדרות האפליקציה הנוכחיות.
• views: הפעלה או השבתה של תצוגות ספציפיות. אפשר להגדיר את האפשרויות הבאות: satellite, traffic או transit. ניתן להגדיר מספר ערכים באמצעות מפריד פסיקים. אם מציינים את הפרמטר ללא ערך, הוא יגרום למחיקת כל התצוגות.
• zoom: מציין את רמת המרחק מהתצוגה של המפה.

בכתובת ה-URL בדוגמה הזו מוצגת המפה במרכז ניו יורק בזום 14, כאשר תצוגת התנועה מוצגת ב:

comgooglemaps://?center=40.765819,-73.975866&zoom=14&views=traffic

דוגמאות נוספות:

comgooglemaps://?center=37.788463,-122.392545&zoom=12

comgooglemaps://?center=46.414382,10.013988&mapmode=streetview

חיפוש

השתמשו בסכימה הזו כדי להציג שאילתות חיפוש במיקום תצוגה ספציפי.

פרמטרים

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

• q: מחרוזת השאילתה שמשויכת לחיפוש.

כתובת ה-URL לדוגמה הזו לחיפוש "פיצה" סביב המיקום שצוין:

comgooglemaps://?q=Pizza&center=37.759748,-122.427135

דוגמאות נוספות:

comgooglemaps://?q=Steamers+Lane+Santa+Cruz,+CA&center=37.782652,-122.410126&views=satellite,traffic&zoom=15

comgooglemaps://?q=Google+Japan,+Minato,+Tokyo,+Japan&center=35.660888,139.73073&zoom=15&views=transit

הצגת מסלול

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

פרמטרים

• saddr: מגדיר את נקודת ההתחלה לחיפושי מסלול. אפשר להזין קו רוחב,קו אורך או כתובת בפורמט של שאילתה. אם זו מחרוזת שאילתה שמחזירה יותר מתוצאה אחת, התוצאה הראשונה תיבחר. אם משאירים את הערך ריק, המערכת תשתמש במיקום הנוכחי של המשתמש.
• daddr: מגדיר את נקודת הסיום לחיפושי מסלול. הפורמט וההתנהגות שלו זהים לאלה של saddr.
• directionsmode: אמצעי תחבורה. אפשר להגדיר אותו ל: driving, transit, bicycling או walking.

בכתובת ה-URL לדוגמה מוצגים מסלולי תחבורה ציבורית בין Google NYC לנמל התעופה JFK:

comgooglemaps://?saddr=Google+Inc,+8th+Avenue,+New+York,+NY&daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York&directionsmode=transit

דוגמאות נוספות:

comgooglemaps://?saddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA+94043&daddr=Google+Inc,+345+Spear+Street,+San+Francisco,+CA&center=37.422185,-122.083898&zoom=10

comgooglemaps://?saddr=2025+Garcia+Ave,+Mountain+View,+CA,+USA&daddr=Google,+1600+Amphitheatre+Parkway,+Mountain+View,+CA,+United+States&center=37.423725,-122.0877&directionsmode=walking&zoom=17

ציון כתובת URL לקריאה חוזרת (callback)

כדי לציין כתובת URL לקריאה חוזרת, צריך להשתמש בסכמת כתובת ה-URL comgooglemaps-x-callback://. הסכימה הזו פועלת בהתאם למפרט x-callback-url. באמצעות סכימה זו, כשתתקשרו לאפליקציית מפות Google ל-iOS, האפליקציה תציג לחצן בחלק העליון של המסך. הקשה על הלחצן הזה תיצור קריאה חוזרת לכתובת ה-URL שציינתם.

בקשות אל comgooglemaps-x-callback:// חייבות להיות בפורמט הבא:

comgooglemaps-x-callback://?parameters

פרמטרים

סכימת כתובת ה-URL x-callback מקבלת את אותם פרמטרים כמו סכימת כתובת ה-URL comgooglemaps://, עם הפרמטרים הנוספים הבאים. שני הפרמטרים נדרשים.

• x-source – השם של האפליקציה ששולחת את בקשת ה-x-callback. עדיף להשתמש בשמות קצרים.
• x-success — כתובת ה-URL לקריאה בסיום הפעולה. לעיתים קרובות זו תהיה סכימה של כתובת URL לאפליקציה שלכם, שתאפשר למשתמשים לחזור לאפליקציה המקורית.

שימו לב שהאפליקציה תצטרך לרשום סכימה משלה של כתובת URL כדי שהיא תוכל להגיב לכתובת ה-URL לקריאה חוזרת.

1. צריך לוודא שבאפליקציה רשמת סכימת כתובת URL שיכולה להגיב לבקשת הקריאה החוזרת.
2. צריך להעביר את התווית של לחצן הקריאה החוזרת בפרמטר x-source.
3. מעבירים את כתובת ה-URL לקריאה חוזרת (callback) בפרמטר x-success.

הדוגמה הבאה תפעיל את אפליקציית מפות Google ל-iOS ותציג מפה במרכז ניו יורק. האפליקציה תציג גם לחצן עם התווית SourceApp. כשלוחצים על הלחצן SourceApp, אפליקציית מפות Google ל-iOS תנפיק קריאה חוזרת לסכימה פיקטיבית של כתובת URL, sourceapp://?resume=true.

comgooglemaps-x-callback://?center=40.765819,-73.975866&zoom=14
   &x-success=sourceapp://?resume=true
   &x-source=SourceApp

בדומה לסכימת כתובת ה-URL comgooglemaps://, קודם צריך לוודא שאפליקציית מפות Google ל-iOS זמינה במכשיר ותומכת בסכמת כתובת ה-URL x-callback. האפליקציה שלכם יכולה לבדוק שסכימת כתובת ה-URL זמינה באמצעות הקוד הבא:

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps-x-callback://")!)

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemaps-x-callback://"]];

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

comgooglemaps-x-callback://?q=dessert&center=37.759748,-122.427135
   &x-success=sourceapp://?resume=true
   &x-source=Nom+Nom

הניווט מתווסף לאפליקציה

השקת האפליקציה מפות Google ל-iOS עם בקשה למסלול היא דרך קלה לתת למשתמשים גישה לניווט עם מסלול מפורט מהאפליקציה. אפשר להשתמש בסכימות של כתובות URL comgooglemaps:// או comgooglemaps-x-callback://.

קטע הקוד הזה מראה איך להשתמש בסכימה comgooglemaps-x-callback:// כדי לבקש מסלול הגעה ולחזור לאפליקציה כשהמשתמש מוכן. הקוד יבצע את הפעולות הבאות:

1. צריך לוודא שסכימת כתובת ה-URL comgooglemaps-x-callback:// זמינה.
2. צריך להפעיל את אפליקציית מפות Google ל-iOS ולבקש מסלול הגעה לנמל התעופה JFK בעיר ניו יורק. כדי לבקש מסלול מהמיקום הנוכחי של המשתמש, צריך להשאיר את כתובת ההתחלה ריקה.
3. יש להוסיף לחצן עם התווית 'AirApp' לאפליקציית מפות Google ל-iOS. תווית הלחצן מוגדרת על ידי הפרמטר x-source.
4. קוראים לסכימה של כתובת ה-URL הפיקטיבית, sourceapp://, כשמשתמשים לוחצים על לחצן 'הקודם'.

let testURL = URL(string: "comgooglemaps-x-callback://")!
if UIApplication.shared.canOpenURL(testURL) {
  let directionsRequest = "comgooglemaps-x-callback://" +
    "?daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York" +
    "&x-success=sourceapp://?resume=true&x-source=AirApp"

  let directionsURL = URL(string: directionsRequest)!
  UIApplication.shared.openURL(directionsURL)
} else {
  NSLog("Can't use comgooglemaps-x-callback:// on this device.")
}

NSURL *testURL = [NSURL URLWithString:@"comgooglemaps-x-callback://"];
if ([[UIApplication sharedApplication] canOpenURL:testURL]) {
  NSString *directionsRequest = @"comgooglemaps-x-callback://" +
      @"?daddr=John+F.+Kennedy+International+Airport,+Van+Wyck+Expressway,+Jamaica,+New+York" +
      @"&x-success=sourceapp://?resume=true&x-source=AirApp";
  NSURL *directionsURL = [NSURL URLWithString:directionsRequest];
  [[UIApplication sharedApplication] openURL:directionsURL];
} else {
  NSLog(@"Can't use comgooglemaps-x-callback:// on this device.");
}

השקת האפליקציה מפות Google ל-iOS מכתובת URL של מפות Google למחשב

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

1. מחליפים את הסכימה http:// או https:// ב-comgooglemapsurl://.
2. אם רוצים להשתמש בקריאה חוזרת (callback), צריך לכלול את הפרמטרים x-source ו-x-success. הסכימה הזו פועלת בהתאם למפרט x-callback-url.

פורמטים נתמכים של כתובות URL במפות Google

הסכימה comgooglemapsurl:// תומכת בכתובות URL שתואמות לביטוי הרגולרי הזה, כאשר {TLD} מתייחס לכל דומיין מדינה תקין ברמה העליונה. נוספו מעברי שורה לשם הבהרה:

(http(s?)://)?
((maps\.google\.{TLD}/)|
 ((www\.)?google\.{TLD}/maps/)|
 (goo.gl/maps/))
.*

בדיקת הזמינות של אפליקציית מפות Google

קודם כל, צריך לוודא שאפליקציית מפות Google ל-iOS זמינה במכשיר ותומכת בסכמה של כתובות ה-URL:

UIApplication.shared.canOpenURL(URL(string:"comgooglemaps-x-callback://")!)

[[UIApplication sharedApplication] canOpenURL:
   [NSURL URLWithString:@"comgooglemapsurl://"]];

דוגמאות

דוגמה לכתובת URL כללית של מפות Google:

כתובת ה-URL המקורית של מפות Google:

https://www.google.com/maps/preview/@42.585444,13.007813,6z

באמצעות הסכימה של כתובת ה-URL:

comgooglemapsurl://www.google.com/maps/preview/@42.585444,13.007813,6z

דוגמה לכתובת URL כללית של מפות Google:

כתובת ה-URL המקורית של מפות Google:

https://maps.google.com/?q=@37.3161,-122.1836

באמצעות הסכימה של כתובת ה-URL:

comgooglemapsurl://maps.google.com/?q=@37.3161,-122.1836

דוגמה לבקשת מסלול למגדל טוקיו באמצעות x-callback:

כתובת ה-URL המקורית של מפות Google:

http://maps.google.com/maps?f=d&daddr=Tokyo+Tower,+Tokyo,+Japan&sll=35.6586,139.7454&sspn=0.2,0.1&nav=1

הדוגמה הבאה תפעיל את אפליקציית מפות Google ל-iOS ותציג מפה עם מסלול למגדל טוקיו, כפי שצוין בכתובת ה-URL המקורית של מפות Google (למעלה). האפליקציה תציג גם לחצן עם התווית SourceApp. כשלוחצים על הלחצן SourceApp, אפליקציית מפות Google ל-iOS תנפיק קריאה חוזרת לסכימה פיקטיבית של כתובת URL, sourceapp://?resume=true.

comgooglemapsurl://maps.google.com/maps?f=d&daddr=Tokyo+Tower,+Tokyo,+Japan&sll=35.6586,139.7454&sspn=0.2,0.1&nav=1
    &x-source=SourceApp
    &x-success=sourceapp://?resume=true