SubSovereign — przewodnik integracji z Flutterem

Ten przewodnik dotyczy pakietu subsovereign dla Fluttera (sdk-flutter/) — klienta danych oraz natywnego widżetu płatnej ściany. Zaprojektowana w panelu SubSovereign płatna ściana renderuje się tutaj jako rzeczywisty widżet Flutter Paywall, z tej samej konfiguracji co SDK dla iOS, Androida, sieci, Reacta i React Native.

Zanim zaczniesz

Działający serwer SubSovereign, aplikacja zarejestrowana w panelu (z appId i kluczem API roli SDK), poziomy dostępu (np. pro) powiązane z produktami sklepowymi oraz opublikowana płatna ściana. Sam zakup obsługuje się standardowym wtycznym płatności (np. in_app_purchase); SubSovereign weryfikuje i rejestruje go później.

Krok 1 — Instalacja

Dodaj pakiet (ścieżka/zależność git, póki nie jest dostępny na pub.dev):

dependencies:
  subsovereign:
    path: ../sdk-flutter   # or a git dependency

import 'package:subsovereign/subsovereign.dart';

Krok 2 — Konfiguracja raz, przy uruchomieniu aplikacji

SubSovereign.instance.configure(SubSovereignConfig(
  apiKey:  'YOUR_SDK_KEY',
  appId:   'your-app-id',
  baseUrl: 'https://subs.yourdomain.com/api/v1', // YOUR self-hosted server
  userId:  currentUser.id,                        // your own stable user id
  locale:  'en',
));

Użyj stałego userId — tej samej wartości wszędzie, aby dostęp podążał za użytkownikiem między urządzeniami.

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

try {
  final result = await SubSovereign.instance.checkEntitlements();
  if (result.hasAccess) {
    showPremiumContent();
  } else {
    showPaywall();
  }
} on SubSovereignException catch (e) {
  // Keep the user on their last-known access and retry later.
  debugPrint('Entitlement check failed: $e');
}

Krok 4 — Pokaż płatną ścianę i sprzedaj

final config = await SubSovereign.instance.getPaywallConfig(platform: 'android');

Paywall(
  config: config,
  onSelectProduct: (productId) => buy(productId), // your billing plugin
)

Po pomyślnym zakupie należy zweryfikować go po stronie serwera, a następnie ponownie sprawdzić i odblokować:

final granted = await SubSovereign.instance.validateGooglePurchase(
  purchaseToken: purchase.verificationData.serverVerificationData,
  productId: purchase.productID,
  accessLevelId: 'pro',
);
if (granted) {
  final result = await SubSovereign.instance.checkEntitlements();
  if (result.hasAccess) unlockProFeatures();
}

Prywatność (RODO)

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

Przycisk odstąpienia od umowy (Compliance Passport)

Jeśli sprzedajesz subskrypcje konsumentom z UE przez internet, dyrektywa (UE) 2023/2673 wymaga wyraźnie oznaczonej funkcji odstąpienia:

WithdrawalButton(subscriptionId: sub.id)

Pokazuje on widoczny przycisk, potwierdza jednokrotnie i wysyła idempotentnie (ponowna próba sieciowa nigdy nie utworzy dwóch odstąpień). W przypadku interfejsów użytkownika dostosowanych indywidualnie użyj SubSovereign.instance.withdraw(subscriptionId: …) oraz getWithdrawalConfig().

Szybki przegląd

Następne kroki

• Działający przykład znajdziesz w sdk-flutter/example/.
• Nowy w tych koncepcjach? Przeczytaj Jak działa SubSovereign.