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

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

Pete LePage

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

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

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

رصد الميزات

للتحقق مما إذا كانت واجهة برمجة تطبيقات "أداة اختيار جهات الاتصال" متوافقة، استخدم:

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

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

فتح منتقي جهات الاتصال

نقطة الدخول إلى واجهة برمجة تطبيقات "أداة اختيار جهات الاتصال" هي 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().

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

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

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

على سبيل المثال، إذا طلب أحد المواقع الإلكترونية name وemail وtel ومستخدم. يحدد جهة اتصال واحدة تحتوي على بيانات في حقل الاسم، ويوفر ولكن ليس لديه عنوان بريد إلكتروني، سيكون الردّ المعروض:

[{
  "email": [],
  "name": ["Queen O'Hearts"],
  "tel": ["+1-206-555-1000", "+1-206-555-1111"]
}]

الأمان والأذونات

صمم فريق Chrome ونفذ واجهة برمجة تطبيقات اختيار جهات الاتصال باستخدام محددة في التحكّم في الوصول إلى الميزات الفعّالة للنظام الأساسي للويب بما في ذلك تحكُّم المستخدم والشفافية وتسهيل الاستخدام. سأشرح كل منها.

تحكم المستخدم

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

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

الشفافية

لتوضيح تفاصيل الاتصال التي تتم مشاركتها، سيجري أداة الاختيار دائمًا تعرض اسم جهة الاتصال ورمزها، بالإضافة إلى أي خصائص يحتوي عليها الموقع طلبنا. على سبيل المثال، إذا طلب أحد المواقع الإلكترونية name وemail وtel، ستظهر السمات الثلاث في أداة الاختيار. بدلاً من ذلك، إذا كان الموقع الإلكتروني يطلب tel فقط، ستعرض أداة الاختيار الاسم فقط أرقام الهواتف.

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

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

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

ملاحظات

يرغب فريق Chrome في الاطلاع على تجاربك مع منتقي جهات الاتصال واجهة برمجة التطبيقات.

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

هل واجهت مشكلة في التنفيذ في Chrome؟ أم أن التنفيذ عن المواصفات؟

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

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

هل تخطّط لاستخدام واجهة برمجة تطبيقات "أداة اختيار جهات الاتصال"؟ يساعد دعمك العام فريق Chrome لتحديد الأولوية للميزات، وتوضيح لموردي المتصفحات الآخرين أمرًا بالغ الأهمية لدعمهم.

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

روابط مفيدة

• شرح علني
• مواصفات منتقي جهات الاتصال
• العرض التوضيحي لواجهة برمجة تطبيقات اختيار جهات الاتصال والمصدر التجريبي لواجهة برمجة تطبيقات اختيار جهات الاتصال
• خطأ في التتبُّع
• إدخال ChromeStatus.com
• مكوِّن Blink: Blink>Contacts

شكرًا

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

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