--- title: वेब ऐप इंटीग्रेशन description: Web & SDK contract को client side पर कैसे integrate करें — redirect flows और iFrame SDK सेटअप। canonical: https://developer.unico.io/hi/dual-api/developers/sdks-and-tools/web/web-integration/ locale: hi generated_by: markdown-export --- यह पेज बताता है कि 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 किया जाता है। :::tip[अपना 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/open) देखें। ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` Mobile applications में, journey को सीधे खोलने के लिए **WebView** का उपयोग करना सामान्य है, जिसमें किसी अतिरिक्त redirect की ज़रूरत नहीं होती। इस स्थिति में, `callbackUri` एक **deeplink** भी स्वीकार करता है, जिससे journey के पूरा होने पर native application में किसी विशिष्ट screen को खोलना संभव होता है। बस deeplink को return destination के रूप में configure करें और operating system स्वयं user को सही जगह पर route कर देगा। ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### 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 करें। ```bash 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 के साथ आते हैं। :::tip[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 करें | ```javascript 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 पर अटका न रहे। :::warning `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 कर सके, तो आप इसे सुरक्षित रूप से छोड़ सकते हैं। ```javascript 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 का उपयोग कैसे करें: ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### सैंपल ऐप्स | भाषा / फ्रेमवर्क | विवरण | रिपॉजिटरी | | --------------------- | ------------ | ---------- | | Angular | Journeys SDK को implement करने वाला Angular में PoC | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | Journeys SDK को implement करने वाला JS Vanilla में PoC | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | Journeys SDK को implement करने वाला React में PoC | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | Journeys SDK को implement करने वाला Vue JS में PoC | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/unico-cbu-poc-vuejs) | #### Security :::note[इस section का दायरा] यह security rationale विशेष रूप से **Web App Integration** (`idpay-b2b-sdk`) पर लागू होता है। **Web SDK** (`unico-webframe`) एक अलग model उपयोग करता है: यह पूरी तरह page context में चलता है और [इसके लिए CSP आवश्यक है](/dual-api/developers/sdks-and-tools/web/web-sdk/installation)। ये अलग-अलग 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 बंद कर दें। :::warning[असमर्थित 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 `