انتخابگر مخاطب برای وب، انتخابگر مخاطب برای وب

Contact Picker API یک راه آسان برای کاربران فراهم می کند تا مخاطبین را از لیست مخاطبین خود به اشتراک بگذارند.

پیت لی پیج

Contact Picker API چیست؟

دسترسی به مخاطبین کاربر در دستگاه تلفن همراه یکی از ویژگی‌های برنامه‌های iOS/Android از زمان (تقریباً) زمان بوده است. این یکی از متداول‌ترین درخواست‌های ویژگی است که از توسعه‌دهندگان وب می‌شنوم و اغلب دلیل اصلی ساخت برنامه iOS/Android است.

مشخصات Contact Picker API که از Chrome 80 در Android M یا جدیدتر موجود است، یک API درخواستی است که به کاربران امکان می‌دهد ورودی‌ها را از لیست مخاطبین خود انتخاب کنند و جزئیات محدود ورودی‌های انتخاب‌شده را با یک وب‌سایت به اشتراک بگذارند. این به کاربران اجازه می‌دهد فقط آنچه را که می‌خواهند به اشتراک بگذارند، و دسترسی کاربران و ارتباط با دوستان و خانواده‌شان را آسان‌تر می‌کند.

به عنوان مثال، یک سرویس گیرنده ایمیل مبتنی بر وب می تواند از Contact Picker API برای انتخاب گیرنده(های) ایمیل استفاده کند. یک برنامه Voice-over-IP می تواند به دنبال شماره تلفنی باشد که باید با آن تماس بگیرد. یا یک شبکه اجتماعی می تواند به کاربر کمک کند تا بفهمد کدام دوستان قبلاً به آن ملحق شده اند.

با استفاده از Contact Picker API

Contact Picker API به فراخوانی روش با پارامتر گزینه نیاز دارد که انواع اطلاعات تماس مورد نظر شما را مشخص می کند. روش دوم به شما می گوید که سیستم زیربنایی چه اطلاعاتی را ارائه خواهد کرد.

تشخیص ویژگی

برای بررسی اینکه آیا Contact Picker API پشتیبانی می‌شود، از این موارد استفاده کنید:

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

علاوه بر این، در Android، Contact Picker به 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() ارسال کنید.

به یاد داشته باشید، ویژگی ها همیشه در دسترس نیستند و ممکن است ویژگی های جدیدی اضافه شوند. در آینده، سایر پلتفرم‌ها و منابع تماس ممکن است ویژگی‌هایی را که به اشتراک گذاشته می‌شوند محدود کنند.

رسیدگی به نتایج

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 ، یک مخاطب انتخاب شده است.
اسکرین شات انتخاب کننده برای سایتی که فقط شماره تلفن را درخواست می کند.
انتخاب کننده، سایت درخواست کننده فقط tel ، یک مخاطب انتخاب شده است.
عکس صفحه انتخابگر زمانی که یک مخاطب به مدت طولانی فشار داده می شود.
نتیجه فشار طولانی روی یک مخاطب.

با فشار طولانی روی یک مخاطب، تمام اطلاعاتی که در صورت انتخاب مخاطب به اشتراک گذاشته می شود، نشان داده می شود. (تصویر تماس گربه Cheshire را ببینید.)

بدون تداوم مجوز

دسترسی به مخاطبین بر حسب تقاضا است و ادامه ندارد. هر بار که سایتی می‌خواهد دسترسی داشته باشد، باید با اشاره کاربر navigator.contacts.select() را فراخوانی کند و کاربر باید به‌صورت جداگانه مخاطبینی را که می‌خواهد با سایت به اشتراک بگذارد انتخاب کند.

بازخورد

تیم Chrome می‌خواهد درباره تجربیات شما با Contact Picker API بشنود.

مشکل در اجرا؟

آیا اشکالی در پیاده سازی کروم پیدا کردید؟ یا اجرا با مشخصات متفاوت است؟

  • یک اشکال را در https://new.crbug.com ثبت کنید. اطمینان حاصل کنید که تا آنجا که می توانید جزئیات را وارد کنید، دستورالعمل های ساده ای را برای بازتولید اشکال ارائه دهید و Components را روی Blink>Contacts تنظیم کنید. Glitch برای به اشتراک گذاری بازتولید سریع و آسان مشکل عالی عمل می کند.

آیا قصد استفاده از API را دارید؟

آیا قصد دارید از Contact Picker API استفاده کنید؟ پشتیبانی عمومی شما به تیم Chrome کمک می‌کند تا ویژگی‌ها را اولویت‌بندی کند، و به سایر فروشندگان مرورگر نشان می‌دهد که چقدر حمایت از آنها ضروری است.

  • نحوه استفاده از آن را در موضوع WICG Discourse به اشتراک بگذارید.
  • با استفاده از هشتگ #ContactPicker یک توییت به ChromiumDev@ ارسال کنید و به ما اطلاع دهید کجا و چگونه از آن استفاده می‌کنید.

لینک های مفید

با تشکر

فریاد بزرگ و تشکر از Finnur Thorarinsson و Rayan Kanso که در حال پیاده سازی این ویژگی هستند و Peter Beverloo که من بی شرمانه کد او را دزدیدم و برای نسخه ی نمایشی آن را بازسازی کردم.

PS: نام های موجود در انتخابگر مخاطب من شخصیت هایی از آلیس در سرزمین عجایب هستند.

،

Contact Picker API یک راه آسان برای کاربران فراهم می کند تا مخاطبین را از لیست مخاطبین خود به اشتراک بگذارند.

پیت لی پیج

Contact Picker API چیست؟

دسترسی به مخاطبین کاربر در دستگاه تلفن همراه یکی از ویژگی‌های برنامه‌های iOS/Android از زمان (تقریباً) زمان بوده است. این یکی از متداول‌ترین درخواست‌های ویژگی است که از توسعه‌دهندگان وب می‌شنوم و اغلب دلیل اصلی ساخت برنامه iOS/Android است.

مشخصات Contact Picker API که از Chrome 80 در Android M یا جدیدتر موجود است، یک API درخواستی است که به کاربران امکان می‌دهد ورودی‌ها را از لیست مخاطبین خود انتخاب کنند و جزئیات محدود ورودی‌های انتخاب‌شده را با یک وب‌سایت به اشتراک بگذارند. این به کاربران اجازه می‌دهد فقط آنچه را که می‌خواهند به اشتراک بگذارند، و دسترسی کاربران و ارتباط با دوستان و خانواده‌شان را آسان‌تر می‌کند.

به عنوان مثال، یک سرویس گیرنده ایمیل مبتنی بر وب می تواند از Contact Picker API برای انتخاب گیرنده(های) ایمیل استفاده کند. یک برنامه Voice-over-IP می تواند به دنبال شماره تلفنی باشد که باید با آن تماس بگیرد. یا یک شبکه اجتماعی می تواند به کاربر کمک کند تا بفهمد کدام دوستان قبلاً به آن ملحق شده اند.

با استفاده از Contact Picker API

Contact Picker API به فراخوانی روش با پارامتر گزینه نیاز دارد که انواع اطلاعات تماس مورد نظر شما را مشخص می کند. روش دوم به شما می گوید که سیستم زیربنایی چه اطلاعاتی را ارائه خواهد کرد.

تشخیص ویژگی

برای بررسی اینکه آیا Contact Picker API پشتیبانی می‌شود، از این موارد استفاده کنید:

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

علاوه بر این، در Android، Contact Picker به 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() ارسال کنید.

به یاد داشته باشید، ویژگی ها همیشه در دسترس نیستند و ممکن است ویژگی های جدیدی اضافه شوند. در آینده، سایر پلتفرم‌ها و منابع تماس ممکن است ویژگی‌هایی را که به اشتراک گذاشته می‌شوند محدود کنند.

رسیدگی به نتایج

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 ، یک مخاطب انتخاب شده است.
اسکرین شات انتخاب کننده برای سایتی که فقط شماره تلفن را درخواست می کند.
انتخاب کننده، سایت درخواست کننده فقط tel ، یک مخاطب انتخاب شده است.
عکس صفحه انتخابگر زمانی که یک مخاطب به مدت طولانی فشار داده می شود.
نتیجه فشار طولانی روی یک مخاطب.

با فشار طولانی روی یک مخاطب، تمام اطلاعاتی که در صورت انتخاب مخاطب به اشتراک گذاشته می شود، نشان داده می شود. (تصویر تماس گربه Cheshire را ببینید.)

بدون تداوم مجوز

دسترسی به مخاطبین بر حسب تقاضا است و ادامه ندارد. هر بار که سایتی می‌خواهد دسترسی داشته باشد، باید با اشاره کاربر navigator.contacts.select() را فراخوانی کند و کاربر باید به‌صورت جداگانه مخاطبینی را که می‌خواهد با سایت به اشتراک بگذارد انتخاب کند.

بازخورد

تیم Chrome می‌خواهد درباره تجربیات شما با Contact Picker API بشنود.

مشکل در اجرا؟

آیا اشکالی در پیاده سازی کروم پیدا کردید؟ یا اجرا با مشخصات متفاوت است؟

  • یک اشکال را در https://new.crbug.com ثبت کنید. اطمینان حاصل کنید که تا آنجا که می توانید جزئیات را وارد کنید، دستورالعمل های ساده ای را برای بازتولید اشکال ارائه دهید و Components را روی Blink>Contacts تنظیم کنید. Glitch برای به اشتراک گذاری بازتولید سریع و آسان مشکل عالی عمل می کند.

آیا قصد استفاده از API را دارید؟

آیا قصد دارید از Contact Picker API استفاده کنید؟ پشتیبانی عمومی شما به تیم Chrome کمک می‌کند تا ویژگی‌ها را اولویت‌بندی کند، و به سایر فروشندگان مرورگر نشان می‌دهد که چقدر حمایت از آنها ضروری است.

  • نحوه استفاده از آن را در موضوع WICG Discourse به اشتراک بگذارید.
  • با استفاده از هشتگ #ContactPicker یک توییت به ChromiumDev@ ارسال کنید و به ما اطلاع دهید کجا و چگونه از آن استفاده می‌کنید.

لینک های مفید

با تشکر

فریاد بزرگ و تشکر از Finnur Thorarinsson و Rayan Kanso که در حال پیاده سازی این ویژگی هستند و Peter Beverloo که من بی شرمانه کد او را دزدیدم و برای نسخه ی نمایشی آن را بازسازی کردم.

PS: نام های موجود در انتخابگر مخاطب من شخصیت هایی از آلیس در سرزمین عجایب هستند.