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

Contact Picker API מספק למשתמשים דרך קלה לשתף אנשי קשר מרשימת אנשי הקשר שלהם.

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

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

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

שימוש ב-Contact Picker API

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

זיהוי תכונות

כדי לבדוק אם יש תמיכה ב-Contact Picker API:

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

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

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

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

כשקוראים ל-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.
}

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

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

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

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

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

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

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

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

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

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

שליטת משתמשים

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

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

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

שקיפות

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

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

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

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

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

משוב

חברי צוות Chrome רוצים לשמוע על החוויה שלכם בשימוש ב-Contact Picker API.

בעיה בהטמעה?

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

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

אתם מתכננים להשתמש ב-API?

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

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

תודה

תודה רבה ל-Finnur Thorarinsson ול-Rayan Kanso על הטמעת התכונה, ותודה רבה ל-Peter Beverloo על הקוד שגנבתי ועיבדת מחדש לצורך הדגמה.

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