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

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

Pete LePage

מהו ה-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. הקפידו לכלול כמה שיותר פרטים, לשלוח הוראות פשוטות לשחזור הבאג ולהגדיר את הרכיבים ל-Blink>Contacts. Glitch הוא כלי מצוין לשיתוף הדגמות מהירות וקלות של הבעיה.

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

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

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

תודה

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

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