SubSovereign Android पर — एकीकरण गाइड

यह गाइड आपके Android ऐप (फ़ोन, टैबलेट, Android TV, या Amazon Fire TV) को "मुझे पता ही नहीं कि किसने भुगतान किया" से "मेरा ऐप सही उपयोगकर्ता के लिए सही सुविधाएँ अनलॉक करता है, जो मेरे अपने सर्वर पर सत्यापित होती हैं" तक ले जाती है। इसे शुरू से अंत तक क्रमबद्ध रूप से पालन करने के लिए लिखा गया है — सब्स्क्रिप्शन टूलिंग का पूर्व अनुभव आवश्यक नहीं है।

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

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

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

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

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

आपको चाहिए होगा:

एक चालू SubSovereign सर्वर (आपका स्व-होस्टेड deployment)। आप SDK को उसके URL पर इंगित करेंगे। अगर अभी तक नहीं है, तो पहले उसे deploy करें — इस गाइड का बाकी हिस्सा मानता है कि वह लाइव है।
डैशबोर्ड में पंजीकृत एक ऐप। SubSovereign डैशबोर्ड में एक ऐप बनाएँ। आपको दो चीज़ें मिलेंगी:
- एक appId (आपके ऐप की पहचान), और
- एक API key (वह क्रेडेंशियल जो आपका ऐप सर्वर से बात करने के लिए उपयोग करता है)।
पहुँच स्तर बनाए गए। डैशबोर्ड में, वे पहुँच स्तर (access levels) (जिन्हें टियर भी कहा जाता है) परिभाषित करें जो आपका ऐप प्रदान करता है — उदाहरण के लिए pro या premium — और प्रत्येक को उन स्टोर प्रोडक्ट IDs से जोड़ें जो आपके उपयोगकर्ता खरीदते हैं।
स्टोर बिलिंग पहले से काम कर रही हो। SubSovereign खरीदारी को सत्यापित और ट्रैक करता है; यह Google Play Billing (या Amazon IAP) की जगह नहीं लेता। उन्हें अपने ऐप में सामान्य रूप से सेट करें — SubSovereign खरीदारी सत्यापित और दर्ज करने के लिए उसके ठीक बाद आता है।

कोड की दृष्टि से आपको Kotlin और coroutines चाहिए (SDK कॉल suspend फ़ंक्शन हैं), और minSdk 21 या उससे अधिक।

चरण 1 — SDK जोड़ें

अपने मॉड्यूल के build.gradle में dependency जोड़ें:

dependencies {
    implementation 'com.subsovereign:android-sdk:1.0.0'
}

या, यदि आप शून्य dependencies पसंद करते हैं, तो SubSovereign.kt फ़ाइल को सीधे अपने प्रोजेक्ट में कॉपी करें। इसमें कोई थर्ड-पार्टी लाइब्रेरी नहीं है — केवल Android और Kotlin coroutines।

सुनिश्चित करें कि आपके ऐप के AndroidManifest.xml में इंटरनेट अनुमति है:

<uses-permission android:name="android.permission.INTERNET" />

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

SDK को एक बार कॉन्फ़िगर करें — सबसे अच्छी जगह आपका Application.onCreate() है, या उपयोगकर्ता के साइन इन करने के तुरंत बाद। आप इसे चार चीज़ें देते हैं: आपकी API key, आपका ऐप ID, इस उपयोगकर्ता के लिए एक स्थिर पहचानकर्ता, और उनकी भाषा।

import com.subsovereign.sdk.SubSovereign
import com.subsovereign.sdk.SubSovereignConfig

SubSovereign.configure(
    context,
    SubSovereignConfig(
        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, e.g. "fr"
    )
)

कुछ महत्वपूर्ण बातें:

userId आपका है। किसी साइन-इन उपयोगकर्ता के लिए जो भी स्थिर ID आपके पास पहले से है, उसका उपयोग करें। हर बार एक ही मान उपयोग करें ताकि उपयोगकर्ता की पहुँच उनके साथ सभी डिवाइस पर बनी रहे। यदि आप साइन-आउट और किसी अन्य उपयोगकर्ता के साइन-इन का समर्थन करते हैं, तो नए userId के साथ फिर से configure कॉल करें।
baseUrl आपके सर्वर पर इंगित करता है। SDK में डिफ़ॉल्ट एक placeholder है — इसे अपने SubSovereign deployment पर सेट करें।
locale सर्वर को उपयोगकर्ता की भाषा में पेवॉल टेक्स्ट वापस करने देता है।

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

उपयोगकर्ता ने क्या अनलॉक किया है यह जानने के लिए checkEntitlements() कॉल करें। यह हर cold start पर करें, और किसी भी खरीदारी के तुरंत बाद फिर से करें। चूँकि यह एक suspend फ़ंक्शन है, इसे coroutine से कॉल करें:

import com.subsovereign.sdk.SubSovereignResult
import kotlinx.coroutines.launch

lifecycleScope.launch {
    when (val result = SubSovereign.checkEntitlements()) {
        is SubSovereignResult.Success -> {
            val ent = result.data
            if (ent.hasAccess) {
                unlockProFeatures()          // the user has paid access
            } else {
                showFreeExperience()         // free tier / show a paywall
            }
        }
        is SubSovereignResult.Error -> {
            // Network hiccup or server error. Fail gracefully — usually keep the
            // user on whatever access they last had, and try again later.
            Log.w("MyApp", "Entitlement check failed: ${result.message}")
        }
    }
}

hasAccess त्वरित हाँ/नहीं है। यदि आपके ऐप में एक से अधिक टियर हैं, तो result.data.entitlements के अंदर देखें — प्रत्येक आपको बताता है कि कौन सा पहुँच स्तर सक्रिय है:

val isPro = result.data.entitlements.any { it.isActive && it.accessLevelId == "pro" }

हर पात्रता में expiresAt, willRenew, और वह store भी होता है जहाँ से वह आई — "आपकी सब्स्क्रिप्शन इस तारीख को नवीनीकृत होगी…" जैसे संदेशों के लिए उपयोगी। यदि सर्वर कुछ देर के लिए अनुपलब्ध था और SDK ने अपनी अंतिम ज्ञात स्थिति से उत्तर दिया, तो fromCache का मान true होगा।

चरण 4 — सब्स्क्रिप्शन बेचें

पेवॉल दिखाएँ

अपने ऐप में कीमतें हार्ड-कोड करने की बजाय सर्वर से पेवॉल प्राप्त करें। इससे आप रिलीज़ किए बिना कोई सेल चला सकते हैं या ट्रायल अवधि बदल सकते हैं:

lifecycleScope.launch {
    when (val result = SubSovereign.getPaywallConfig()) {
        is SubSovereignResult.Success -> renderPaywall(result.data) // headline, features, products…
        is SubSovereignResult.Error   -> renderFallbackPaywall()    // your built-in default
    }
}

PaywallConfig आपको एक headline, subheadline, features की सूची, प्रस्तावित products (प्रत्येक में displayPrice, period, trialDays, और एक वैकल्पिक badge), call-to-action टेक्स्ट, और footer टेक्स्ट देता है। आप असली स्क्रीन बनाते हैं — SubSovereign बताता है उसमें क्या लिखना है।

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

Google Play Billing के माध्यम से खरीदारी बिल्कुल सामान्य तरीके से चलाएँ। जब Google आपको purchaseToken वापस दे, उसे SubSovereign को दें ताकि सर्वर सीधे स्टोर के साथ रसीद सत्यापित कर सके और पहुँच स्तर प्रदान कर सके:

lifecycleScope.launch {
    val ok = SubSovereign.validateGooglePurchase(
        purchaseToken  = purchase.purchaseToken, // from Google Play Billing
        productId      = purchase.products.first(),
        accessLevelId  = "pro",                   // which tier this product grants
    )
    when (ok) {
        is SubSovereignResult.Success ->
            if (ok.data) SubSovereign.checkEntitlements() // re-check, then unlock
        is SubSovereignResult.Error ->
            showTryAgain(ok.message)
    }
}

यही पूरा भरोसे का मॉडल है: खरीदारी तभी वास्तविक है जब सर्वर ने उसकी पुष्टि की हो।

Amazon Fire TV पर

Fire TV ऐप Google Play की बजाय Amazon के In-App Purchasing का उपयोग करते हैं। यह वही पैटर्न है — आपको Amazon से receiptId मिलता है और आप Amazon variant कॉल करते हैं:

SubSovereign.validateAmazonPurchase(
    receiptId     = receipt.receiptId,
    productId     = receipt.sku,
    accessLevelId = "pro",
)

चरण 5 — सहमति दर्ज करें (GDPR)

यदि आप सहमति संग्रहित करते हैं (एनालिटिक्स, व्यक्तिगत सामग्री, आदि), तो उपयोगकर्ता की पसंद दर्ज करें ताकि आपके पास एक ऑडिट ट्रेल हो:

SubSovereign.recordConsent(purpose = "analytics", granted = true)

jurisdiction डिफ़ॉल्ट रूप से "GDPR" है और policyVersion "1.0" — यदि वे अलग हों तो अपने मान पास करें।

परिणामों के साथ काम करना

हर SDK कॉल एक SubSovereignResult लौटाती है, जो या तो Success (डेटा के साथ) या Error (एक संदेश और जहाँ प्रासंगिक हो, HTTP स्टेटस code के साथ) होती है। यह जानबूझकर है: नेटवर्क कॉल विफल होती हैं, और आपके ऐप को क्रैश करने की बजाय यह तय करना चाहिए कि क्या करना है। एक सरल आदत:

Success पर — डेटा का उपयोग करें।
Error पर — उसे लॉग करें, उपयोगकर्ता को उनकी अंतिम ज्ञात पहुँच पर रखें, और बाद में पुनः प्रयास करें। किसी भुगतान करने वाले उपयोगकर्ता को क्षणिक नेटवर्क समस्या के कारण कभी लॉक आउट न करें।

सर्वोत्तम अभ्यास

Cold start पर जाँचें। ऐप लॉन्च होने पर checkEntitlements() कॉल करें ताकि उपयोगकर्ता किसी लॉक फ़ीचर तक पहुँचने से पहले गेटिंग सही हो।
खरीदारी के बाद पुनः जाँचें। किसी सफल validate… कॉल के ठीक बाद, checkEntitlements() फिर चलाएँ ताकि UI तुरंत नई पहुँच दर्शाए।
क्लाइंट पर कभी भरोसा न करें। ऐप में "is pro" स्टोर करके उसे सत्य न मानें। सर्वर से पूछें; सर्वर ने रसीद सत्यापित की है।
प्रति वास्तविक उपयोगकर्ता एक userId। इसे स्थिर रखें ताकि पहुँच उपयोगकर्ता के साथ सभी डिवाइस पर बनी रहे, और साइन-इन उपयोगकर्ता बदलने पर पुनः कॉन्फ़िगर करें।
Coroutines व्यवस्थित रखें। ये suspend फ़ंक्शन हैं — इन्हें lifecycleScope या viewModelScope से कॉल करें ताकि वे स्क्रीन के साथ रद्द हो जाएँ।

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

आप यह करना चाहते हैं…	कॉल करें
SDK सेट करें	`SubSovereign.configure(context, config)`
उपयोगकर्ता ने क्या अनलॉक किया देखें	`checkEntitlements()` → `EntitlementResult`
रिमोट पेवॉल दिखाएँ	`getPaywallConfig()` → `PaywallConfig`
Google Play खरीदारी सत्यापित करें	`validateGooglePurchase(token, productId, accessLevelId)`
Amazon (Fire TV) खरीदारी सत्यापित करें	`validateAmazonPurchase(receiptId, productId, accessLevelId)`
GDPR सहमति दर्ज करें	`recordConsent(purpose, granted)`

अगले चरण

अपने अन्य प्लेटफ़ॉर्म पर भी यही करें — iOS, Web/JavaScript, और Roku SDK एक जैसे ढाँचे का पालन करते हैं।
अवधारणाओं में नए हैं? SubSovereign कैसे काम करता है पढ़ें।