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

توفر واجهة برمجة تطبيقات "أداة اختيار جهات الاتصال" للمستخدمين طريقة سهلة لمشاركة جهات الاتصال من قائمة جهات الاتصال.

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

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

على سبيل المثال، يمكن أن يستخدم برنامج بريد إلكتروني على الويب واجهة برمجة التطبيقات Contact Picker API لتحديد مستلمي الرسالة الإلكترونية. يمكن لتطبيق Voice-over-IP البحث عن رقم الهاتف المطلوب الاتصال به. أو يمكن أن تساعد شبكة اجتماعية المستخدم في اكتشاف الأصدقاء الذين سبق لهم الانضمام.

استخدام واجهة برمجة التطبيقات Contact Picker API

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

رصد الميزات

للتحقّق من توفّر واجهة برمجة التطبيقات Contact Picker API، استخدِم:

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

بالإضافة إلى ذلك، تتطلب "أداة اختيار جهات الاتصال" على نظام التشغيل Android M من Android أو إصدار أحدث.

فتح "أداة اختيار جهات الاتصال"

نقطة الدخول إلى 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، تم اختيار جهة اتصال واحدة.
لقطة شاشة لأداة الاختيار للموقع الإلكتروني الذي يطلب أرقام الهاتف فقط.
Picker، الموقع الإلكتروني يطلب tel فقط، تم اختيار جهة اتصال واحدة.
لقطة شاشة لأداة الاختيار عند الضغط مع الاستمرار على جهة اتصال
نتيجة الضغط مع الاستمرار على جهة اتصال.

يؤدي الضغط المطوّل على جهة الاتصال إلى إظهار جميع المعلومات التي ستتم مشاركتها إذا تم تحديد جهة الاتصال. (اطّلِع على صورة جهة الاتصال "قطة Cheshire").

عدم تثبيت الأذونات

يكون الوصول إلى جهات الاتصال عند الطلب، ولم يتم الاحتفاظ به. في كل مرة يريد فيها أحد المواقع الإلكترونية الوصول إلى جهات الاتصال، يجب أن يطلب من navigator.contacts.select() الحصول على إذن من المستخدم، وعلى المستخدم اختيار جهات الاتصال التي يريد مشاركتها مع الموقع الإلكتروني بشكلٍ فردي.

ملاحظات

يريد فريق Chrome معرفة تجاربك مع واجهة برمجة التطبيقات لتطبيق "أداة اختيار جهات الاتصال".

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

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

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

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

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

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

روابط مفيدة

شكرًا

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

ملاحظة: الأسماء الواردة في منتقي جهات الاتصال هي أحرف من Alice in Wonderland.