Rozpoczynanie pracy z SubSovereign

Ten przewodnik przeprowadzi Cię od zera do działającej kontroli subskrypcji w Twojej aplikacji. Jest praktycznym uzupełnieniem dokumentu Jak działa SubSovereign — przeczytaj go najpierw, jeśli chcesz poznać koncepcje.

Proces składa się z pięciu kroków: uruchomienie serwera → utworzenie aplikacji → zdefiniowanie oferowanych produktów → dodanie SDK → sprawdzanie dostępu. Pierwszy krok zajmie Ci około popołudnia; reszta to kwestia kilku minut.

Krok 1 — Uruchomienie serwera

SubSovereign jest rozwiązaniem samodzielnie hostowanym, dlatego pierwszym krokiem jest uruchomienie backendu na własnej infrastrukturze. To usługa napisana w Node.js/TypeScript, korzystająca z PostgreSQL (do przechowywania uprawnień, zdarzeń i zgód) oraz Redis (do szybkiej pamięci podręcznej uprawnień).

cd backend
cp .env.example .env
# Fill in every value in .env — database URL, store credentials, secrets.

npm install
npm run migrate      # creates the database tables
npm run build && npm start

Dla uproszczenia wdrożenia dostępna jest gotowa konfiguracja dla Northflank (backend/northflank.yml), ale równie dobrze sprawdzi się dowolny host obsługujący Node + PostgreSQL + Redis — kluczowe jest, że należy do Ciebie. Po uruchomieniu serwera zanotuj jego adres; to Twój baseUrl, z którym będą komunikować się Twoje aplikacje (np. https://subs.twojadomena.com).

Wskazówka: Utrzymuj serwer na hostingu w UK/EU. Suwerenność i GDPR są kluczowe — nie trać ich na etapie wdrażania.

Krok 2 — Utworzenie aplikacji w panelu administracyjnym

Otwórz panel administracyjny i utwórz aplikację — po jednej na każdy produkt, który publikujesz (aplikacja Android i iOS mogą korzystać z tego samego rekordu aplikacji lub z osobnych; to zależy od Ciebie). Tworzenie aplikacji daje Ci dwa niezbędne elementy:

• appId — identyfikator aplikacji dla serwera,
• klucz API — poświadczenie używane przez aplikację do uwierzytelniania wywołań SDK.

🚩 Skopiuj klucz API w momencie jego pojawienia się i przechowuj go w bezpiecznym miejscu. Jest on wyświetlany tylko raz. Przechowujemy jedynie jego skrót, dlatego nie można go wyświetlić ponownie. Jeśli go zgubisz lub dojdzie do jego wycieku, nie musisz tworzyć nowej aplikacji: otwórz aplikację w panelu sterowania, a następnie w sekcji SDK keys naciśnij New key, aby wygenerować nowy klucz, lub Revoke, aby unieważnić stary. Unieważnienie następuje natychmiast i nie może zostać cofnięte — wszystko, co nadal korzysta z tego klucza, przestanie do nas docierać w momencie potwierdzenia.

Krok 3 — Zdefiniowanie oferowanych produktów

Wciąż w panelu administracyjnym skonfiguruj rzeczy, które będą kupować Twoi użytkownicy:

1. Utwórz poziomy dostępu (nazywane również poziomami) — poziomy dostępu, jakie oferuje Twój produkt, np. pro lub premium. To nazwy, które Twoja aplikacja będzie sprawdzać.
2. Powiąż każdy poziom dostępu z produktami w sklepach. W każdym sklepie (App Store, Google Play, Amazon, Roku, Stripe) twórz subskrypcje w standardowy sposób; w SubSovereign informujesz system "ten produkt sklepu przyznaje ten poziom dostępu". To powiązanie sprawia, że zakup staje się uprawnieniem.
3. **Zaprojektuj swoją płatną ściankę — nagłówek, funkcje, ceny i długości okresów próbnych. Ponieważ jest ona dostarczana zdalnie, możesz ją zmieniać później bez konieczności aktualizacji aplikacji.

Jeśli sprzedajesz przez Stripe

Konfiguracja dostawcy płatności leży po Twojej stronie. Postępuj zgodnie z oficjalną dokumentacją Stripe, dodaj nasz adres webhooka oraz wymienione poniżej zdarzenia w panelu Stripe, zapisz swój klucz tajny Stripe na stronie swojej aplikacji i sprawdź, czy wszystko działa poprzez testowy zakup przed uruchomieniem. SubSovereign reaguje na to, co Stripe nam przekazuje.

1. W panelu Stripe dodaj punkt końcowy webhooka: <your SubSovereign server>/api/v1/webhooks/stripe?appId=<your app id>, wysyłając te zdarzenia: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.resumed, invoice.paid, invoice.payment_failed. Stripe pokaże Ci wówczas klucz tajny webhooka Stripe (whsec_…).
2. Na stronie swojej aplikacji (Aplikacje → twoja aplikacja → Dane uwierzytelniające sklepu) zapisz swój klucz tajny Stripe oraz ten klucz tajny webhooka Stripe. Bez klucza tajnego webhooka każda wiadomość Stripe zostanie odrzucona.
3. Gdy Twoja aplikacja jest połączona (Krok 4), przetestuj ją w trybie testowym Stripe: testowy zakup powinien włączyć dostęp klienta, a jego natychmiastowe anulowanie w panelu Stripe powinno ten dostęp wyłączyć. Anulowanie na koniec okresu utrzymuje dostęp do daty końcowej — to jest poprawne działanie, a nie błąd.

Jeśli na stronie Twojej aplikacji widnieje "Nie można połączyć się ze Stripe dla tej aplikacji", oznacza to, że Stripe odrzucił zapisany tam klucz tajny lub żaden nie został zapisany — dopóki problem nie zostanie naprawiony, anulowania i nieudane płatności nie zmienią dostępu Twoich klientów.

Krok 4 — Dodanie SDK do aplikacji

Zainstaluj SDK w aplikacji i skieruj je do swojego serwera. Struktura jest identyczna na wszystkich platformach — postępuj zgodnie z przewodnikiem dla wybranej technologii:

• Android / Fire TV (Kotlin)
• iOS / tvOS (Swift)
• Web / React Native (JavaScript)
• Roku (BrightScript)
• React (interfejs UI dla aplikacji webowych w React)
• React Native (klient danych + natywna płatna ścianka)
• Flutter (Dart)
• Komponent Webowy (Vue / Svelte / Angular / zwykły HTML)

Każdy przewodnik konfiguruje SDK raz, podając: Twój klucz API, appId, adres serwera baseUrl oraz stały userId dla zalogowanego użytkownika (użyj tego samego identyfikatora wszędzie, aby dostęp był spójny na różnych urządzeniach).

Krok 5 — Sprawdzanie dostępu i uruchomienie

Po skonfigurowaniu SDK aplikacja wykonuje dwie czynności:

• Przy uruchomieniu sprawdza, jakie uprawnienia ma użytkownik, i odblokowuje funkcje odpowiednio (w przewodniku dla Androida proces ten nosi nazwę checkEntitlements(); każde SDK posiada odpowiednik tej metody).
• Po zakupie przekazuje paragon do SubSovereign, aby serwer zweryfikował go bezpośrednio ze sklepem i przyznał odpowiedni poziom dostępu — następnie ponownie sprawdza i odblokowuje.

To kompletna integracja. Przed wypuszczeniem aplikacji na produkcję, sprawdź listę kontrolną:

• Serwer wdrożony na hostingu w UK/EU, migracje wykonane, dostępny z aplikacji.
• Aplikacja utworzona; klucz API przechowywany bezpiecznie; aplikacja skierowana na Twój baseUrl.
• Poziomy dostępu zdefiniowane i powiązane z rzeczywistymi produktami w sklepach, które obsługujesz.
• Płatności sklepowe (Google Play / StoreKit / Amazon / Roku / Stripe) działają w Twojej aplikacji.
• Stripe: dodany punkt końcowy webhooka z powyższymi zdarzeniami, zapisany klucz tajny i klucz tajny webhooka, testowy zakup powodujący włączenie dostępu oraz natychmiastowe anulowanie powodujące jego wyłączenie.
• Sprawdzanie uprawnień przy uruchomieniu; weryfikacja paragonu po zakupie; oba procesy przetestowane na rzeczywistym urządzeniu z rzeczywistym (sandboxowym) zakupem.
• Zgoda na przetwarzanie danych zgodnie z GDPR zebrana w miejscu jej zbierania.

Co dalej

• Poznaj model w szczegółach: Jak działa SubSovereign.
• Podłącz swoją platformę: przewodniki SDK powyżej.