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

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

Pete LePage

מהו ה-Contact Picker API?

שימוש ב-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, בבורר יוצגו רק השם ומספרי הטלפון.

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

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

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

משוב

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

בעיה בהטמעה?

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

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

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

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

• תוכלו לשתף את האופן שבו אתם מתכננים להשתמש בו בשרשור השיחה של WICG.
• אפשר לשלוח ציוץ אל @ChromiumDev עם ההאשטאג #ContactPicker ולספר לנו איפה ואיך אתם משתמשים בו.

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

• הסבר ציבורי
• מפרט של בורר אנשי הקשר
• הדגמה של Contact Picker API ומקור הדגמה של Contact Picker API
• באג במעקב
• הרשומה ב-ChromeStatus.com
• רכיב Blink: Blink>Contacts

תודה

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

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