वेब के लिए संपर्क पिकर

Contact Picker API की मदद से, उपयोगकर्ता अपनी संपर्क सूची से संपर्कों को आसानी से शेयर कर सकते हैं.

Contact Picker API क्या है?

iOS/Android ऐप्लिकेशन में, मोबाइल डिवाइस पर उपयोगकर्ता के संपर्कों का ऐक्सेस पाने की सुविधा, शुरू से ही उपलब्ध है. वेब डेवलपर से, इस सुविधा के लिए अक्सर अनुरोध मिलते हैं. अक्सर, वे iOS/Android ऐप्लिकेशन बनाने के लिए, इसी सुविधा को मुख्य वजह बनाते हैं.

Contact Picker API spec, Android M या उसके बाद के वर्शन पर Chrome 80 से उपलब्ध है. यह एक ऑन-डिमांड एपीआई है, जिसकी मदद से उपयोगकर्ता अपनी संपर्क सूची से एंट्री चुन सकते हैं और चुनी गई एंट्री की सीमित जानकारी किसी वेबसाइट के साथ शेयर कर सकते हैं. इसकी मदद से, उपयोगकर्ता अपनी पसंद के मुताबिक और जब चाहें, सिर्फ़ वही कॉन्टेंट शेयर कर सकते हैं. साथ ही, अपने दोस्तों और परिवार के साथ आसानी से जुड़ सकते हैं.

उदाहरण के लिए, वेब पर चलने वाला ईमेल क्लाइंट, किसी ईमेल के पाने वाले को चुनने के लिए, Contact Picker API का इस्तेमाल कर सकता है. वॉइस-ओवर-आईपी ऐप्लिकेशन यह पता लगा सकता है कि किस फ़ोन नंबर पर कॉल करना है. इसके अलावा, सोशल नेटवर्क की मदद से उपयोगकर्ता यह पता लगा सकता है कि उसके कौनसे दोस्त पहले से ही शामिल हैं.

Contact Picker API का इस्तेमाल करना

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 का अनुरोध कर रही है, एक संपर्क चुना गया है.
किसी संपर्क को दबाकर रखने पर, पिकर का स्क्रीन शॉट.
किसी संपर्क को दबाकर रखने पर दिखने वाला नतीजा.

किसी संपर्क पर लंबे समय तक दबाने पर, वह सारी जानकारी दिखेगी जो संपर्क चुनने पर शेयर की जाएगी. (चेशर कैट की संपर्क इमेज देखें.)

अनुमति का हमेशा चालू रहना

संपर्कों का ऐक्सेस, मांग पर दिया जाता है और यह सेव नहीं होता. जब भी कोई साइट, उपयोगकर्ता के जेस्चर की मदद से navigator.contacts.select() को ऐक्सेस करना चाहे, तो उसे ऐसा करना होगा. साथ ही, उपयोगकर्ता को उन संपर्कों को चुनना होगा जिन्हें उसे साइट के साथ शेयर करना है.

सुझाव/राय दें या शिकायत करें

Chrome की टीम, संपर्क चुनने वाले टूल के एपीआई के साथ आपके अनुभवों के बारे में जानना चाहती है.

क्या लागू करने में समस्या आ रही है?

क्या आपको Chrome में इस सुविधा को लागू करने में कोई गड़बड़ी मिली? या क्या इसे लागू करने का तरीका, स्पेसिफ़िकेशन से अलग है?

  • https://new.crbug.com पर जाकर, गड़बड़ी की शिकायत करें. इसमें ज़्यादा से ज़्यादा जानकारी शामिल करें. साथ ही, गड़बड़ी को दोहराने के लिए आसान निर्देश दें और कॉम्पोनेंट को Blink>Contacts पर सेट करें. Glitch, समस्या को तुरंत और आसानी से शेयर करने के लिए बहुत अच्छा है.

क्या आपको एपीआई का इस्तेमाल करना है?

क्या आपको Contact Picker API का इस्तेमाल करना है? सार्वजनिक तौर पर सहायता करने से, Chrome टीम को सुविधाओं को प्राथमिकता देने में मदद मिलती है. साथ ही, इससे ब्राउज़र के अन्य वेंडर को यह पता चलता है कि इन सुविधाओं को उपलब्ध कराना कितना ज़रूरी है.

  • WICG के Discourse थ्रेड पर शेयर करें कि आपको इसका इस्तेमाल कैसे करना है.
  • #ContactPicker हैशटैग का इस्तेमाल करके, @ChromiumDev को ट्वीट करें और हमें बताएं कि इसका इस्तेमाल कहां और कैसे किया जा रहा है.

मदद के लिए लिंक

धन्यवाद

इस सुविधा को लागू करने वाले फ़िनूर थोरिन्सन और रेयान कांसो का धन्यवाद. साथ ही, पीटर बेवरलू का भी धन्यवाद, जिनके कोड को मैंने बिना किसी शर्मिंदगी के चुराया और डेमो के लिए फिर से बनाया.

PS: मेरे संपर्क पिकर में मौजूद नाम, 'वंडरलैंड में एलिस के रोमांच की कहानी' के किरदार हैं.