# Tracking von App-Store-Abonnements

<Aside type="caution" icon="setting" title="Hilfe von Entwicklern erforderlich">
Sie benötigen Hilfe von Ihrem Entwicklungsteam, um diese Integration einzurichten. Bitte teilen Sie diese Anleitung mit ihnen.
</Aside>

## Integrationsübersicht

[App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications) ist Apples Server-zu-Server-Dienst, der Ihrem Backend eine Echtzeitnachricht sendet, wann immer sich der Status eines Abonnements ändert.

Durch die Verbindung von App Store Server Notifications mit Pushwoosh können Sie auf den gesamten Abonnement-Lebenszyklus reagieren, einschließlich Käufen, Verlängerungen, Kündigungen, Abrechnungsproblemen, Ablaufdaten und Rückerstattungen – ohne eine eigene Backend-Infrastruktur aufbauen zu müssen. Wann immer sich der Status eines Abonnements im App-Store-Konto eines Benutzers ändert, benachrichtigt Apple Pushwoosh, und Pushwoosh löst das entsprechende [`PW_Subscription*`](#tracked-events)-Ereignis im Benutzerprofil aus.

<Aside type="note">
Diese Integration unterstützt **iOS-Abonnements** (App Store Server Notifications V2). Informationen zum Tracking von Android-Abonnements finden Sie unter [Tracking von Google-Play-Abonnements](/de/product/integrations/google-play-subscription-tracking/).
</Aside>

### Integrationstyp

**Quelle:** App Store Server Notifications werden von Apple an Pushwoosh gesendet.

### Verfolgte Ereignisse

Pushwoosh ordnet jede unterstützte App-Store-Benachrichtigung einem einheitlichen `PW_Subscription*`-Ereignissatz zu, sodass Sie Kampagnen in jeder Phase des Abonnement-Lebenszyklus auslösen können.

| Ereignis | Wird ausgelöst, wenn |
| ----- | ---------- |
| `PW_SubscriptionStart` | Ein Benutzer kauft das Abonnement zum ersten Mal. |
| `PW_SubscriptionRenew` | Das Abonnement verlängert sich automatisch für einen neuen Abrechnungszeitraum. |
| `PW_SubscriptionCancel` | Ein Benutzer deaktiviert die automatische Verlängerung. Das Abonnement bleibt bis zum Ablauf aktiv. |
| `PW_SubscriptionResume` | Ein Benutzer aktiviert die automatische Verlängerung erneut oder abonniert erneut, bevor das Abonnement abläuft. |
| `PW_SubscriptionBillingIssue` | Eine Verlängerungszahlung schlägt fehl und das Abonnement tritt in Apples Abrechnungs-Wiederholungszeitraum ein. |
| `PW_SubscriptionRecovered` | Eine zuvor fehlgeschlagene Verlängerung wird durchgeführt und das Abonnement ist wieder aktiv. |
| `PW_SubscriptionExpired` | Das Abonnement ist vollständig abgelaufen und nicht mehr aktiv. |
| `PW_SubscriptionRefund` | Apple erstattet den Kauf oder widerruft den Zugriff. |

Jedes Ereignis trägt die gleichen Attribute:

- **productID:** die App-Store-Produktkennung des Abonnements.
- **expiresAt:** wann der aktuelle bezahlte Zeitraum endet, als Unix-Zeitstempel in Sekunden. Enthalten, wenn Apple es bereitstellt.

<details>

<summary>Wie Ereignisse den App Store Server Notifications zugeordnet werden</summary>

Für Entwickler, die die Integration überprüfen: Jedes Pushwoosh-Ereignis entspricht diesen App-Store-`notificationType`- (und `subtype`-)Werten:

| Pushwoosh-Ereignis | `notificationType` / `subtype` |
| --------------- | ------------------------------ |
| `PW_SubscriptionStart` | `SUBSCRIBED` / `INITIAL_BUY` |
| `PW_SubscriptionRenew` | `DID_RENEW` |
| `PW_SubscriptionCancel` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_DISABLED` |
| `PW_SubscriptionResume` | `DID_CHANGE_RENEWAL_STATUS` / `AUTO_RENEW_ENABLED`, `SUBSCRIBED` / `RESUBSCRIBE` |
| `PW_SubscriptionBillingIssue` | `DID_FAIL_TO_RENEW` |
| `PW_SubscriptionRecovered` | `DID_RENEW` / `BILLING_RECOVERY` |
| `PW_SubscriptionExpired` | `EXPIRED` |
| `PW_SubscriptionRefund` | `REFUND`, `REVOKE` |

Andere Benachrichtigungstypen wie Preiserhöhungen, Planänderungen, „on-hold“-Status und Verbrauchs-Anfragen werden bestätigt, lösen aber kein Ereignis aus.

</details>


### So funktioniert es

1. Der Status eines Abonnements ändert sich im App-Store-Konto eines Benutzers (ein Kauf, eine Verlängerung, eine Kündigung usw.).
2. Apple sendet eine App Store Server Notification (V2) an Ihre Pushwoosh-Benachrichtigungs-URL.
3. Pushwoosh dekodiert die signierte Nutzlast und liest den `appAccountToken` aus der Transaktion.
4. Pushwoosh sucht das Gerät, dessen HWID mit diesem Token übereinstimmt, findet den damit verbundenen Benutzer und postet das entsprechende `PW_Subscription*`-Ereignis für diesen Benutzer.

<Aside type="caution" title="Wichtig">
Die Zuordnung zwischen einer App-Store-Transaktion und einem Pushwoosh-Benutzer basiert auf dem `appAccountToken`. Wenn Ihre App dieses Token zum Zeitpunkt des Kaufs nicht setzt, empfängt Pushwoosh die Benachrichtigung, aber es wird **kein Ereignis gepostet**. Siehe [So setzen Sie `appAccountToken`](#set-appaccounttoken-to-the-devices-pushwoosh-hwid).
</Aside>

### Anwendungsfälle

**Abwandernde Abonnenten zurückgewinnen:** Das Deaktivieren der automatischen Verlängerung beendet den Zugriff nicht sofort. Das Abonnement bleibt bis zum Ende des bezahlten Zeitraums aktiv, und das ist Ihre Chance, den Benutzer zurückzugewinnen. Starten Sie bei `PW_SubscriptionCancel` eine [Customer Journey](/de/product/customer-journey/pushwoosh-journey-overview/) mit einem Retentions-Push, einer [E-Mail](/de/product/messaging-channels/emails/) über Funktionen, die sie verlieren würden, oder einer [In-App-Nachricht](/de/product/messaging-channels/in-apps/) mit einem Verlängerungsrabatt, bevor der Zugriff abläuft.

**Neue Abonnenten onboarden:** Lösen Sie bei `PW_SubscriptionStart` eine Willkommensserie aus, um Benutzern zu helfen, frühzeitig einen Mehrwert aus ihrem Plan zu ziehen und die Weichen für eine Verlängerung zu stellen.

**Fehlgeschlagene Zahlungen retten:** Wenn `PW_SubscriptionBillingIssue` ausgelöst wird, ist eine Verlängerungszahlung fehlgeschlagen und das Abonnement befindet sich im Wiederholungsfenster von Apple. Fordern Sie den Benutzer auf, seine Zahlungsmethode zu aktualisieren, bevor er den Zugriff verliert, und folgen Sie mit `PW_SubscriptionRecovered`, um zu bestätigen, sobald das Problem behoben ist.

**Abgelaufene Benutzer reaktivieren:** Starten Sie bei `PW_SubscriptionExpired` eine Reaktivierungskampagne mit einem Angebot für wiederkehrende Kunden für Abonnenten, die vollständig abgewandert sind.


## Einrichtung der Integration

### `appAccountToken` auf die Pushwoosh-HWID des Geräts setzen

Pushwoosh identifiziert den richtigen Benutzer anhand der **HWID** des Geräts. Daher muss Ihre App die Pushwoosh-HWID des Geräts als `appAccountToken` anhängen, wenn das Abonnement über StoreKit gekauft wird.

Standardmäßig verwendet das Pushwoosh iOS SDK den `identifierForVendor` (IDFV) des Geräts als HWID. IDFV ist bereits eine `UUID`, genau das Format, das Apple für `appAccountToken` verlangt. Pushwoosh löst dann automatisch den Benutzer auf, der aktuell an dieses Gerät gebunden ist, sodass dies funktioniert, unabhängig davon, ob Sie Ihre eigenen Benutzer-IDs mit `setUserId` zuweisen oder nicht.

<Tabs>
<TabItem label="StoreKit 2">
```swift
// Attach the device's Pushwoosh HWID (the default IDFV) as the appAccountToken
var options: Set<Product.PurchaseOption> = []
if let hwid = UIDevice.current.identifierForVendor {
    options.insert(.appAccountToken(hwid))
}

let result = try await product.purchase(options: options)
```
</TabItem>
<TabItem label="StoreKit 1">
```swift
// applicationUsername must be a UUID string to populate appAccountToken
let payment = SKMutablePayment(product: product)
payment.applicationUsername = UIDevice.current.identifierForVendor?.uuidString
SKPaymentQueue.default().add(payment)
```
</TabItem>
</Tabs>

<Aside type="caution">
Wenn Ihre App die Pushwoosh-HWID überschreibt (z. B. über das persistente HWID-Modul [`PushwooshKeychain`](/de/developer/pushwoosh-sdk/ios-sdk/ios-keychain/) oder einen benutzerdefinierten Wert), setzen Sie `appAccountToken` auf dieselbe HWID. Das Token muss mit der HWID des Geräts in Pushwoosh übereinstimmen, sonst kann das Ereignis nicht zugeordnet werden.
</Aside>

### Finden Sie Ihren Pushwoosh Application Code

Öffnen Sie Ihre Anwendung im Pushwoosh Control Panel. Ihr **Application Code** (Format `XXXXX-XXXXX`) wird unter dem Projektnamen in der Seitenleiste angezeigt.

Sie benötigen den Application Code, um die Benachrichtigungs-URL zu erstellen.

### Fügen Sie die Benachrichtigungs-URL in App Store Connect hinzu

1. Gehen Sie in [App Store Connect](https://appstoreconnect.apple.com/) zu **Apps → Ihre App → App-Informationen** (unter *Allgemein*) und scrollen Sie zu **App Store Server Notifications**.
2. Wählen Sie Benachrichtigungen der **Version 2** aus.
3. Setzen Sie sowohl die **Produktionsserver-URL** als auch die **Sandbox-Server-URL** auf:

```
https://appstore-notifications.pushwoosh.com/appstore/YOUR_APPLICATION_CODE/
```

4. Ersetzen Sie `YOUR_APPLICATION_CODE` durch den Application Code aus dem vorherigen Schritt. Behalten Sie den abschließenden Schrägstrich bei.

<Aside type="note">
Wenn Ihr Konto im **US-Rechenzentrum** gehostet wird, verwenden Sie stattdessen `https://appstore-notifications.pushwoosh.us/appstore/YOUR_APPLICATION_CODE/`. Wenn Sie sich nicht sicher sind, welches Rechenzentrum Ihr Konto verwendet, wenden Sie sich an Ihren Customer Success Manager oder den [Pushwoosh-Support](https://www.pushwoosh.com/contact-us/).
</Aside>

### Bestätigen Sie die Ereignisse in Pushwoosh

Pushwoosh registriert jedes `PW_Subscription*`-Ereignis in Ihrem Projekt, wenn es zum ersten Mal auftritt, mit den Attributen `productID` und `expiresAt`. Öffnen Sie nach einem Sandbox-Test **Audience → Events**, um zu überprüfen, ob die Ereignisse angezeigt werden. Sie sind dann bereit für die Segmentierung, Statistiken und Customer Journeys.

### Erstellen Sie Ihre Kampagne

Erstellen Sie eine [Customer Journey](/de/product/customer-journey/pushwoosh-journey-overview/) mit einem [triggerbasierten Eintritt](/de/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/) für ein beliebiges `PW_Subscription*`-Ereignis, z. B. `PW_SubscriptionCancel` zur Rückgewinnung oder `PW_SubscriptionStart` zum Onboarding, und fügen Sie die Nachrichten hinzu, die Sie senden möchten.

## Testen

App Store Server Notifications können in Apples **Sandbox**-Umgebung ausgelöst werden. Um die Integration zu überprüfen:

1. Tätigen Sie einen Sandbox-Abonnementkauf, bei dem `appAccountToken` wie oben beschrieben gesetzt ist. Dies löst `PW_SubscriptionStart` aus.
2. Deaktivieren Sie die automatische Verlängerung auf dem Abonnementverwaltungsbildschirm des Geräts. Dies löst `PW_SubscriptionCancel` aus.
3. Öffnen Sie im Pushwoosh Control Panel das Benutzerprofil und gehen Sie zum [Ereignisverlauf](/de/product/audience-data-and-segmentation/user-explorer/#events-history-tab).
4. Bestätigen Sie, dass die Ereignisse innerhalb weniger Augenblicke erscheinen.