SubSovereign na Webie i React Native — przewodnik integracji

Ten przewodnik dotyczy JavaScriptowego/TypeScriptowego SDK, które działa w trzech miejscach z jednej biblioteki: React Native (iOS + Android), React Native TV oraz web (z Stripe). Przekształca twoją aplikację z „nie mam pojęcia, kto mi zapłacił” do „moja aplikacja odblokowuje odpowiednie funkcje dla odpowiedniego użytkownika, zweryfikowane na moim własnym serwerze”.

Co SubSovereign robi dla Ciebie

Twoi użytkownicy subskrybują przez sklep z aplikacjami (Apple, Google) lub, na stronie internetowej, przez Stripe. SubSovereign udziela odpowiedzi na jedno pytanie dla twojej aplikacji, niezawodnie: co ten użytkownik faktycznie opłacił?

• Twoja aplikacja pyta SubSovereign o uprawnienia użytkownika — dostęp, który został odblokowany.
• Weryfikacja potwierdzenia zakupu odbywa się po stronie serwera, bezpośrednio ze sklepem (lub Stripe), więc sfałszowany klient nie może podrobić subskrypcji.
• Płatna ścianka jest konfigurowana zdalnie, więc możesz zmieniać ceny, okresy próbne i treści bez ponownego wdrażania.
• Jest samodzielnie hostowany: działa na twojej infrastrukturze, dane twoich użytkowników pozostają u Ciebie, i nie ma udziału w przychodach — zatrzymujesz 100% tego, co płacą twoi użytkownicy.

Nigdy nie ufaj klientowi. Klient pyta; serwer decyduje.

Zanim zaczniesz

Będziesz potrzebować działającego serwera SubSovereign, zarejestrowanej aplikacji w panelu (dostarczającej ci appId i klucz API), oraz poziomów dostępu (tierów, np. pro) utworzonych i powiązanych z produktami, które kupują twoi użytkownicy — produktami App Store / Google Play dla React Native lub cenami Stripe dla strony internetowej. Obsługę zakupu wykonuj normalnie (biblioteki zakupów w aplikacji na React Native, Stripe Checkout/Billing na stronie internetowej); SubSovereign weryfikuje i rejestruje go później.

Krok 1 — Zainstaluj SDK

npm install @subsovereign/js-sdk

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

Krok 2 — Skonfiguruj raz, przy uruchomieniu aplikacji

SubSovereign.configure({
  apiKey:  'YOUR_APP_API_KEY',                  // z panelu
  appId:   'your-app-id',                       // z panelu
  baseUrl: 'https://subs.yourdomain.com/api/v1', // TWÓJ samodzielnie hostowany serwer
  userId:  currentUser.id,                      // twój własny stabilny identyfikator użytkownika
  locale:  'en',                                // język użytkownika
});

Użyj stabilnego userId dla zalogowanego użytkownika — tej samej wartości wszędzie, aby dostęp podążał za nim między urządzeniami i platformami. Uruchom ponownie configure, jeśli zaloguje się inny użytkownik.

Krok 3 — Sprawdź, do czego użytkownik ma dostęp

Pełny obraz dostarcza checkEntitlements():

try {
  const result = await SubSovereign.checkEntitlements();
  if (result.hasAccess) unlockProFeatures();
  else showFreeExperience();
} catch (err) {
  // Pozostaw użytkownika na ostatnio znanym dostępie i spróbuj ponownie później.
  console.warn('Sprawdzanie uprawnień nie powiodło się:', err);
}

Do prostego zabezpieczenia istnieje pomocnicza metoda hasAccess(), która domyślnie blokuje (zwraca false) w przypadku błędu sieciowego, aby chwilowa usterka nigdy nie odblokowała płatnych funkcji:

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

Każde uprawnienie w result.entitlements zawiera accessLevelId, isActive, expiresAt, willRenew oraz store. result.fromCache ma wartość true, jeśli odpowiedź pochodziła z ostatnio znanego cache podczas krótkiej awarii.

Krok 4 — Sprzedawaj subskrypcję

Pokaż płatną ściankę

const paywall = await SubSovereign.getPaywallConfig('web'); // lub 'ios' | 'android' | 'firetv' | 'roku'
if (paywall) renderPaywall(paywall);   // nagłówek, funkcje, produkty…
else renderFallbackPaywall();

Ukończ zakup, a następnie zweryfikuj go

Zrealizuj zakup w sposób typowy dla platformy, a następnie przekaż wynik do SubSovereign, aby serwer zweryfikował go i przyznał poziom dostępu. Wybierz wywołanie, które pasuje do miejsca, w którym odbył się zakup:

// 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' });

Każda metoda zwraca true po tym, jak serwer potwierdził zakup. Uruchom ponownie checkEntitlements() i odblokuj.

Przełączniki funkcji

Wdrażaj funkcje z poziomu serwera bez ponownego wdrażania:

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

Krok 5 — Prywatność: RODO i CCPA

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

await SubSovereign.requestErasure();            // "zapomnij mnie"
const myData = await SubSovereign.exportMyData(); // eksport danych
await SubSovereign.setDoNotSell(true);          // sygnał CCPA „Nie sprzedawaj” / GPC

Obsługa błędów

checkEntitlements i wywołania validate… zgłaszają wyjątki w przypadku niepowodzenia — opakuj je w try/catch i w przypadku błędu pozostaw użytkownika na ostatnio znanym dostępie i spróbuj ponownie później; nigdy nie blokuj płacącemu użytkownikowi dostępu z powodu chwilowej usterki. Pomocnicze metody (hasAccess, getPaywallConfig, getFeatureFlags) zamiast tego domyślnie blokują, zwracając false/null/{}, dzięki czemu można je bezpiecznie wywoływać w kodzie.

Najlepsze praktyki

• Sprawdzaj przy montowaniu / uruchamianiu, aby zabezpieczenie było tuż przed dotarciem użytkownika do zablokowanej funkcji.
• Sprawdzaj ponownie po zakupie, aby interfejs zaktualizował się natychmiast.
• Nigdy nie ufaj klientowi — pytaj serwer; on zweryfikował potwierdzenie.
• Jeden userId na rzeczywistego użytkownika, utrzymywany stabilnie między stroną internetową i aplikacją mobilną.

Szybki przegląd

Następne kroki

• Platformy natywne mają własne przewodniki: Android, iOS, Roku.
• Nowy w tych koncepcjach? Przeczytaj Jak działa SubSovereign.