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

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

Pete LePage

מה זה Contact Picker API?

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

מפרט Contact Picker 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 בהתאם לעקרונות המרכזיים שמוגדרים במאמר שליטה בגישה לתכונות חזקות של פלטפורמת אינטרנט, כולל שליטה על ידי המשתמש, שקיפות וארגונומיה. אסביר על כל אחת מהן.

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

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

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

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

שקיפות

כדי להבהיר אילו פרטים ליצירת קשר משותפים, בבורר תמיד מוצגים השם והסמל של איש הקשר, וגם כל הנכסים שהאתר ביקש. לדוגמה, אם אתר מבקש את 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 על הקוד שגנבתי ועיבדת מחדש לצורך הדגמה.

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