# Отслеживание подписок из App Store

<Aside type="caution" icon="setting" title="Требуется помощь разработчика">
Для настройки этой интеграции вам потребуется помощь команды разработчиков. Пожалуйста, поделитесь с ними этим руководством.
</Aside>

## Обзор интеграции

[App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications) — это межсерверный сервис Apple, который в реальном времени отправляет на ваш бэкенд сообщение при каждом изменении статуса подписки.

Подключив App Store Server Notifications к Pushwoosh, вы сможете реагировать на весь жизненный цикл подписки, включая покупки, продления, отмены, проблемы с оплатой, истечение срока действия и возвраты средств — без создания собственной бэкенд-инфраструктуры. Каждый раз, когда статус подписки в учетной записи App Store пользователя меняется, Apple уведомляет Pushwoosh, а Pushwoosh вызывает соответствующее событие [`PW_Subscription*`](#tracked-events) в профиле пользователя.

<Aside type="note">
Эта интеграция поддерживает **подписки для iOS** (App Store Server Notifications V2). Чтобы отслеживать подписки для Android, см. [отслеживание подписок в Google Play](/ru/product/integrations/google-play-subscription-tracking/).
</Aside>

### Тип интеграции

**Источник:** App Store Server Notifications отправляются из Apple в Pushwoosh.

### Отслеживаемые события

Pushwoosh сопоставляет каждое поддерживаемое уведомление App Store с единым набором событий `PW_Subscription*`, чтобы вы могли запускать кампании на любом этапе жизненного цикла подписки.

| Событие | Срабатывает, когда |
| ----- | ---------- |
| `PW_SubscriptionStart` | Пользователь покупает подписку в первый раз. |
| `PW_SubscriptionRenew` | Подписка автоматически продлевается на новый расчетный период. |
| `PW_SubscriptionCancel` | Пользователь отключает автопродление. Подписка остается активной до истечения срока ее действия. |
| `PW_SubscriptionResume` | Пользователь снова включает автопродление или повторно подписывается до истечения срока действия подписки. |
| `PW_SubscriptionBillingIssue` | Платеж за продление не прошел, и подписка переходит в период повторных попыток списания средств Apple. |
| `PW_SubscriptionRecovered` | Ранее неудачное продление проходит успешно, и подписка снова становится активной. |
| `PW_SubscriptionExpired` | Срок действия подписки полностью истек, и она больше не активна. |
| `PW_SubscriptionRefund` | Apple возвращает средства за покупку или отзывает доступ. |

Каждое событие несет в себе одни и те же атрибуты:

- **productID:** идентификатор продукта подписки в App Store.
- **expiresAt:** время окончания текущего оплаченного периода в виде временной метки Unix в секундах. Включается, когда Apple предоставляет эту информацию.

<details>

<summary>Как события соотносятся с уведомлениями App Store Server</summary>

Для разработчиков, проверяющих интеграцию, каждое событие Pushwoosh соответствует этим значениям `notificationType` (и `subtype`) App Store:

| Событие Pushwoosh | `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` |

Другие типы уведомлений, такие как повышение цен, изменение тарифа, приостановка и запросы на использование, подтверждаются, но не регистрируют событие.

</details>


### Как это работает

1. Статус подписки в учетной записи App Store пользователя меняется (покупка, продление, отмена и т. д.).
2. Apple отправляет App Store Server Notification (V2) на ваш URL-адрес уведомлений Pushwoosh.
3. Pushwoosh декодирует подписанные данные и считывает `appAccountToken` из транзакции.
4. Pushwoosh находит устройство, HWID которого совпадает с этим токеном, находит привязанного к нему пользователя и регистрирует соответствующее событие `PW_Subscription*` для этого пользователя.

<Aside type="caution" title="Важно">
Сопоставление транзакции App Store с пользователем Pushwoosh зависит от `appAccountToken`. Если ваше приложение не устанавливает этот токен во время покупки, Pushwoosh получает уведомление, но **событие не регистрируется**. См. [как установить `appAccountToken`](#set-appaccounttoken-to-the-devices-pushwoosh-hwid).
</Aside>

### Сценарии использования

**Возвращение уходящих подписчиков:** Отключение автопродления не прекращает доступ немедленно. Подписка остается активной до конца оплаченного периода, и это ваше окно возможностей, чтобы вернуть пользователя. При событии `PW_SubscriptionCancel` запустите [Customer Journey](/ru/product/customer-journey/pushwoosh-journey-overview/) с push-уведомлением для удержания, [сообщением по электронной почте](/ru/product/messaging-channels/emails/) о функциях, которые они потеряют, или [in-app сообщением](/ru/product/messaging-channels/in-apps/) со скидкой на продление до истечения доступа.

**Онбординг новых подписчиков:** Запустите приветственную серию при событии `PW_SubscriptionStart`, чтобы помочь пользователям быстрее извлечь пользу из своего тарифа и подготовить почву для продления.

**Восстановление неудачных платежей:** Когда срабатывает `PW_SubscriptionBillingIssue`, это означает, что платеж за продление не прошел, и подписка находится в окне повторных попыток Apple. Предложите пользователю обновить способ оплаты, прежде чем он потеряет доступ, и отправьте сообщение при событии `PW_SubscriptionRecovered`, чтобы подтвердить, что проблема решена.

**Повторное вовлечение неактивных пользователей:** Начните кампанию по реактивации при событии `PW_SubscriptionExpired` с предложением для вернувшихся клиентов, которые полностью ушли.


## Настройка интеграции

### Установите appAccountToken равным HWID устройства в Pushwoosh

Pushwoosh идентифицирует нужного пользователя по **HWID** устройства, поэтому ваше приложение должно прикреплять HWID устройства Pushwoosh в качестве `appAccountToken` при покупке подписки через StoreKit.

По умолчанию Pushwoosh iOS SDK использует `identifierForVendor` (IDFV) устройства в качестве HWID. IDFV уже является `UUID`, что точно соответствует формату, требуемому Apple для `appAccountToken`. Затем Pushwoosh автоматически определяет пользователя, привязанного к этому устройству, так что это работает независимо от того, назначаете ли вы свои собственные User ID с помощью `setUserId`.

<Tabs>
<TabItem label="StoreKit 2">
```swift
// Прикрепите HWID устройства Pushwoosh (IDFV по умолчанию) в качестве 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 должен быть строкой UUID для заполнения appAccountToken
let payment = SKMutablePayment(product: product)
payment.applicationUsername = UIDevice.current.identifierForVendor?.uuidString
SKPaymentQueue.default().add(payment)
```
</TabItem>
</Tabs>

<Aside type="caution">
Если ваше приложение переопределяет HWID Pushwoosh (например, с помощью модуля постоянного HWID [`PushwooshKeychain`](/ru/developer/pushwoosh-sdk/ios-sdk/ios-keychain/) или пользовательского значения), установите `appAccountToken` равным этому же HWID. Токен должен совпадать с HWID устройства в Pushwoosh, иначе событие не может быть атрибутировано.
</Aside>

### Найдите код вашего приложения Pushwoosh

Откройте ваше приложение в панели управления Pushwoosh. Ваш **код приложения** (формат `XXXXX-XXXXX`) отображается под названием проекта в боковой панели.

Код приложения понадобится вам для создания URL-адреса уведомлений.

### Добавьте URL-адрес уведомлений в App Store Connect

1. В [App Store Connect](https://appstoreconnect.apple.com/) перейдите в **Apps → ваше приложение → App Information** (в разделе *General*) и прокрутите до **App Store Server Notifications**.
2. Выберите уведомления **Version 2**.
3. Установите и **Production Server URL**, и **Sandbox Server URL** на:

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

4. Замените `YOUR_APPLICATION_CODE` на код приложения из предыдущего шага. Сохраните косую черту в конце.

<Aside type="note">
Если ваша учетная запись размещена в **американском дата-центре**, используйте вместо этого `https://appstore-notifications.pushwoosh.us/appstore/YOUR_APPLICATION_CODE/`. Если вы не уверены, какой дата-центр использует ваша учетная запись, свяжитесь с вашим менеджером по работе с клиентами или [службой поддержки Pushwoosh](https://www.pushwoosh.com/contact-us/).
</Aside>

### Подтвердите события в Pushwoosh

Pushwoosh регистрирует каждое событие `PW_Subscription*` в вашем проекте при его первом возникновении с атрибутами `productID` и `expiresAt`. После теста в песочнице откройте **Audience → Events**, чтобы убедиться, что события появились. Затем они будут готовы для сегментации, статистики и Customer Journeys.

### Создайте свою кампанию

Создайте [Customer Journey](/ru/product/customer-journey/pushwoosh-journey-overview/) с [входом на основе триггера](/ru/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/) по любому событию `PW_Subscription*`, например `PW_SubscriptionCancel` для возврата или `PW_SubscriptionStart` для онбординга, и добавьте сообщения, которые вы хотите отправить.

## Тестирование

App Store Server Notifications можно вызывать в среде **Sandbox** от Apple. Для проверки интеграции:

1. Совершите покупку подписки в песочнице с установленным `appAccountToken`, как описано выше. Это вызовет `PW_SubscriptionStart`.
2. Отключите автопродление на экране управления подписками устройства. Это вызовет `PW_SubscriptionCancel`.
3. В панели управления Pushwoosh откройте профиль пользователя и перейдите в [историю событий](/ru/product/audience-data-and-segmentation/user-explorer/#events-history-tab).
4. Убедитесь, что события появляются в течение нескольких мгновений.