SubSovereign वेब घटक — एकीकरण मार्गदर्शिका (Vue, Svelte, Angular, सामान्य HTML)

यह मार्गदर्शिका sdk-web/ को कवर करती है — फ्रेमवर्क-अज्ञेय ब्राउज़र SDK। यह एक साधारण fetch-आधारित डेटा क्लाइंट के साथ दो वेब घटकों प्रदान करता है: <subsovereign-paywall> और <subsovereign-withdrawal>। ये किसी भी साइट — Vue, Svelte, Angular, या सामान्य HTML पृष्ठ — में बिना किसी बिल्ड चरण और बिना निर्भरताओं के काम करते हैं। (React में निर्माण कर रहे हैं? React मार्गदर्शिका का उपयोग करें।)

शुरू करने से पहले

एक चलता हुआ SubSovereign सर्वर, डैशबोर्ड में पंजीकृत ऐप (एक appId और एक SDK-भूमिका API कुंजी), और एक प्रकाशित पे-वाल।

चरण 1 — लोड और कॉन्फ़िगर करें

<script type="module">
  import { SubSovereign } from './sdk-web/src/index.js'; // importing registers the elements

  SubSovereign.configure({
    apiKey:  'YOUR_SDK_KEY',
    appId:   'your-app-id',
    baseUrl: 'https://subs.yourdomain.com/api/v1', // YOUR self-hosted server
    userId:  currentUser.id,                        // your own stable user id
    locale:  'en',
  });
</script>

चरण 2 — उपयोगकर्ता की पहुंच जांचें

const { hasAccess } = await SubSovereign.checkEntitlements();
if (hasAccess) showPremiumContent();
else showPaywall();

एक साधारण द्वार के लिए hasAccess() है, जो वैकल्पिक रूप से एक नामित पहुंच स्तर के लिए है। यह असफल बंद (fail closed) होता है: नेटवर्क त्रुटि पर यह false लौटाता है, ताकि कोई भी गड़बड़ी गलती से सशुल्क सामग्री अनलॉक न कर सके।

if (await SubSovereign.hasAccess('pro')) showPremiumContent();

checkEntitlements() विफल होने पर अपवाद फेंकता है, ताकि आप उपयोगकर्ता को उनके अंतिम ज्ञात पहुंच पर रख सकें; hasAccess() कभी अपवाद नहीं फेंकता। वह चुनें जिसका विफल व्यवहार आप चाहते हैं।

चरण 3 — पे-वाल दिखाएं और बिक्री करें

<subsovereign-paywall id="pw"></subsovereign-paywall>

<script type="module">
  const pw = document.getElementById('pw');
  pw.config = await SubSovereign.getPaywallConfig(); // platform defaults to 'web'
  pw.addEventListener('select-product', (e) => {
    startCheckout(e.detail.productId);               // wire to your checkout
  });
</script>

आकार देना आपकी वेबसाइट का काम है। डिफ़ॉल्ट चौड़ाई 420px है; इसे CSS कस्टम गुण (कस्टम गुण शैडो DOM को भेदते हैं) से चौड़ा करें और/या इसे समान रूप से स्केल करें:

subsovereign-paywall { --ss-paywall-max-width: 900px; transform: scale(1.4); }

खरीदारी प्रदान करना: इस SDK में क्लाइंट-साइड validate… कॉल नहीं है। अपने प्रदाता के साथ चेकआउट पूरा करें, सर्वर-साइड अनुज्ञप्ति प्रदान करें — आपका बैकएंड आपके SubSovereign सर्वर को कॉल करता है, या हस्ताक्षरित अपना स्वयं का बिलिंग पुल (POST /entitlements/external) — फिर पुनः जांचें:

const again = await SubSovereign.checkEntitlements();
if (again.hasAccess) unlock();

फीचर फ्लैग

सर्वर से सुविधाओं को बिना किसी तैनाती के रोल आउट करें। असफल बंद होता है: नेटवर्क त्रुटि पर आपको {} मिलता है, इसलिए हर फ्लैग बंद पढ़ा जाता है।

const flags = await SubSovereign.getFeatureFlags(); // { newPlayer: true, ... }
if (flags.newPlayer) showNewPlayer();

AI उत्तर-इंजन एट्रिब्यूशन (GEO)

यदि आप अधिग्रहण/GEO सुविधाओं का उपयोग करते हैं, तो ट्रैक करें कि आगंतुक कहां से आए — AI रेफरर केवल लैंडिंग पृष्ठ पर मौजूद होता है, और उपयोगकर्ता आईडी केवल साइन-अप के बाद मौजूद होती है, इसलिए यह दो-चरणीय स्टैश-और-फ्लश है:

import { ssCaptureLanding } from '@subsovereign/web';

// On every page of your marketing site, ONCE THE VISITOR HAS ACCEPTED YOUR CONSENT BANNER:
onConsentAccepted(() => ssCaptureLanding());

// …later, the moment the user signs up / signs in, after SubSovereign.configure():
await SubSovereign.recordAttributionTouch();

SDK विज़िटर के डिवाइस पर कुछ भी संग्रहीत नहीं करता जब तक आप ssCaptureLanding() को कॉल नहीं करते। पैकेज आयात करने से कुछ भी लिखा नहीं जाता। स्टैश (रेफरर + UTM टैग) जीडीपीआर के तहत व्यक्तिगत डेटा है और ईप्राइवेसी के तहत संग्रहण है, इसलिए इसे कब कैप्चर करना है, यह आपका सहमति निर्णय है — इसे अपने बैनर के स्वीकृति हैंडलर से कॉल करें। कैप्चर के बिना, recordAttributionTouch() केवल वही रिपोर्ट करता है जो साइन-अप पृष्ठ स्वयं देख सकता है — उस URL पर UTM टैग, और एक रेफरर यदि वह आपकी अपनी साइट नहीं है — इसलिए किसी पूर्व लैंडिंग पृष्ठ से AI या खोज रेफरल एट्रिब्यूट नहीं होता। यह कैप्चर न करने की कीमत है, और यह आगंतुक का विकल्प है।

recordAttributionTouch() स्टैश्ड पहले लैंडिंग को भेजता है (यह वर्तमान पृष्ठ को हरा देता है), स्टैश को केवल सफल भेजने के बाद ही साफ करता है ताकि बाद में लॉगिन पुनः प्रयास करे, और कभी अपवाद नहीं फेंकता। यदि आपकी लैंडिंग पृष्ठ configure() (कोई उपयोगकर्ता नहीं वाला स्थिर विपणन साइट) को कॉल नहीं कर सकते, तो ssFlushAttribution(userId, { apiUrl, apiKey }) वही भेजता है लेकिन स्पष्ट क्रेडेंशियल्स के साथ — या window.SS_API_URL और window.SS_API_KEY सेट करें।

आपकी वेबसाइट के ओरिजिन को सर्वर के ALLOWED_ORIGINS में होना चाहिए, अन्यथा ब्राउज़र चुपचाप कुछ भी रिपोर्ट नहीं करेगा।

गोपनीयता (जीडीपीआर और सीसीपीए)

await SubSovereign.recordConsent({ purpose: 'analytics', granted: true });

await SubSovereign.requestErasure();               // "forget me" — GDPR Art. 17
const myData = await SubSovereign.exportMyData();  // data export — GDPR Art. 20
await SubSovereign.setDoNotSell(true);             // CCPA "Do Not Sell" / GPC signal

तीन गोपनीयता कॉल विफल होने पर अपवाद फेंकते हैं (ApiError, जिसमें .status होता है)। कानूनी अधिकार का प्रयोग करने वाले उपयोगकर्ता को यह बताया जाना चाहिए कि यह पूरा नहीं हुआ — त्रुटि पकड़ें और ऐसा कहें; कभी भी मूक सफलता न दिखाएं। बिलिंग रिकॉर्ड जीडीपीआर अनुच्छेद 17(3)(b) के तहत सर्वर द्वारा रखे जाते हैं और गुमनाम कर दिए जाते हैं।

EU निकासी बटन (अनुपालन पासपोर्ट)

<subsovereign-withdrawal subscription-id="SUB_ID" appearance="auto"></subsovereign-withdrawal>

स्पष्ट लेबल वाला बटन → एक बार पुष्टि → आइडेमपोटेंट सबमिट → स्वीकृति, निर्देशिका (EU) 2023/2673 के अनुसार। कस्टम UI के लिए: SubSovereign.withdraw(subscriptionId, opts) और SubSovereign.getWithdrawalConfig()।

दिखावट — light, dark या auto (डिफ़ॉल्ट), और कुछ और नहीं। डायलॉग स्वयं का कार्ड और स्वयं की पाठ प्रस्तुत करता है, इसलिए यह किसी भी होस्ट पृष्ठ पर पठनीय है; auto विज़िटर के ब्राउज़र सेटिंग (prefers-color-scheme) का अनुसरण करता है, और विशेषता को किसी भी समय बदला जा सकता है — कार्ड पुनः पेंट होता है। जानबूझकर कोई रंग पास करने का तरीका नहीं है: यह एक वैधानिक नोटिस है, और शब्दावली और रंग तय हैं ताकि हर किरायेदार के हर ग्राहक के लिए यह समान पढ़ा जाए। शब्द आपकी सर्वर से ग्राहक की भाषा में आते हैं (configure() में locale); पुराने सर्वर के साथ वे खाली होने के बजाय अंग्रेजी में वापस आ जाते हैं।

यह घटक withdrawal-shown, withdrawal-submitted (विवरण: रसीद) और withdrawal-error (विवरण: { reason, status? }) उत्सर्जित करता है, आपके विश्लेषण के लिए। यदि आप subscription-id भूल जाते हैं, तो ग्राहक अनूदित त्रुटि देखता है और आपको एक कंसोल त्रुटि और एक withdrawal-error घटना मिलती है। यदि घटक अपने सेटिंग लोड नहीं कर सकता (गलत कुंजी, गलत ऐप आईडी, आपका सर्वर इस पृष्ठ के ओरिजिन को अस्वीकार कर रहा है), तो ग्राहक को अभी भी बटन दिखाई देता है — अंग्रेजी में — और आपको console.warn मिलता है जिसमें संभावित कारण का नाम होता है, साथ ही एक withdrawal-error घटना reason: 'config-unavailable' और, यदि उपलब्ध हो, HTTP status (एक अस्वीकृत ओरिजिन या गलत URL का कोई नहीं)। हर वातावरण में इस घटना को सुनें: यही वह तरीका है जिससे आप जानेंगे कि जर्मन ग्राहकों को अंग्रेजी दिखाई दे रही है। ध्यान दें कि यह लोड होते ही फायर होता है, किसी ग्राहक क्रिया से पहले — इसे असफल रद्दीकरण के रूप में गिनें नहीं। गलत कॉन्फ़िगरेशन डेवलपर के लिए कभी मूक नहीं होता और ग्राहक को कभी दिखाई नहीं देता।

त्वरित संदर्भ

अगले चरण

• React ऐप्स: React मार्गदर्शिका। डेटा-परत गहन जानकारी: वेब और React Native।
• अवधारणाओं से परिचित नहीं हैं? SubSovereign कैसे काम करता है पढ़ें।