SubSovereign — przewodnik integracji na Roku

Ten przewodnik przeprowadzi Cię od sytuacji „nie mam pojęcia, kto za mnie zapłacił” do stanu „mój kanał odblokowuje odpowiednie funkcje dla odpowiedniego użytkownika, zweryfikowane na moim własnym serwerze”. SDK to pojedynczy plik BrightScript i nie wymaga wcześniejszego doświadczenia z narzędziami subskrypcyjnymi.

Co SubSovereign robi dla Ciebie

Użytkownicy subskrybują przez Roku Pay (Roku Channel Store). SubSovereign wiarygodnie odpowiada na jedno pytanie dotyczące Twojego kanału: za co użytkownik faktycznie zapłacił?

• Twój kanał pyta SubSovereign o uprawnienia użytkownika — dostęp, który odblokował.
• Weryfikacja paragonu odbywa się po stronie serwera, bezpośrednio z Roku, dzięki czemu sfałszowanie klienta przez atakującego nie jest możliwe.
• Jest samodzielnie hostowany: działa na Twojej infrastrukturze, dane użytkowników pozostają u Ciebie, a nie pobieramy udziału w przychodach — zatrzymujesz 100% tego, co płacą Twoi użytkownicy.

Nie ufasz urządzeniu. Urządzenie pyta; serwer decyduje.

Przed rozpoczęciem

Będziesz potrzebować działającego serwera SubSovereign, zarejestrowanej aplikacji w panelu (dostarcza ona appId i klucz API), oraz skonfigurowanych poziomów dostępu (tierów, np. pro) powiązanych z produktami Roku Pay. Ustaw produkty w Roku Developer Dashboard i obsłuż zakup za pomocą roChannelStore jak zwykle — SubSovereign zweryfikuje i zapisze go później.

Krok 1 — Dodaj SDK

Umieść plik SubSovereign.brs w folderze source/ swojego kanału. To wszystko — bez menedżera pakietów. Połączenia HTTP używają roUrlTransfer z już dołączonym pakietem certyfikatów Roku.

Krok 2 — Konfiguracja raz, przy starcie kanału

Wywołaj SubSovereign_Configure wczesnym etapie (np. w Main), przekazując swój klucz API, identyfikator aplikacji, stały identyfikator użytkownika oraz adres URL serwera:

SubSovereign_Configure("YOUR_APP_API_KEY", "your-app-id", userId, "https://subs.yourdomain.com/api/v1")

Używaj tego samego userId za każdym razem dla danego użytkownika, aby jego uprawnienia podążały za nim między urządzeniami. (Konfiguracja jest przechowywana w m, więc skonfiguruj ją na tym samym wątku, z którego będziesz wywoływał — patrz uwaga w Kroku 6.)

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

SubSovereign_CheckEntitlements() zwraca obiekt. Odczytaj hasAccess dla szybkiej odpowiedzi tak/nie:

result = SubSovereign_CheckEntitlements()
if result.hasAccess = true
    unlockProFeatures()
else
    showFreeExperience()   ' darmowy poziom, lub wyślij do Roku Channel Store
end if

Jeśli żądanie się nie powiedzie, obiekt zostanie zwrócony z hasAccess = false i polem error — więc chwilowa awaria sieci spowoduje zablokowanie dostępu (zamknięte), nigdy przypadkowe odblokowanie.

Krok 4 — Sprzedaj subskrypcję

Zrealizuj zakup przez Roku Pay (roChannelStore) jak zwykle. Gdy Roku zwróci udaną transakcję, przekaż jej transactionId (razem z identyfikatorem produktu i poziomem dostępu, którego dotyczy) do SubSovereign, aby serwer zweryfikował ją bezpośrednio z Roku:

result = SubSovereign_ValidateRokuPurchase(transactionId, productId, "pro")
if result.granted = true
    entitlements = SubSovereign_CheckEntitlements()   ' ponowne sprawdzenie, następnie odblokowanie
    unlockProFeatures()
end if

Zakup jest realny dopiero wtedy, gdy serwer potwierdzi go z Roku.

Krok 5 — Flagi funkcjonalne i zgoda

Wdrażaj funkcje z poziomu serwera bez aktualizacji kanału:

flags = SubSovereign_GetFeatureFlags()
if flags.newPlayer = true then showNewPlayer()

Zbierz zgodę na przetwarzanie danych (fire-and-forget):

purposes = { analytics: true, marketing: false }
SubSovereign_RecordConsent(purposes, "GDPR")

Krok 6 — Uruchamiaj połączenia sieciowe poza wątkiem renderowania

SubSovereign_CheckEntitlements i SubSovereign_ValidateRokuPurchase czekają na odpowiedź serwera (do 15 sekund). Nigdy nie wywołuj ich w wątku renderowania/UI — wolna sieć spowodowałaby zawieszenie ekranu. Uruchamiaj je wewnątrz węzła Task i przekazuj wynik z powrotem do sceny:

' w funkcji węzła Task:
SubSovereign_Configure(m.top.apiKey, m.top.appId, m.top.userId, m.top.baseUrl)
m.top.result = SubSovereign_CheckEntitlements()   ' obserwowane pole, na które nasłuchuje scena

Wywołanie fire-and-forget SubSovereign_RecordConsent nie czeka na odpowiedź i można je bezpiecznie wywołać bezpośrednio.

Najlepsze praktyki

• Sprawdzaj przy uruchomieniu kanału, aby bramkowanie nastąpiło tuż przed dotarciem użytkownika do zablokowanej treści.
• Ponownie sprawdzaj po zakupie, aby interfejs natychmiast odzwierciedlał nowy dostęp.
• Nigdy nie ufaj klientowi — pytaj serwer; to on zweryfikował transakcję z Roku.
• Zawsze używaj węzła Task do wywołań uprawnień i weryfikacji.

Szybki przegląd

Następne kroki

• Inne platformy mają własne przewodniki: Android, iOS, Web / React Native.
• Nowy w temacie? Przeczytaj Jak działa SubSovereign.