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

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

Pete LePage

ما هي واجهة برمجة تطبيقات Contact Picker؟

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

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

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

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

تتطلب واجهة برمجة تطبيقات منتقي جهات الاتصال استدعاء طريقة مع معلمة خيارات تحدد أنواع معلومات الاتصال التي تريدها. تخبرك الطريقة الثانية بالمعلومات التي سيوفرها النظام الأساسي.

رصد الميزات

لمعرفة ما إذا كانت واجهة برمجة التطبيقات 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.
}

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

اكتشاف الخصائص المتاحة

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

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

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

تعرض واجهة برمجة تطبيقات Contact Picker من خلال مصفوفة من جهات الاتصال، وتتضمن كل جهة اتصال مصفوفة من الخصائص المطلوبة. إذا لم يكن لدى جهة الاتصال بيانات عن الموقع المطلوب، أو إذا اختار المستخدم إيقاف مشاركة موقع معيّن، تعرض واجهة برمجة التطبيقات صفيفًا فارغًا. (أصف كيفية اختيار المستخدم للخصائص في قسم تحكُّم المستخدم).

على سبيل المثال، إذا طلب أحد المواقع الإلكترونية 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.

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

هل واجهت خطأً في تنفيذ Chrome؟ أم أن التنفيذ مختلف عن المواصفات؟

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

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

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

روابط مفيدة

شكرًا

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

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