כלי לבחירת אנשי קשר לאינטרנט

ה-API של בוחר אנשי הקשר מאפשר למשתמשים לשתף בקלות אנשי קשר מרשימת אנשי הקשר שלהם.

Pete LePage

מהו ה-Contact Picker API?

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

המפרט של Contact Picker API זמין ב-Chrome מגרסה 80 ואילך, והוא API על פי דרישה שמאפשר למשתמשים לבחור רשומות מרשימת אנשי הקשר שלהם ולשתף עם אתר מידע מוגבל על הרשומות שנבחרו. היא מאפשרת למשתמשים לשתף רק את מה שהם רוצים, מתי שהם רוצים, ועוזרת למשתמשים ליצור קשר עם החברים והמשפחה שלהם ולהתחבר אליהם.

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

שימוש ב-Contact Picker API

ב-Contact Picker API נדרשת קריאה ל-method עם פרמטר אפשרויות שמציין את סוגי הפרטים ליצירת קשר הרצויים. שיטה שנייה מציינת איזה מידע המערכת הבסיסית מספקת.

זיהוי תכונות

כדי לבדוק אם Contact Picker API נתמך, משתמשים בפקודה:

const supported = ('contacts' in navigator && 'ContactsManager' in window);

בנוסף, ב-Android, הכלי לבחירת אנשי קשר דורש Android M ואילך.

פתיחת בורר אנשי הקשר

נקודת הכניסה ל-Contact Picker API היא navigator.contacts.select(). כשמתקבלת קריאה, הוא מחזיר הבטחה ומציג את בוחר אנשי הקשר, וכך מאפשר למשתמש לבחור את אנשי הקשר שהם רוצים לשתף עם האתר. אחרי שבוחרים מה לשתף ולוחצים על Done, ההבטחה מסתיימת עם מערך של אנשי קשר שהמשתמש בוחר.

בקריאה ל-select(), צריך לציין מערך של מאפיינים שרוצים שיוחזרו כפרמטר הראשון (הערכים המותרים הם כל אחד מהערכים 'name', 'email', 'tel', 'address' או 'icon'), ואפשר גם לבחור אם אפשר לבחור כמה אנשי קשר כפרמטר שני.

const props = ['name', 'email', 'tel', 'address', 'icon'];
const opts = {multiple: true};

try {
  const contacts = await navigator.contacts.select(props, opts);
  handleResults(contacts);
} catch (ex) {
  // Handle any errors here.
}

אפשר לקרוא ל-API של בוחר אנשי הקשר רק מהקשר גלישה מאובטח ברמה העליונה, ובדומה לממשקי API חזקים אחרים, נדרשת תנועת משתמש.

זיהוי נכסים זמינים

כדי לזהות אילו נכסים זמינים, צריך להתקשר אל navigator.contacts.getProperties(). היא מחזירה הבטחה שמסתיימת עם מערך של מחרוזות שמציינות אילו מאפיינים זמינים. לדוגמה: ['name', 'email', 'tel', 'address']. אפשר להעביר את הערכים האלה אל select().

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

טיפול בתוצאות

ה-Contact Picker API מחזיר מערך של אנשי קשר, וכל איש קשר כולל מערך של המאפיינים המבוקשים. אם לאיש הקשר אין נתונים בנכס המבוקש, או שהמשתמש בוחר להפסיק לשתף נכס מסוים, ה-API מחזיר מערך ריק. (בקטע בקרת משתמשים מתואר איך המשתמש בוחר מאפיינים).

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

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

אבטחה והרשאות

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

בקרת משתמשים

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

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

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

שקיפות

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

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

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

אין הרשאה קבועה

הגישה לאנשי הקשר היא על פי דרישה, ולא קבועה. בכל פעם שאתר מבקש גישה, הוא צריך להפעיל את navigator.contacts.select() באמצעות תנועת משתמש, והמשתמש צריך לבחור בנפרד את אנשי הקשר שהוא רוצה לשתף עם האתר.

משוב

צוות Chrome ישמח לשמוע על החוויה שלכם עם ממשק ה-API של בורר אנשי הקשר.

נתקלתם בבעיה בהטמעה?

האם מצאת באג בהטמעה של Chrome? או שההטמעה שונה מהמפרט?

  • אפשר לדווח על באג בכתובת https://new.crbug.com. חשוב לכלול כמה שיותר פרטים, לספק הוראות פשוטות לשחזור הבאג ולהגדיר את הרכיבים ל-Blink>Contacts. גליץ' הוא כלי מעולה לשיתוף של שחזורים של בעיות בקלות ובמהירות.

מתכנן להשתמש ב-API?

האם בכוונתך להשתמש ב-Contact Picker API? התמיכה הציבורית עוזרת לצוות של Chrome לתעדף תכונות, ומראה לספקי דפדפנים אחרים עד כמה קריטי לתמוך בהם.

קישורים שימושיים

תודה

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

נ.ב: השמות בבוחר אנשי הקשר שלי הם תווים מאליס בארץ הפלאות.