आपको कौन सा सरफ़ेस चाहिए

एम्बेडेड फ़्रेम: हमारे tiles आपके अपने लेआउट के अंदर render किए गए, प्रति नेटवर्क एक slot या कई के लिए एक slot।

आपका अपना बटन: बटन आप render करते हैं, और हमारा एक संक्षिप्त पॉपअप नेटवर्क को संभालता है।

होस्टेड लिंकिंग पेज: हमारे द्वारा होस्ट किया गया पेज, आपके लोगो और रंगों के साथ, जिसका उपयोग करने के लिए आपका उपयोगकर्ता आपका ऐप छोड़ता है।
init आपको दोनों देता है: जहाँ आप
हमारे बटन चाहते हैं वहाँ फ़्रेम mount करें, और बाक़ी हर जगह अपने बटन से popup() कॉल करें। वे
एक ही सेशन साझा करते हैं और एक ही handlers पर रिपोर्ट करते हैं।डायरेक्ट मोड वही पॉपअप है बिना हमारी स्क्रिप्ट के —
सख़्त Content-Security-Policy वाले पेज, server-rendered पेज, या native ऐप के लिए। वहाँ पॉपअप
आप स्वयं खोलते और देखते हैं।Script जोड़ें
कोई version और उसका hash pin करें, या बिना hash के कोई channel track करें। दोनों कभी नहीं — बदलते रहने वाले URL परintegrity attribute हमारी अगली release पर काम करना बंद कर देता है,
क्योंकि वह जिस फ़ाइल का नाम लेता है वह वैध रूप से बदल चुकी होती है।
v1 वह channel है जिसकी अनुशंसा की जाती है। यह फ़िक्स अपनाता है लेकिन कभी breaking change
पार नहीं करता। latest परिभाषा से ही major versions पार करता है, इसलिए वह अंततः आपके पेज को ऐसा
version थमा देगा जिसके व्यवहार की आपने समीक्षा नहीं की है।
हर version का hash
manifest.json में प्रकाशित होता है,
जो यह भी बताता है कि हर channel वर्तमान में क्या serve कर रहा है:
Content-Security-Policy
यदि आपका पेज Content-Security-Policy भेजता है, तो उसे दो entries चाहिए, दोनों उस host के नाम पर जिससे आप script लोड करते हैं:connect-src entry नहीं चाहिए — हमारे फ़्रेम हमारे
API तक अपने अंदर से पहुँचते हैं, आपके पेज से नहीं — और पॉपअप के लिए कोई entry नहीं, जो
top-level windows हैं जिन पर आपकी policy लागू नहीं होती। दोनों entries को मापा गया है:
script-src हटाने से script ब्लॉक होती है, और frame-src हटाने से फ़्रेम।
एक instance शुरू करें
session एकमात्र आवश्यक option है। इसे प्रति instance एक बार कॉल किया जाता है, प्रति mount
एक बार नहीं, और इसे mode: "connect" के साथ
Link Session बनाएँ के प्रति आपके backend की प्रतिक्रिया —
{ sessionId, token, expiresAt } — बिल्कुल जैसी आई वैसी लौटानी होगी।
network नहीं बताता — यह आपके अकाउंट द्वारा अनुमत हर नेटवर्क को अधिकृत करता
है, और कौन से दिखाई देते हैं यह प्रति mount, आपके पेज में तय होता है। यह एक origin ज़रूर ले जाता
है, जो एकमात्र चीज़ है जिससे फ़्रेम render होते ही हैं: फ़्रेम उसे embed करने वाले पेज की तुलना उस
मान से करता है और कहीं और render करने से इनकार कर देता है।
Token की समाप्ति से पहले हम session को फिर से कॉल करते हैं, ताकि पूरे दिन खुला छोड़ा गया पेज
भी काम करता रहे। जो कॉल reject होती है, या कोई token नहीं लौटाती, उसका दो बार और पुनः प्रयास किया
जाता है — 0.5s बाद, फिर 1s बाद — इससे पहले कि हम हार मानकर error emit करें। यानी एक refresh की
लागत आपके endpoint पर अधिकतम तीन कॉल है।
एक slot mount करें
प्रति slot एकmount। एक नेटवर्क माँगें, कई, या वह सब कुछ जो सेशन अनुमति देता है — granularity
आपकी है, इसलिए slot किसी मौजूदा टेबल की एक row भी हो सकता है या सब कुछ रखने वाला एक panel।
mount एक CSS selector या element लेता है, और { unmount, element } लौटाता है। यदि target किसी
से match नहीं करता तो यह throw करता है — जो लगभग हमेशा ऐसा slot होता है जो अभी मौजूद नहीं है,
इसलिए अपने markup के document में आने के बाद mount करें।
हर mount एक iframe है। वह अपनी ऊँचाई हमें रिपोर्ट करता है और हम उसे उसके अनुसार resize करते हैं,
इसलिए हमारी सामग्री बदलने पर आपका लेआउट reflow होता है; maxHeight से आगे फ़्रेम आपके पेज से
बाहर निकलने के बजाय अंदर ही scroll करता है। हमारा समर्थित सबसे संकीर्ण slot 300px है।
Network keys Ayrshare की अपनी हैं, और alias spellings भी काम करती हैं: instagram और
instagramapi दोनों का अर्थ instagramApi है, और x का अर्थ twitter। जो key कोई नेटवर्क नहीं
है, वह कोई tile render नहीं करती।
आपका अपना बटन
जो ग्राहक हमारे किसी फ़्रेम के बजाय अपना बटन इस्तेमाल करना पसंद करे, वह इसके बजायpopup कॉल
करता है। यह वही फ़्लो, उसी सेशन पर चलाता है, और उन्हीं handlers पर रिपोर्ट करता है।
popup { close(), network } लौटाता है, और हमेशा एक handle लौटाता है — ब्लॉक हुए पॉपअप के
बाद भी, जहाँ close() कुछ नहीं करता — ताकि आपके कोड को close() कॉल करने से पहले कभी null-check
न करना पड़े।
यहाँ हर नेटवर्क काम करता है, उन नेटवर्कों समेत जिन्हें फ़्रेम अपने ही panel के अंदर पूरा करता है:
Facebook अपना hand-off explainer पॉपअप में दिखाता है, Bluesky और X अपना credential फ़ॉर्म दिखाते
हैं, और LinkedIn, Pinterest, YouTube और Google Business नेटवर्क तक जाकर लौटते हैं।
यह उन तीन चीज़ों के लिए synchronously throw करता है जो programming errors हैं — कोई network
नहीं, destroy किया हुआ instance, या ऐसा सेशन जो अभी resolve नहीं हुआ है। ब्लॉक हुआ पॉपअप उनमें से
नहीं है: वह reason: "popupBlocked" के साथ error emit करता है, क्योंकि आपके उपयोगकर्ता ने
कुछ ग़लत नहीं किया।
एक समय में अधिकतम एक पॉपअप खुला रहता है। दूसरी कॉल पहले को बंद कर देती है और उस पर
reason: "superseded" के साथ cancelled रिपोर्ट करती है। हमारे किसी फ़्रेम द्वारा खोला गया
पॉपअप अलग चीज़ है और उसे कभी छुआ नहीं जाता, इसलिए आपका बटन किसी mounted slot के अंदर चल रहे
फ़्लो को रद्द नहीं कर सकता।
error के रूप में
रिपोर्ट होता है। Script केवल यह जाँचती है कि कोई नेटवर्क बताया गया था या नहीं।React
Script framework-free है, इसलिए React को हमसे कुछ ख़ास नहीं चाहिए — लेकिन उसके lifecycle की चार बातें पहली ही बार में सही कर लेना उचित है। Script को एक बार लोड करें, अपने component tree के बाहर। Next.js में वह आपके root layout मेंnext/script है; Vite या Create React App में वह index.html में एक टैग है। इसे प्रति component
लोड करना हर mount पर उसे फिर से चलाता है।
- development में आपको session callback दो बार fire होता दिखेगा। React का Strict Mode effects को mount → unmount → mount क्रम में चलाता है, इसलिए instance बनता है, destroy होता है और फिर बनता है। ऊपर का cleanup इसे सुरक्षित बनाता है; dev में इसकी लागत आपके backend पर एक अतिरिक्त कॉल है और production में शून्य।
- effect की dependencies स्थिर रखें। parent render से सीधे
mountमें पास किया गया array literal हर बार नया मान होता है, इसलिए उस पर निर्भर effect हर render पर विजेट को तोड़कर फिर से बनाता है। इसे memoize करें, या ऊपर की तरह स्थिर रखें।
Events
on से subscribe करें, जो एक unsubscribe फ़ंक्शन लौटाता है। Handlers को event का payload और वह
mount मिलता है जिससे वह आया; off(name, handler) वही काम करता है जब आप handler को नाम देना
पसंद करें।
network होता है, सिवाय ready के, और उस एक तरह के error के जो किसी
नेटवर्क के बारे में है ही नहीं — नीचे देखें error के दो स्रोत हैं।
success, unlinked, error और cancelled — और प्रति प्रयास ठीक
एक ही आता है। closed एक lifecycle सूचना है जो किसी अंत के बाद आती है, स्वयं अंत नहीं।
click किसी भी linking काम के शुरू होने से पहले fire होता है, इसलिए वह ऐसा क्लिक भी रिपोर्ट
करता है जिसे ब्लॉक हुआ पॉपअप या मृत सेशन आगे चलकर ठुकरा देता है। आपकी अपनी analytics के लिए
यही event है; started वह है जिसका अर्थ है कि प्रयास वाक़ई चल रहा है।
Reasons
error के दो स्रोत हैं
उनमें से केवल एक link की विफलता है, और वे अलग-अलग फ़ील्ड ले जाते हैं।
- Link error में
network,codeऔर वह mount होता है जिससे वह आया। - Session error — हम आपका सेशन बना या refresh नहीं कर पाए — में केवल
messageहोता है, क्योंकि उस समय कुछ भी लिंक नहीं हो रहा था।
code और network undefined होते हैं।
state आपको polling से बचाता है
state किसी प्रयास की रिपोर्ट के बजाय data channel है। हर फ़्रेम mount होते समय प्रति नेटवर्क एक
emit करता है, जिसमें उस नेटवर्क का वर्तमान state और since timestamp होता है जबसे वह उसे धारण
किए है, और हर बार जब कोई state बदलता है तब एक और — हमारी तरफ़ से शुरू होने वाले बदलावों समेत,
जैसे किसी token का मरकर relink-required में बदल जाना। इसलिए आप बिना कुछ भी poll किए विजेट से
अपना पूरा UI चला सकते हैं।
मान वही enum हैं जो
GET /profiles include=state के साथ लौटाता है: linked,
unlinked, identityVerificationRequired, restricted, rateLimited, suspended।
अनलिंक करना
हमारे tiles लिंक के साथ-साथ अनलिंक भी करते हैं। आपका उपयोगकर्ता किसी कनेक्टेड नेटवर्क पर क्लिक करता है, पुष्टि करता है, और अकाउंट हटा दिया जाता है:click,action: "unlink"के साथ fire होता है।- हटाना सेव हो जाने पर
unlinkedfire होता है।
error रिपोर्ट करता है, और जिससे आपका उपयोगकर्ता confirm चरण पर
पीछे हट जाता है वह cancelled। कोई अलग unlink-failed event नहीं है।
Appearance
किसी ग्राहक की stylesheet cross-origin फ़्रेम के अंदर नहीं पहुँच सकती, इसलिए styling ऐसे data के रूप में जाती है जिसे हम उसके भीतर लागू करते हैं।appearance को init में CSS custom properties
के रूप में पास करें; जो हमें नहीं मिलती वह हर एक हमारा डिफ़ॉल्ट रखती है।
appearance न होने पर, हर token अपना डिफ़ॉल्ट रखता है और फ़्रेम ऐसा दिखता है:

डिफ़ॉल्ट tokens: सफ़ेद surfaces, गहरा navy टेक्स्ट, indigo accent, 8px radius।

ऊपर के tokens लागू होने के बाद वही तीन tiles।
prefers-color-scheme पर आधारित नहीं
है, जानबूझकर — आपके पेज की थीम आपके उपयोगकर्ता के operating system से मेल न खाती हो सकती है, और
कोई media query आपके चुने रंगों को चुपचाप पछाड़ देती। Dark डैशबोर्ड को dark मान देकर थीम किया
जाता है।
यह token सूची एक समर्थित contract है जिसे हम versions के आर-पार बनाए रखते हैं।
Tokens
--ayr-connect-spacing के
लिए unit-रहित 8 एक बिल्कुल मासूम स्ट्रिंग है जो उसे पढ़ने वाली हर गणना को अमान्य कर देती और
लेआउट ढहा देती, बिना कहीं किसी error के। लंबाइयों को unit दें।
Hand-Off स्क्रीन पर आपका अपना नाम
आपके उपयोगकर्ता को किसी नेटवर्क को सौंपने से पहले, हम एक छोटी स्क्रीन दिखाते हैं जिस पर लिखा होता है कि वे किसके माध्यम से कनेक्ट कर रहे हैं। दो hooks इसे आपका अपना बनाने देते हैं, और दोनों version-stable हैं।--ayr-connect-partner-name label सेट करता है। यह एकमात्र token है जिसका मान टेक्स्ट है,
इसलिए इसे CSS स्ट्रिंग के रूप में quote करना होगा — बिना quote का मान अमान्य है और कुछ भी render
नहीं करता:
css के माध्यम से background-image से भरते हैं — ऐसा token जो हमारे document के अंदर से
कोई image fetch कर सके, हम स्वीकार नहीं करते, इसलिए request आपके लिखे किसी rule से आती है, आपके
हमें दिए किसी मान से नहीं।
[data-ayr-connect-partner-mark] और [data-ayr-connect-partner-name] नीचे दी गई custom-CSS
चेतावनी के अपवाद हैं: ये दोनों selectors contract का हिस्सा हैं और हम इन्हें versions के
आर-पार बनाए रखते हैं।कस्टम CSS
css एक ऐसी स्ट्रिंग लेता है जो हर फ़्रेम के अंदर लागू होती है, उन मामलों के लिए जिन्हें tokens
कवर नहीं करते।
appearance और css को बिल्कुल फ़्रेमों की तरह अपनाते हैं, ताकि आपका
उपयोगकर्ता किसी फ़्लो के बीच में हमारे neutral डिफ़ॉल्ट प्रकट होते न देखे।
Ship करने से पहले जानने योग्य
जिस पॉपअप का सेशन समाप्त हो गया है वह error नहीं, cancelled रिपोर्ट करता है
जिस पॉपअप का सेशन समाप्त हो गया है वह error नहीं, cancelled रिपोर्ट करता है
popup() से खोले गए पॉपअप को यह नहीं बताया जा सकता कि token क्यों ठुकराया गया — ऐसा कहने के
लिए उसे ऐसे origin पर भरोसा करना होगा जिसे उसने अभी validate नहीं किया है, जिसकी अनुमति हमारा
security model नहीं देता। इसलिए मृत token ले जाने वाला पॉपअप बंद हो जाता है और error के बजाय
reason: "popupClosed" के साथ cancelled के रूप में सामने आता है।व्यवहार में यह दुर्लभ है: silent refresh से पहले खोला गया पॉपअप काम करता रहता है, क्योंकि उसने
खुलते समय अपना token validate कर लिया था। यदि आपको अस्पष्टीकृत popupClosed परिणाम दिखें, तो
जाँचें कि आपका session endpoint ताज़ा सेशन लौटा रहा है।प्रति instance एक सेशन, प्रति mount एक नहीं
प्रति instance एक सेशन, प्रति mount एक नहीं
allowedSocial — तो किसी mount से
उसे संकीर्ण करने की अपेक्षा करने के बजाय अपने सेशन के साथ दूसरा init चलाएँ।फ़्रेम केवल आपके घोषित origin पर render होते हैं
फ़्रेम केवल आपके घोषित origin पर render होते हैं
origin ले जाता है जिस पर आपका पेज चलता है, और फ़्रेम कुछ भी render करने से पहले
उसे embed करने वाले पेज की तुलना उस मान से करता है। कहीं और embed किया गया फ़्रेम खाली रहता है
और कोई events नहीं भेजता। register करने के लिए कोई allowlist नहीं है और configure करने के लिए
कुछ नहीं — सेशन बनाते समय सही origin भेजें।ऊँचाई आपके लिए संभाली जाती है, और वह कोई event नहीं है
ऊँचाई आपके लिए संभाली जाती है, और वह कोई event नहीं है
आवश्यकताएँ
- Max Pack। विजेट सेशन एक connect-mode सेशन है, और Max Pack के बिना
एक बनाने पर
code: 504लौटता है। यदि आपको बिना Max Pack वाले अकाउंट पर connect mode सक्षम कराना हो तो support से संपर्क करें। - हर सेशन पर एक
origin— ठीक वही origin जिस पर आपका पेज चलता है। इसे छोड़ने परcode: 505लौटता है; ऐसा मान जोhttpsorigin, custom scheme, याhttp://localhostनहीं है,code: 506लौटाता है। - सेशन पर कोई
networkनहीं। वह पैरामीटर सेशन को इसके बजाय डायरेक्ट मोड बना देता है, और direct-mode सेशन का URL वह नहीं है जिसकी script अपेक्षा करती है।