Verwalten von Abonnements unter iOSPrivate Vorschau
Akzeptieren Sie wiederkehrende Zahlungen und verwalten Sie Berechtigungen mit dem BillingSDK für iOS.
Akzeptieren Sie Abonnement-Zahlungen, lassen Sie Kunden ihre Abonnements verwalten und verwalten SieBerechtigungen direkt in Ihrer iOS-App mit demBillingSDK für iOS. Das SDK bietet vordefinierte Nutzeroberfläche-Komponenten zum Anzeigen von Kaufschaltflächen, zum Präsentieren des Kundenportals sowie zum Überprüfen der Berechtigungen für Gate-Premium-Funktionen.
Bevor Sie beginnen
Um das BillingSDK für iOS zu verwenden, benötigen Sie Folgendes:
- Ein Backend-Server zum Erstellen von Kunden-Sitzungen
- Ein Stripe-Konto mit Zugriff auf die private Vorschau
- iOS 15.0 oder höher und macOS 12.0 oder höher
- Xcode 15.0 oder höher
Sie werden Folgendes entwickeln
Dieser Leitfaden bietet Informationen zu den folgenden Vorgehensweisen:
- Richten Sie einen Server Endpoint ein, um Kundensitzugngen zu erstellen
- Installieren und Konfigurieren des BillingSDK für iOS
- Anzeigen von Kauf-Schaltflächen für Abonnement-Käufe
- Überprüfen von Berechtigungen für Gate-Premium-Funktionen
- Präsentieren des Kundenportals für die Abonnement-Verwaltung
- Behandeln von Fehlern und Verwalten des Sitzungsstatus
Eine vollständige Beispiel-App finden Sie in der BillingSDK für das iOS-Repository.
Einrichten Ihres BackendsServer
Erstellen Sie ein Server-Endpoint zumGenerieren von Kundensitzungen für authentifizierte Nutzer/innen. Diese Sitzungen authentifizieren Ihre iOS-App sicher mit den Abrechnungs-APIs von Stripe.
Erstellen Sie einen Endpoint der Kundensitzung
Der Endpoint muss folgende Anforderungen erfüllen:
- Überprüfen, ob die/der Nutzer/in authentifiziert ist
- Erstellen oder Abrufen der Stripe Kunden-ID für die Nutzerin / den Nutzer
- Erstellen Sie eine Kundensitzung mit aktivierten erforderlichen Komponenten
- Geben Sie die Sitzungsdetails an Ihre App zurück
Hier ist ein Beispiel für eine Implementierung:
import 'dotenv/config'; import express from 'express'; import Stripe from 'stripe'; const stripe = new Stripe(process.env.STRIPE_SECRET_KEY || '', { apiVersion: '2025-07-30.basil', }); const app = express(); app.use(express.json()); app.post('/authenticate', async (req, res) => { try { // Replace with your auth; return 401 if the user is not logged in const user = authUser(req); if (!user) { res.status(401).json({ error: { type: 'no_session_present' } }); return; } const customerSession = await stripe.customerSessions.create({ customer: user.stripeCustomerId, components: { buy_button: { enabled: true }, active_entitlements: { enabled: true }, customer_portal: { enabled: true }, } as any, }); res.json({ clientSecret: customerSession.client_secret, expiresAt: customerSession.expires_at, customer: customerSession.customer as string, }); } catch (err) { res.status(500).json({ error: { message: 'Internal server error' } }); } }); app.listen(3000);
Format der Antwort
Der Endpoint muss die folgenden Felder zurückgeben, um eine erfolgreiche Authentifizierung zu gewährleisten:
| Feld | Typ | Beschreibung |
|---|---|---|
clientSecret | Zeichenfolge | Der geheime Schlüssel der Kundensitzung, der zum Authentifizieren des SDK verwendet wird |
expiresAt | Zahl | Ablaufzeitstempel in Sekunden seit Epoch |
customer | Zeichenfolge | Die Stripe-Kunden-ID |
Wenn die Authentifizierung fehlschlägt, geben Sie HTTP 401 zurück, um den nicht authentifizierten Status des SDK auszulösen.
Installieren und Konfigurieren des SDKiOS
Das BillingSDK für iOS bietet eine native iOS-Oberfläche für die Abonnementverwaltung und die Zugriffssteuerung auf Funktionen.
Hinzufügen des SDK zu Ihrem Projekt
Installieren Sie während der privaten Vorschau das BillingSDK-Paket:
- Öffnen Sie Ihr Projekt in Xcode
- Wählen Sie Datei → Paketabhängigkeiten hinzufügen aus.
- Tippen Sie
https://github.in das Feld Paket-URL suchen oder eingeben eincom/stripe-samples/billing-ios-sdk - Wählen Sie
BillingSDKund klicken Sie auf Paket hinzufügen
Konfigurieren des SDK
Initialisieren Sie das SDK in einer freigegebenen Klasse, um die Einrichtung und Authentifizierung des BillingSDK durchzuführen:
import Foundation import BillingSDK import SwiftUI class BillingManager { static let shared = BillingManager() public let billing: BillingSDK private init() { // Initialize with your publishable key and set how long entitlements can be stale before needing to refresh. let configuration = BillingSDK.Configuration( publishableKey: "pk_test_…", maximumStaleEntitlementsDuration: TimeInterval(60 * 5) ) self.billing = BillingSDK(configuration: configuration) // Set up authentication (see below for implementation) setupCustomerSessionProvider() // Add entitlement change listener (see below for implementation) setupEntitlementListener() } }
Hinweis
Das SDK kümmert sich intern um die Threadsicherheit – Sie können seine Methoden sicher von jedem Thread aus aufrufen.
Einrichten des Anbieters für Kundensitzungen
Fügen Sie die Authentifizierungsmethode Ihrem Abrechnung-Manager hinzu:
import Foundation import BillingSDK extension BillingManager { func setupCustomerSessionProvider() { billing.setCustomerSessionProvider { [weak self] in await self?.fetchCustomerSession() } } private func fetchCustomerSession() async -> UBCustomerSessionDetails? { // Configure request to your backend endpoint guard let url = URL(string: "https://your-backend.example.com/customer-session") else { print("Invalid URL") return nil } var request = URLRequest(url: url) request.httpMethod = "POST" request.setValue("application/json", forHTTPHeaderField: "Content-Type") // Send any additional headers needed to authenticate the user, for example, an auth token. request.setValue("Bearer \(authToken)", forHTTPHeaderField: "Authorization") do { // Make the request let (data, response) = try await URLSession.shared.data(for: request) guard let httpResponse = response as? HTTPURLResponse else { print("Invalid response format") return nil } switch httpResponse.statusCode { case 200: // Parse the successful response let decoder = JSONDecoder() decoder.dateDecodingStrategy = .secondsSince1970 return try decoder.decode(UBCustomerSessionDetails.self, from: data) case 401: // User not authenticated - SDK will enter unauthenticated state print("Authentication required") return nil default: print("Unexpected status code: \(httpResponse.statusCode)") return nil } } catch { print("Session provider error: \(error.localizedDescription)") return nil } } // Call this method when your user signs out func handleSignOut() async { await billing.reset() // Clear session data and caches } }
Hinweis
Das BillingSDK ruft Ihren Sitzungsanbieter automatisch auf, wenn es sich bei Stripe authentifizieren muss. Wenn der Anbieter nil zurückgibt, geht das SDK in einen nicht authentifizierten Zustand über.
Schaltflächen zum Kauf von Abonnements anzeigeniOS
Kauf-Schaltflächen bieten ein vordefiniertes Nutzeroberfläche-Element, mit dem Kunden Abonnements erwerben können. Jede Schaltfläche ist mit einem bestimmten Produkt und Preis in Ihrem Stripe-Konto verknüpft.
Erstellen Sie Kauf-Schaltfächen im Dashboard
Folgen Sie den Anweisungen in diesem Leitfaden, um Kauf-Schaltflächen im Dashboard zu erstellen. Wenn Sie die Funktionalität zur Berechtigungsprüfung verwenden möchten, stellen Sie sicher, dass die von Ihnen erstellten Produkte über angehängte Berechtigungen verfügen.
Anzeigen einer Schaltfläche „Kaufen“
import SwiftUI import BillingSDK struct SubscriptionView: View { @State private var buyButton: BuyButton? @State private var isLoading = true @State private var errorMessage: String? // Replace with your buy button ID from the Dashboard let buttonId = "buy_btn_1Abcdef123456" var body: some View { VStack { if isLoading { ProgressView("Loading subscription options...") } else if let buyButton = buyButton { // Display the prebuilt buy button UI // Alternatively the BuyButton class also provides all the data to render // a custom UI element. buyButton.view() .frame(height: 56) .padding(.horizontal) } else if let errorMessage = errorMessage { Text("Error: \(errorMessage)") .foregroundColor(.red) Button("Retry") { loadBuyButton() } } } .onAppear { loadBuyButton() } } func loadBuyButton() { isLoading = true errorMessage = nil Task { do { // Fetch the button from Stripe buyButton = try await BillingManager.shared.billing.getBuyButton(id: buttonId) isLoading = false } catch { errorMessage = "Failed to load buy button" isLoading = false } } } }
Hinweis
„Kaufen“-Schaltflächen funktionieren auch, wenn Nutzer/innen nicht authentifiziert sind. Das SDK erstellt bei Bedarf während des Kaufs einen neuen Stripe-Kunden.
Überprüfen und Validieren von BerechtigungeniOS
Mit Berechtigungen können Sie den Zugriff auf Premium-Funktionen basierend auf den aktiven Abonnements einer Kundin oder eines Kunden regeln.
Überprüfen einer bestimmten Berechtigung
Überprüfen, ob ein/e Nutzer/in Zugriff auf eine bestimmte Funktion hat:
func checkPremiumAccess() async { do { let hasPremiumAccess = try await BillingManager.shared.billing.hasEntitlement(lookupKey: "premium_tier") if hasPremiumAccess { // User has premium access - enable features unlockPremiumFeatures() } else { // User doesn't have access - show upsell showPremiumUpsell() } } catch { showErrorMessage("Couldn't verify entitlements status") } }
Abrufen aller aktiven Berechtigungen
Rufen Sie alle Berechtigungen ab, auf die die Kundin / der Kunde Zugriff hat:
func loadUserEntitlements() async { do { // Force refresh ensures we get the latest data from the server let entitlements = try await BillingManager.shared.billing.getActiveEntitlements(forceRefresh: true) // Map entitlements to app features let features = entitlements.map { $0.lookupKey } updateAvailableFeatures(features) } catch { handleError(error) } }
Überwachen von Berechtigungsänderungen
Richten Sie einen Listener ein, der Sie benachrichtigt, wenn sich Berechtigungen ändern:
import Foundation import BillingSDK extension BillingManager { func setupEntitlementListener() { billing.onEntitlementsChanged { updatedEntitlements in // Update UI based on new entitlements DispatchQueue.main.async { self.updateAppFeatures(based: updatedEntitlements) self.refreshUI() } } } }
Hinweis
Wenn keine Sitzung vorhanden ist, getActiveEntitlements() wird ein leerer Array zurückgegeben.
Präsentieren des KundenportalsiOS
Über das Kundenportal können Abonnenten ihre Abonnements, Zahlungsmethoden und Abrechnungsdaten verwalten.
Zeigen Sie das Kundenportal an
Präsentieren Sie das Portal, wenn Nutzer/innen ihr Abonnement verwalten müssen:
func manageSubscriptionTapped() { Task { do { let portal = try await BillingManager.shared.billing.getCustomerPortal() // Show portal within your app (recommended) portal.presentCustomerPortal(from: self) } catch { if let billingError = error as? BillingSDKError { switch billingError { case .unauthenticated: // User needs to log in first showLoginPrompt() default: // Handle other errors showErrorMessage("Could not load subscription management") } } else { showErrorMessage("Could not load subscription management") } } } }
Warnung
Für das Kundenportal ist eine aktive authentifizierte Sitzung erforderlich. Wenn die/der Nutzer/in nicht angemeldet ist, löst das SDK einen.-Fehler aus.
Externe Umleitung (optional)
Sie können das Portal auch in einem Browser öffnen:
let portal = try await BillingManager.shared.billing.getCustomerPortal() portal.redirectToCustomerPortal() // Opens in default browser
Verwaltung von SitzungeniOS
Verwaltung von Sitzungen
Setzen Sie das SDK zurück, wenn sich Benutzer abmelden, um Sitzungsdaten und Caches zu löschen:
func signOut() async { // Clear your app's auth state UserDefaults.standard.removeObject(forKey: "auth_token") // Reset the BillingSDK state await BillingManager.shared.billing.reset() // Navigate to login screen showLoginScreen() }
Ihre Integration testen
Verwenden Sie während der Entwicklung Ihre Sandbox API Schlüssel und Sandbox Kunden-IDs, um echte Gebühren zu vermeiden.
Test-Szenarien
Testen Sie die folgenden häufigen Szenarien:
| Szenario | Schritte |
|---|---|
| Kauf eines neuen Abonnements | Einer/einem neuen Nutzer/in eine „Kaufen“-Schaltfläche anzeigen |
| Abonnementverwaltung | Verwenden des Kundenportals zum Ändern von Plänen |
| Überprüfung der Berechtigung | Überprüfen einer Premium-Funktion mithasEntitlement |
| Fehlerbehebung | Testen Sie die Funktion mit ungültigen Schlüsseln oder abgelaufenen Sitzungen |
| Abmeldungsablauf | Überprüfen Sie, dass billing. die zwischengespeicherte Daten löscht |