मुख्य सामग्री पर जाएं

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

Markdown

यह पेज बताता है कि 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 models​

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

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

यदि आपका application एक native mobile app है, तो हम web integration के बजाय उस platform (Android, iOS, या Flutter) के लिए 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

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

  npm install unico-journey-sdk
पहले idpay-b2b-sdk

यह पैकेज पहले idpay-b2b-sdk के रूप में प्रकाशित किया गया था। यह एक नए नाम के तहत वही SDK है और उसी संस्करण लाइन को बनाए रखता है। नए नाम के तहत केवल 2.3.0 और उसके बाद के उपलब्ध हैं — पूरे इतिहास के लिए रिलीज़ नोट्स देखें।

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 'unico-journey-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 कैसे समाप्त हुई:

FieldTypeविवरण
typestringjourney किस तरह समाप्त हुई: 'FINISH' (पूर्ण) या 'CLOSE' (user ने पूरा होने से पहले बंद किया)
transactionobject | undefinedजब type 'FINISH' हो तब मौजूद; जब type 'CLOSE' हो तब undefined
transaction.idstringprocess identifier (वही transactionId जो पास किया गया)
transaction.​redirectUrlstringjourney के बाद 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 का उपयोग कैसे करें:

संदर्भ ऐप​

भाषा / फ्रेमवर्कविवरणरिपॉजिटरी
Node.js (Express)Node.js में संदर्भ ऐप जो Journeys SDK के साथ पूर्ण user journey flow को लागू करता हैGitHub — reference-apps/web

Security​

इस 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 अपनी journeys को सुरक्षित करने के लिए कई mechanisms का उपयोग करता है, जिनमें से एक खुले हुए 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 से संपर्क करें।

अंतिम अपडेट को