वेब ऐप इंटीग्रेशन

यह पेज बताता है कि Unico journeys कैसे काम करती हैं और उन्हें किसी application में integrate करने के लिए कौन-कौन से integration models उपलब्ध हैं।

Journey उन steps का समूह है जिनसे user किसी identity verification को पूरा करने के लिए गुज़रता है। उदाहरण के लिए: document की फ़ोटो कैप्चर करना और facial capture (लाइवनेस) करना।

Unico पूरे experience को manage करता है। Integration का प्रयास न्यूनतम है: journey CreateProcess के ज़रिए बनाई जाती है, user को उस तक पहुँचाया जाता है, और अंत में result प्राप्त होता है। बीच में जो कुछ भी होता है (screens, instructions, validations) वह पहले से ही तैयार है और Unico द्वारा maintain किया जाता है।

अपना integration approach चुनना

• Web SDK (unico-webframe package): तब use करें जब आपका back-end पहले से ही identity verification flow को control करता है और उसे केवल client-side capture component की ज़रूरत है। यह base64 + encrypted JWT सीधे आपके callback में लौटाता है; API calls आप स्वयं manage करते हैं।
• Web App Integration (idpay-b2b-sdk package): तब use करें जब आप चाहते हैं कि Unico पूरी journey (multi-step flows, document capture + लाइवनेस) को orchestrate करे। idpay-b2b-sdk package embedded Journeys SDK (iFrame) model को power करता है; Direct access (redirect) model को किसी library की ज़रूरत नहीं होती।

दो integration models

हर client की ज़रूरतें अलग होती हैं। Unico user को journey तक पहुँचाने के लिए दो models प्रदान करता है।

Model	किसके लिए उपयुक्त
Direct access	ऐसे mobile applications जो पहले से WebView उपयोग करते हैं, या ऐसे web flows जहाँ journey मुख्य page के बाहर हो सकती है
Journeys SDK	ऐसे web applications जिन्हें integrated, seamless अनुभव चाहिए और जो user को एक ही environment में बनाए रखना चाहते हैं

Direct access

User को Unico द्वारा host किए गए एक link पर redirect किया जाता है, जहाँ journey चलती है। पूरा होने पर वह उस URL पर लौटता है जिसे process creation के समय परिभाषित किया गया था (callbackUri parameter)।

यह अपनाने में सबसे आसान approach है: इसमें किसी library की installation की ज़रूरत नहीं होती और यह तब अच्छा काम करता है जब journey को application के अपने page के भीतर होने की ज़रूरत नहीं होती। दूसरी ओर, user को client के environment से बाहर ले जाने से आम तौर पर अधिक friction पैदा होता है और परिणामस्वरूप drop-off दर अधिक होती है।

Process बनाने के बाद, API response में Unico द्वारा host की गई journey का URL शामिल होता है। User को वहाँ पहुँचाने के दो सामान्य तरीके हैं:

• Standard redirect. User को सीधे journey URL पर redirect किया जाता है। पूरा होने पर, Unico उसे process creation के समय परिभाषित किए गए callbackUri पर वापस redirect कर देता है।
• window.open() के साथ नया tab. journey एक नए browser tab में खुलती है, जिससे user एक अलग context में बना रहता है। इस स्थिति में, यह अनुशंसित है कि callbackUri पर URL परिवर्तन की निगरानी करें और process पूरा होते ही tab बंद कर दें। API के बारे में विवरण के लिए MDN documentation देखें।

Mobile applications में, journey को सीधे खोलने के लिए WebView का उपयोग करना सामान्य है, जिसमें किसी अतिरिक्त redirect की ज़रूरत नहीं होती। इस स्थिति में, callbackUri एक deeplink भी स्वीकार करता है, जिससे journey के पूरा होने पर native application में किसी विशिष्ट screen को खोलना संभव होता है। बस deeplink को return destination के रूप में configure करें और operating system स्वयं user को सही जगह पर route कर देगा।

Journeys SDK

Journey application के भीतर ही होती है, और user को उसके context से बाहर नहीं ले जाती। Journeys SDK को application में install किया जाता है और ज़रूरत पड़ने पर journey खोलने के लिए उपयोग किया जाता है।

यह अधिक integrated और seamless अनुभव के लिए अनुशंसित रास्ता है, जो user को पूरे दौरान एक ही environment में रखता है, जिससे flow भर में friction और drop-off कम होने की प्रवृत्ति रहती है।

Unico आधुनिक browsers के साथ compatible एक JavaScript library प्रदान करता है, जिससे journey को कुछ ही lines of code में लगभग किसी भी application में integrate किया जा सकता है।

Compatibility

यह library इस तरह design की गई है कि उपयोग किए जा रहे stack की परवाह किए बिना, बिना किसी friction के किसी भी project में फ़िट हो जाए:

• कोई भी web application. UMD format में distribute की गई, यह आधुनिक bundlers (जैसे webpack या Vite) के ज़रिए import किए जाने पर काम करती है। किसी भी framework (React, Angular, Vue) या pure JavaScript के साथ compatible।
• आधुनिक browsers. library में Promises और async/await जैसी सुविधाओं के लिए आवश्यक polyfills पहले से शामिल हैं, जिससे browsers के पुराने versions तक भी compatibility बढ़ जाती है।
• Standard web APIs. journey browser की native क्षमताओं पर चलती है, और project में किसी plugin या external library पर निर्भर नहीं करती।

SDK आंतरिक रूप से कैसे काम करता है

जब कोई journey खोली जाती है, तो SDK page में एक iFrame डालता है और उसी क्षण से पूरे visual experience का नियंत्रण ले लेता है। हर step की screens, scripts और assets इसी iFrame के भीतर चलती हैं, user के शुरू करने के क्षण से लेकर process पूरा होने तक।

यह architectural निर्णय जानबूझकर लिया गया है: iFrame isolation यह सुनिश्चित करता है कि Unico journey application की styles या behavior में हस्तक्षेप न करे। कोई भी script बाहरी context में leak नहीं होती, कोई भी CSS rule application की अपनी styles से टकराती नहीं। परिणाम end user के लिए एक सुसंगत अनुभव और client के product पर न्यूनतम प्रभाव है।

चूँकि iFrame बनाने और manage करने की ज़िम्मेदारी Unico की है, journey में सुधार (चाहे performance, experience या validation से जुड़े हों) सभी users तक अपने आप पहुँचते हैं, और integrated application में किसी बदलाव की ज़रूरत नहीं होती। Integration हमेशा उपलब्ध सर्वोत्तम optimizations के साथ चलेगा, और platform के हर विकास को track करने या उस पर react करने की ज़रूरत नहीं होती।

शुरू करना

Step 1: Installation

idpay-b2b-sdk package, IDPay payment journeys और identity verification journeys के बीच साझा किया जाता है। Identity use cases के लिए, नीचे दिए गए steps में दिखाए अनुसार ByUnicoSDK class को import करें।

  npm install idpay-b2b-sdk

Journeys SDK को install करने का अनुशंसित तरीका npm या yarn जैसे dependency manager के ज़रिए, npm registry पर उपलब्ध package से है। यह installation और dependency management को सरल बनाने के साथ-साथ, उपयोग में आने वाले version पर स्पष्ट नियंत्रण देता है और जब भी कोई नया version publish हो, update करना आसान बनाता है।

SDK Semantic Versioning (SemVer) का पालन करता है, यानी patch और minor updates कोई breaking changes नहीं लाते। Project को इन updates को अपने आप receive करने के लिए configure करना सुरक्षित है। ऐसे बदलाव जिनमें integration में adaptations की ज़रूरत पड़ सकती है, वे major versions के लिए आरक्षित रहते हैं और हमेशा एक migration guide के साथ आते हैं।

SDK को अपडेट रखें

नवीनतम version पर बने रहना दो कारणों से विशेष रूप से महत्वपूर्ण है। पहला है security: जब भी vulnerabilities की पहचान होती है या communication protocol को मज़बूत करने के अवसर मिलते हैं, तब security patches publish किए जाते हैं। पुराना version चलाने का मतलब है इन fixes को छोड़ देना और flow को अनावश्यक जोखिमों में डालना। दूसरा है stability: bug fixes भी इसी तरह distribute होते हैं, और पुराने versions में ऐसा behavior हो सकता है जो नए releases में पहले ही हल किया जा चुका है।

शुरू करने से पहले, अपने domains को Unico support team के पास register करें। सभी domains को HTTPS का उपयोग करना ज़रूरी है।

Step 2: init(options) को call करें

SDK को initialize करता है और journey के सही ढंग से काम करने के लिए आवश्यक scripts को पहले से load करता है, जिससे end user के लिए एक अधिक सहज अनुभव बनता है। इसे flow में जितना जल्दी हो सके call करें।

Parameter	आवश्यक	विवरण
token	हाँ	Create Process API द्वारा लौटाया गया process token
env	नहीं	केवल test environments के लिए 'uat' set करें

import { ByUnicoSDK } from 'idpay-b2b-sdk';

ByUnicoSDK.init({
  token,
  // env: 'uat' // केवल test environments के लिए
});

Step 3: open(options) को call करें

iFrame दिखाता है और user के लिए journey शुरू करता है। इस बिंदु से, सब कुछ iFrame के भीतर अपने आप होता है, और किसी भी मध्यवर्ती step को manage करने की ज़रूरत नहीं होती।

Parameter	आवश्यक	विवरण
transactionId	हाँ	Create Process API द्वारा लौटाया गया process ID
token	हाँ	Create Process API द्वारा लौटाया गया process token
onFinish	हाँ	journey के समाप्त होने या बंद होने पर execute होने वाला callback
onWidgetVisibilityChange	नहीं	widget की visibility state बदलने पर execute होने वाला callback

Application के साथ अगली interaction तब होती है जब journey समाप्त होती है, चाहे user ने उसे पूरा किया हो या बंद किया हो। उस समय, SDK onFinish callback को invoke करता है, जिसे open में parameter के रूप में पास किया गया था। वहाँ से, application result जाँचने के लिए getProcess API call कर सकती है, या यदि asynchronous approach पसंद हो तो Webhook notification का इंतज़ार कर सकती है।

Result query करने के अलावा, यह अनुशंसित है कि application के front-end state को संभालने के लिए onFinish का उपयोग करें:

• Loops से बचें. journey समाप्त होने के तुरंत बाद यदि user फिर से flow trigger करे, तो processes के तुरंत और अनावश्यक रूप से दोबारा बनने को रोकें।
• Flow management. सुनिश्चित करें कि journey बंद होने के बाद user application के अगले step पर पहुँचे, ताकि वह बिना किसी निकास वाली screen पर अटका न रहे।

चेतावनी

onFinish callback यह संकेत देता है कि user ने journey पूरी कर ली है, लेकिन approval की गारंटी नहीं देता। हो सकता है कि process, Unico के किसी validation rule में fail होकर समाप्त हुआ हो। getProcess के ज़रिए query करना या Webhook notification प्राप्त करना वैकल्पिक नहीं है: ये ही वास्तविक result के एकमात्र स्रोत हैं, और application का behavior इन्हीं पर आधारित होना चाहिए। यह तय करने के लिए कि user approve हुआ या नहीं, onFinish को अकेले उपयोग नहीं करना चाहिए।

onFinish callback एक object प्राप्त करता है जो बताता है कि journey कैसे समाप्त हुई:

Field	Type	विवरण
type	string	journey किस तरह समाप्त हुई: 'FINISH' (पूर्ण) या 'CLOSE' (user ने पूरा होने से पहले बंद किया)
transaction	object | undefined	जब type 'FINISH' हो तब मौजूद; जब type 'CLOSE' हो तब undefined
transaction.id	string	process identifier (वही transactionId जो पास किया गया)
transaction.redirectUrl	string	journey के बाद user को redirect करने के लिए URL

onWidgetVisibilityChange callback को संभालना वैकल्पिक है और आपके use case के लिए प्रासंगिक न भी हो। यह तब-तब invoke होता है जब widget की visibility state बदलती है, और केवल एक विशिष्ट स्थिति में उपयोगी है: कुछ journeys एक transparent background दिखाती हैं, जिससे experience के पीछे application का page दिखता रहता है। ऐसी applications जो verification flow के दौरान अपना custom modal दिखाती हैं (उदाहरण के लिए, कई KYC providers के बीच orchestration के हिस्से के रूप में), उस modal को Unico widget के पीछे दिखा सकती हैं, जिससे visual experience बिगड़ता है। ऐसी स्थिति में, यह callback application को इस बात की अनुमति देता है कि Unico journey के सक्रिय रहने तक किसी भी अतिरिक्त visual element को छिपा दे और समाप्त होने पर उसे बहाल कर दे। यदि आपकी application में ऐसा कोई UI नहीं है जो widget के साथ overlap कर सके, तो आप इसे सुरक्षित रूप से छोड़ सकते हैं।

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: ({ transaction, type }) => {
    if (type === 'FINISH') {
      // Journey पूर्ण (transaction = { id, redirectUrl }): यहाँ अपना flow जारी रखें।
    }
    // type === 'CLOSE' → user ने पूरा होने से पहले बंद किया;
  },
  // वैकल्पिक: केवल तभी ज़रूरी जब आपकी app ऐसा UI दिखाती हो जो widget से overlap कर सके।
  onWidgetVisibilityChange: (visible) => {
    // widget की visibility के अनुसार अपना modal छिपाएँ या बहाल करें
  },
});

// SDK को किसी भी समय स्पष्ट रूप से बंद करने के लिए:
ByUnicoSDK.close();

नीचे दिया गया sequence diagram दिखाता है कि iFrame को configure करने के लिए SDK और API result का उपयोग कैसे करें:

Security

इस section का दायरा

यह security rationale विशेष रूप से Web App Integration (idpay-b2b-sdk) पर लागू होता है। Web SDK (unico-webframe) एक अलग model उपयोग करता है: यह पूरी तरह page context में चलता है और इसके लिए CSP आवश्यक है। ये अलग-अलग security architectures वाले दो अलग products हैं।

इस model में security परतों में बनाई गई है, जिसकी शुरुआत SDK और iFrame के भीतर चलने वाली application के बीच के communication protocol से होती है।

जब journey load होती है, तो दोनों पक्ष communication स्थापित करने के लिए एक handshake करते हैं। इस प्रक्रिया में, Unico की application postMessage के ज़रिए प्राप्त data injection message के origin को, environment (UAT और PROD) के अनुसार विभाजित authorized domains की एक बंद सूची के विरुद्ध validate करती है। गैर-अनुमोदित origins से आए messages तुरंत discard कर दिए जाते हैं, जिससे journey को अनधिकृत pages में embed किए जाने से रोका जाता है और clickjacking जैसी vulnerabilities के लिए attack surface समाप्त हो जाता है।

Origin validation के अलावा, flow केवल एक valid transaction token के साथ ही आगे बढ़ता है: एक single-use JWT, जिसे Unico backend द्वारा जारी और sign किया जाता है। यह सुनिश्चित करता है कि एक authorized origin भी expired, दोबारा इस्तेमाल किए गए या forged token के साथ काम न कर सके।

Handshake के बाद, token को iFrame में inject कर दिया जाता है और दोनों पक्षों के बीच कोई sensitive जानकारी नहीं बहती। बाकी सारा communication केवल interface नियंत्रण (खोलना, बंद करना और screen transitions) के लिए होता है, जिससे journey के दौरान process के data को intercept या leak होने से रोका जाता है।

iFrame isolation runtime पर Unico के scripts की integrity की भी रक्षा करता है। चूँकि code, page से अलग एक context में चलता है, इसे बाहरी scripts न तो access कर सकते हैं और न ही modify कर सकते हैं, जिससे यह सुनिश्चित होता है कि journey ठीक वैसे ही चले जैसे उसे बनाया गया था, बिना किसी हस्तक्षेप के।

Design के अनुसार, इस integration model में CSP नहीं अपनाया जाता। Authorized domains हर client की security configuration का हिस्सा होते हैं, और उन्हें headers में सार्वजनिक रूप से उजागर करने से दुर्भावनापूर्ण actors के लिए infrastructure का mapping आसान हो सकता है। चूँकि client की पहचान केवल init के समय ही होती है, इसलिए उससे पहले इन domains को headers में dynamically inject करना संभव नहीं है, जिससे इस privacy को छोड़े बिना CSP का उपयोग अव्यवहार्य हो जाता है। सभी security गारंटियाँ ऊपर वर्णित handshake protocol द्वारा प्रदान की जाती हैं।

SDK-specific troubleshooting

इस section में integration के दौरान आने वाली सबसे आम समस्याओं और उन्हें जाँचने के अनुशंसित तरीकों को शामिल किया गया है।

अप्रत्याशित behavior या टूटा हुआ flow

जाँचें कि कहीं कोई application script सीधे DOM में iFrame को manipulate तो नहीं कर रही। SDK, page के body में iFrame बनाता और manage करता है, और कोई भी बाहरी संशोधन (चाहे scope, positioning या attributes का हो) journey के lifecycle में हस्तक्षेप कर सकता है और अप्रत्याशित behavior पैदा कर सकता है।

अपेक्षा से भिन्न visual experience

जाँचें कि कहीं कोई global stylesheet, iFrame के भीतर की properties को override तो नहीं कर रही। SDK, iFrame और उसके सभी आंतरिक elements को dynamic IDs और unico से prefix की गई classes के साथ बनाता है, जिससे ID या class selectors द्वारा conflict का जोखिम काफ़ी कम हो जाता है। फिर भी, व्यापक दायरे वाले CSS rules (जैसे tag selectors) iFrame के भीतर के elements तक पहुँच सकते हैं और user को दिए जाने वाले visual experience को बदल सकते हैं।

SDK library की files सीधे संशोधित की गईं

जाँचें कि कहीं कोई library file, dependency manager के बाहर संशोधित तो नहीं की गई। Library को केवल npm या yarn के ज़रिए manage किया जाना चाहिए, बिना installed files में सीधे बदलाव किए। मैन्युअल संशोधन ऐसे असामान्य behavior पैदा कर सकते हैं जिन्हें reproduce करना कठिन होता है और जो Unico support द्वारा सहायता को असंभव बना देते हैं।

Capture tests के दौरान DevTools खुला न रखें

Unico का application facial capture के लिए Capture SDK (unico-webframe) का उपयोग करता है, जो खुले हुए DevTools को एक संभावित fraud signal के रूप में पहचानता है और submission को block कर देता है। End-to-end capture tests चलाने से पहले DevTools बंद कर दें।

असमर्थित integrations

इस documentation में वर्णित models (direct access और Journeys SDK) ही Unico द्वारा आधिकारिक रूप से समर्थित एकमात्र integration approaches हैं। इन standards से भटकने वाली integrations अप्रत्याशित behavior, security flow में विफलता और journey में रुकावट पैदा कर सकती हैं, और ये Unico support के दायरे में नहीं आएँगी।

असमर्थित approaches के कुछ उदाहरण:

• mobile applications में SDK को WebView के भीतर embed करना। ऐसे मामलों में, सही approach direct access model का उपयोग करना है, यानी Journeys SDK को शामिल किए बिना journey link को सीधे WebView में खोलना।
• Journeys SDK से गुज़रे बिना, HTML <iframe> tag के ज़रिए iFrame को सीधे load करना। iFrame, SDK का एक आंतरिक implementation detail है और इसे मैन्युअल रूप से instantiate नहीं करना चाहिए। सही approach Journeys SDK का उपयोग करना है, जो iFrame के lifecycle को सुरक्षित रूप से और अपेक्षित standards के भीतर manage करता है।

यदि इस बारे में कोई संदेह हो कि कोई approach समर्थित standard के भीतर है या नहीं, तो implementation आगे बढ़ाने से पहले documentation देखें या support से संपर्क करें।