SubSovereign on Web & React Native — एकीकरण गाइड

यह गाइड JavaScript/TypeScript SDK को कवर करती है, जो एक ही लाइब्रेरी से तीन जगहों पर काम करती है: React Native (iOS + Android), React Native TV, और वेब (Stripe के साथ)। यह आपके ऐप को "मुझे नहीं पता किसने भुगतान किया" से "मेरा ऐप सही उपयोगकर्ता को सही सुविधाएँ देता है, जो मेरे अपने सर्वर पर सत्यापित हैं" तक ले जाती है।

SubSovereign आपके लिए क्या करता है

आपके उपयोगकर्ता किसी ऐप स्टोर (Apple, Google) के ज़रिये, या वेब पर Stripe के ज़रिये सदस्यता लेते हैं। SubSovereign आपके ऐप के लिए एक सवाल का भरोसेमंद जवाब देता है: इस उपयोगकर्ता ने वास्तव में किस चीज़ के लिए भुगतान किया है?

• आपका ऐप SubSovereign से उपयोगकर्ता की पात्रता (entitlement) माँगता है — यानी उन्होंने जो एक्सेस अनलॉक की है।
• रसीद सत्यापन (receipt validation) सर्वर पर होता है, सीधे स्टोर (या Stripe) से, इसलिए कोई छेड़छाड़ किया गया क्लाइंट सदस्यता की नकल नहीं कर सकता।
• पेवॉल (paywall) को दूर से कॉन्फ़िगर किया जाता है, इसलिए आप कीमतें, ट्रायल और शब्दावली बिना री-डिप्लॉय के बदल सकते हैं।
• यह स्व-होस्टेड (self-hosted) है: यह आपके इन्फ्रास्ट्रक्चर पर चलता है, आपके उपयोगकर्ताओं का डेटा आपके पास रहता है, और राजस्व में कोई हिस्सेदारी नहीं होती — आपके उपयोगकर्ता जो भुगतान करते हैं उसका 100% आपका रहता है।

आप क्लाइंट पर कभी भरोसा नहीं करते। क्लाइंट पूछता है; सर्वर फ़ैसला करता है।

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

आपको एक चालू SubSovereign सर्वर, डैशबोर्ड में एक पंजीकृत ऐप (जो आपको एक appId और एक API key देगा), और आपके एक्सेस स्तर (access levels) (टियर, जैसे pro) की ज़रूरत होगी — जो उन प्रोडक्ट्स से जुड़े हों जो आपके उपयोगकर्ता खरीदते हैं: React Native के लिए App Store / Google Play प्रोडक्ट्स, या वेब के लिए Stripe की कीमतें। खरीदारी की प्रक्रिया को आप सामान्य तरीके से संभालें (React Native पर इन-ऐप परचेज़ लाइब्रेरीज़, वेब पर Stripe Checkout/Billing); SubSovereign उसके बाद उसे सत्यापित और दर्ज करता है।

चरण 1 — SDK इंस्टॉल करें

npm install @subsovereign/js-sdk

import SubSovereign from '@subsovereign/js-sdk';

चरण 2 — ऐप शुरू होने पर एक बार कॉन्फ़िगर करें

SubSovereign.configure({
  apiKey:  'YOUR_APP_API_KEY',                  // from the dashboard
  appId:   'your-app-id',                       // from the dashboard
  baseUrl: 'https://subs.yourdomain.com/api/v1', // YOUR self-hosted server
  userId:  currentUser.id,                      // your own stable user id
  locale:  'en',                                // the user's language
});

लॉग-इन उपयोगकर्ता के लिए एक स्थिर userId इस्तेमाल करें — हर जगह एक ही मान, ताकि एक्सेस उनके सभी डिवाइस और प्लेटफ़ॉर्म पर साथ चले। अगर कोई दूसरा उपयोगकर्ता साइन इन करे तो configure दोबारा चलाएँ।

चरण 3 — जाँचें कि उपयोगकर्ता क्या एक्सेस कर सकता है

पूरी जानकारी checkEntitlements() से मिलती है:

try {
  const result = await SubSovereign.checkEntitlements();
  if (result.hasAccess) unlockProFeatures();
  else showFreeExperience();
} catch (err) {
  // Keep the user on their last-known access and retry later.
  console.warn('Entitlement check failed:', err);
}

एक साधारण गेट के लिए एक सुविधाजनक हेल्पर है, hasAccess(), जो नेटवर्क एरर पर बंद रहता है (false लौटाता है) ताकि कोई छोटी-सी रुकावट कभी गलती से पेड सुविधाएँ अनलॉक न कर दे:

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

result.entitlements में हर पात्रता के साथ accessLevelId, isActive, expiresAt, willRenew, और उसका store होता है। result.fromCache तब true होता है जब किसी संक्षिप्त आउटेज के दौरान जवाब अंतिम ज्ञात कैश से आया हो।

चरण 4 — सदस्यता बेचें

पेवॉल दिखाएँ

const paywall = await SubSovereign.getPaywallConfig('web'); // or 'ios' | 'android' | 'firetv' | 'roku'
if (paywall) renderPaywall(paywall);   // headline, features, products…
else renderFallbackPaywall();

खरीदारी पूरी करें, फिर उसे सत्यापित करें

प्लेटफ़ॉर्म के सामान्य तरीके से खरीदारी करें, फिर नतीजा SubSovereign को दें ताकि सर्वर उसे सत्यापित करे और एक्सेस स्तर प्रदान करे। जहाँ खरीदारी हुई हो उसके अनुसार कॉल चुनें:

// Web (Stripe)
await SubSovereign.validateStripeSubscription({
  subscriptionId, productId, accessLevelId: 'pro',
});

// React Native — iOS (StoreKit)
await SubSovereign.validateApplePurchase({ transactionId, productId, accessLevelId: 'pro' });

// React Native — Android (Play Billing)
await SubSovereign.validateGooglePurchase({ purchaseToken, productId, accessLevelId: 'pro' });

हर कॉल true लौटाती है जब सर्वर ने खरीदारी की पुष्टि कर दी हो। इसके बाद checkEntitlements() दोबारा चलाएँ और अनलॉक करें।

फ़ीचर फ़्लैग्स

बिना डिप्लॉय के सर्वर से फ़ीचर रोल आउट करें:

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

चरण 5 — गोपनीयता: GDPR और CCPA

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

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

एरर हैंडलिंग

checkEntitlements और validate… कॉल विफल होने पर throw करती हैं — इन्हें try/catch में लपेटें और एरर पर उपयोगकर्ता को उनकी अंतिम ज्ञात एक्सेस पर रखें और बाद में दोबारा प्रयास करें; किसी भुगतान करने वाले उपयोगकर्ता को एक छोटी-सी रुकावट के कारण कभी बाहर न करें। सुविधाजनक हेल्पर्स (hasAccess, getPaywallConfig, getFeatureFlags) इसके बजाय बंद रहते हैं, false/null/{} लौटाते हैं, इसलिए इन्हें इनलाइन कॉल करना सुरक्षित है।

सर्वोत्तम तरीके

• माउंट/लॉन्च पर जाँचें ताकि उपयोगकर्ता के किसी लॉक्ड फ़ीचर तक पहुँचने से पहले गेटिंग सही हो।
• खरीदारी के बाद दोबारा जाँचें ताकि UI तुरंत अपडेट हो।
• क्लाइंट पर कभी भरोसा न करें — सर्वर से पूछें; उसने रसीद सत्यापित की है।
• हर असली उपयोगकर्ता के लिए एक userId, जो वेब और मोबाइल पर स्थिर रहे।

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

अगले कदम

• नेटिव प्लेटफ़ॉर्म के लिए अलग गाइड हैं: Android, iOS, Roku.
• अवधारणाओं से अपरिचित हैं? पढ़ें SubSovereign कैसे काम करता है।