أداة اختيار جهات الاتصال على الويب

توفّر واجهة برمجة التطبيقات Contact Picker API طريقة سهلة للمستخدمين لمشاركة جهات الاتصال من قائمة جهات الاتصال.

إنّ الوصول إلى جهات اتصال المستخدم على جهاز جوّال كان ميزة في تطبيقات iOS/Android منذ بدء استخدام هذه الأجهزة (تقريبًا). إنّ هذه الميزة هي من أكثر الميزات المطلوبة التي نتلقّاها من مطوّري الويب، وغالبًا ما تكون السبب الرئيسي لبناء تطبيق لنظامَي التشغيل iOS وAndroid.

تتوفر مواصفات واجهة برمجة تطبيقات أداة اختيار جهات الاتصال في Chrome 80 على الإصدار Android M أو الإصدارات الأحدث، وهي عبارة عن واجهة برمجة تطبيقات عند الطلب تسمح للمستخدمين باختيار إدخالات من قائمة جهات الاتصال ومشاركة تفاصيل محدودة عن الإدخالات المحددة مع موقع إلكتروني. وهي تتيح للمستخدمين مشاركة ما يريدونه فقط، وقتما يريدون، وتسهّل على المستخدمين التواصل مع أصدقائهم وعائلاتهم والتواصل معهم.

على سبيل المثال، يمكن لبرنامج بريد إلكتروني مستنِد إلى الويب استخدام واجهة برمجة تطبيقات "أداة اختيار جهات الاتصال" لتحديد مستلمي الرسالة الإلكترونية. يمكن لتطبيق الاتصالات الصوتية عبر بروتوكول الإنترنت البحث عن رقم الهاتف المطلوب الاتصال به. أو يمكن أن تساعد شبكة اجتماعية المستخدم في اكتشاف الأصدقاء الذين سبق لهم الانضمام.

استخدام واجهة برمجة تطبيقات منتقي جهات الاتصال

تتطلّب واجهة برمجة التطبيقات Contact Picker API طلب إجراء مع مَعلمة خيارات تحدد أنواع معلومات الاتصال التي تريدها. وتوضّح لك الطريقة الثانية المعلومات التي سيقدّمها النظام الأساسي.

رصد الميزات

للتحقّق من توفّر واجهة برمجة التطبيقات 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 إلا من سياق تصفّح آمن من المستوى الأعلى، ومثل واجهات برمجة التطبيقات القوية الأخرى، تتطلّب إيماءة المستخدم.

جارٍ رصد المواقع المتاحة

لاكتشاف السمات المتوفرة، يمكنك طلب navigator.contacts.getProperties(). وتعرض وعدًا يتم حله باستخدام مصفوفة من السلاسل تشير إلى الخصائص المتاحة. على سبيل المثال: ['name', 'email', 'tel', 'address']. يمكنك تمرير هذه القيم إلى select().

يُرجى العِلم أنّ المواقع لا تكون متاحة دائمًا، وقد تتم إضافة مواقع جديدة. في المستقبل، قد تحدّ الأنظمة الأساسية الأخرى ومصادر الاتّصال الأخرى من المواقع التي تتم مشاركتها.

التعامل مع النتائج

تعرض واجهة برمجة التطبيقات Contact Picker 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 معرفة تجاربك مع واجهة برمجة التطبيقات لتطبيق "أداة اختيار جهات الاتصال".

هل هناك مشكلة في التنفيذ؟

هل رصدت خطأ في عملية تنفيذ Chrome؟ أم أن التنفيذ يختلف عن المواصفات؟

  • يمكنك الإبلاغ عن الخطأ على https://new.crbug.com. وتأكّد من تضمين أكبر قدر ممكن من التفاصيل، وقدِّم تعليمات بسيطة لإعادة إنتاج الخطأ، واضبط المكوّنات على Blink>Contacts. تعمل ميزة Glitch بشكل رائع لمشاركة عمليات إعادة إنتاج المشاكل بسرعة وسهولة.

هل تخطّط لاستخدام واجهة برمجة التطبيقات؟

هل تخطّط لاستخدام واجهة برمجة التطبيقات Contact Picker API؟ يساعد دعمك العلني فريق Chrome في تحديد الميزات ذات الأولوية، ويُظهر لموفّري المتصفّحات الآخرين مدى أهمية توفير هذه الميزات.

  • شارِك الطريقة التي تنوي بها استخدام هذا التقرير في سلسلة محادثات WICG Discourse.
  • أرسِل تغريدة إلى ‎@ChromiumDev باستخدام الهاشتاغ #ContactPicker و أخبِرنا بالمكان الذي تستخدم فيه الميزة وطريقة استخدامك لها.

روابط مفيدة

شكرًا

أريد أن أشكر كلًا من "فينور ثورارينسون" و"ريان كانسو" اللذَين ينفذان الميزة و"بيتر بيفيرلو" الذي سرقت الرمز البرمجي الخاص به بدون خجل وأعددتُه من أجل العرض التقديمي.

ملاحظة: الأسماء في أداة اختيار جهات الاتصال هي شخصيات من رواية "أليس في بلاد العجائب".