# App Store 구독 추적

<Aside type="caution" icon="setting" title="개발자 지원 필요">
이 통합을 설정하려면 개발팀의 도움이 필요합니다. 이 가이드를 개발팀과 공유해주세요.
</Aside>

## 통합 개요

[App Store 서버 알림](https://developer.apple.com/documentation/appstoreservernotifications)은 구독 상태가 변경될 때마다 백엔드에 실시간 메시지를 보내는 Apple의 서버 간 서비스입니다.

App Store 서버 알림을 Pushwoosh에 연결하면 자체 백엔드 인프라를 구축하지 않고도 구매, 갱신, 취소, 결제 문제, 만료 및 환불을 포함한 전체 구독 수명 주기에 대응할 수 있습니다. 사용자의 App Store 계정에서 구독 상태가 변경될 때마다 Apple은 Pushwoosh에 알림을 보내고, Pushwoosh는 사용자 프로필에서 일치하는 [`PW_Subscription*`](#tracked-events) 이벤트를 발생시킵니다.

<Aside type="note">
이 통합은 **iOS 구독**(App Store 서버 알림 V2)을 지원합니다. Android 구독을 추적하려면 [Google Play 구독 추적](/ko/product/integrations/google-play-subscription-tracking/)을 참조하세요.
</Aside>

### 통합 유형

**소스:** App Store 서버 알림은 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 서버 알림에 매핑되는 방식</summary>

통합을 확인하는 개발자를 위해 각 Pushwoosh 이벤트는 다음 App Store `notificationType` (및 `subtype`) 값에 해당합니다:

| 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이 Pushwoosh 알림 URL로 App Store 서버 알림(V2)을 보냅니다.
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](/ko/product/customer-journey/pushwoosh-journey-overview/)를 시작하여 유지 푸시, 잃게 될 기능에 대한 [이메일](/ko/product/messaging-channels/emails/) 또는 접근이 만료되기 전에 갱신 할인이 포함된 [인앱 메시지](/ko/product/messaging-channels/in-apps/)를 보냅니다.

**신규 구독자 온보딩:** `PW_SubscriptionStart` 시 환영 시리즈를 트리거하여 사용자가 요금제에서 조기에 가치를 얻고 갱신을 위한 기반을 마련하도록 돕습니다.

**결제 실패 구제:** `PW_SubscriptionBillingIssue`가 발생하면 갱신 결제가 실패하고 구독이 Apple의 재시도 기간에 들어갑니다. 사용자에게 접근 권한을 잃기 전에 결제 방법을 업데이트하도록 유도하고, 문제가 해결되면 `PW_SubscriptionRecovered`로 후속 조치를 취하여 확인합니다.

**만료된 사용자 재참여:** 완전히 이탈한 구독자를 위해 `PW_SubscriptionExpired` 시 재방문 고객 제안으로 재활성화 캠페인을 시작합니다.


## 통합 설정하기

### `appAccountToken`을 기기의 Pushwoosh HWID로 설정

Pushwoosh는 기기의 **HWID**로 올바른 사용자를 식별하므로, 앱은 StoreKit을 통해 구독을 구매할 때 기기의 Pushwoosh HWID를 `appAccountToken`으로 첨부해야 합니다.

기본적으로 Pushwoosh iOS SDK는 기기의 `identifierForVendor`(IDFV)를 HWID로 사용합니다. IDFV는 이미 Apple이 `appAccountToken`에 요구하는 형식인 `UUID`입니다. 그런 다음 Pushwoosh는 현재 해당 기기에 바인딩된 사용자를 자동으로 확인하므로, `setUserId`로 자체 User ID를 할당했는지 여부에 관계없이 작동합니다.

<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">
앱이 Pushwoosh HWID를 재정의하는 경우(예: [`PushwooshKeychain`](/ko/developer/pushwoosh-sdk/ios-sdk/ios-keychain/) 영구 HWID 모듈 또는 사용자 지정 값을 통해), `appAccountToken`을 동일한 HWID로 설정해야 합니다. 토큰은 Pushwoosh의 기기 HWID와 일치해야 하며, 그렇지 않으면 이벤트를 귀속시킬 수 없습니다.
</Aside>

### Pushwoosh 애플리케이션 코드 찾기

Pushwoosh Control Panel에서 애플리케이션을 엽니다. **애플리케이션 코드**(`XXXXX-XXXXX` 형식)는 사이드바의 프로젝트 이름 아래에 표시됩니다.

알림 URL을 빌드하려면 애플리케이션 코드가 필요합니다.

### App Store Connect에 알림 URL 추가하기

1. [App Store Connect](https://appstoreconnect.apple.com/)에서 **앱 → 해당 앱 → 앱 정보**(*일반* 아래)로 이동하여 **App Store 서버 알림**으로 스크롤합니다.
2. **버전 2** 알림을 선택합니다.
3. **프로덕션 서버 URL**과 **샌드박스 서버 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](/ko/product/customer-journey/pushwoosh-journey-overview/)를 생성하고, 예를 들어 이탈 방지를 위한 `PW_SubscriptionCancel` 또는 온보딩을 위한 `PW_SubscriptionStart`와 같은 `PW_Subscription*` 이벤트에 [트리거 기반 진입](/ko/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/)을 설정하고 보내려는 메시지를 추가하세요.

## 테스트

App Store 서버 알림은 Apple의 **Sandbox** 환경에서 트리거할 수 있습니다. 통합을 확인하려면:

1. 위에서 설명한 대로 `appAccountToken`을 설정하여 샌드박스 구독 구매를 합니다. 이것은 `PW_SubscriptionStart`를 발생시킵니다.
2. 기기의 구독 관리 화면에서 자동 갱신을 비활성화합니다. 이것은 `PW_SubscriptionCancel`을 발생시킵니다.
3. Pushwoosh Control Panel에서 사용자 프로필을 열고 [Events history](/ko/product/audience-data-and-segmentation/user-explorer/#events-history-tab)로 이동합니다.
4. 잠시 후 이벤트가 나타나는지 확인합니다.