App Store 구독 추적

개발자 지원 필요

이 통합을 설정하려면 개발팀의 도움이 필요합니다. 이 가이드를 개발팀과 공유해주세요.

통합 개요

App Store 서버 알림은 구독 상태가 변경될 때마다 백엔드에 실시간 메시지를 보내는 Apple의 서버 간 서비스입니다.

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

참고

이 통합은 iOS 구독(App Store 서버 알림 V2)을 지원합니다. Android 구독을 추적하려면 Google Play 구독 추적을 참조하세요.

통합 유형

소스: 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이 제공하는 경우 포함됩니다.

이벤트가 App Store 서버 알림에 매핑되는 방식

통합을 확인하는 개발자를 위해 각 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

가격 인상, 요금제 변경, 보류 및 소비 요청과 같은 다른 알림 유형은 확인되지만 이벤트를 게시하지는 않습니다.

작동 방식

1. 사용자의 App Store 계정에서 구독 상태가 변경됩니다 (구매, 갱신, 취소 등).
2. Apple이 Pushwoosh 알림 URL로 App Store 서버 알림(V2)을 보냅니다.
3. Pushwoosh는 서명된 페이로드를 디코딩하고 트랜잭션에서 appAccountToken을 읽습니다.
4. Pushwoosh는 HWID가 해당 토큰과 일치하는 기기를 조회하고, 해당 기기에 바인딩된 사용자를 찾아 해당 사용자에 대해 일치하는 PW_Subscription* 이벤트를 게시합니다.

중요

App Store 트랜잭션과 Pushwoosh 사용자 간의 일치는 appAccountToken에 의존합니다. 앱이 구매 시 이 토큰을 설정하지 않으면 Pushwoosh는 알림을 받지만 이벤트는 게시되지 않습니다. appAccountToken을 설정하는 방법을 참조하세요.

사용 사례

이탈 구독자 되찾기: 자동 갱신을 비활성화해도 즉시 접근이 종료되지는 않습니다. 구독은 유료 기간이 끝날 때까지 활성 상태로 유지되며, 이것이 사용자를 되찾을 수 있는 기회입니다. PW_SubscriptionCancel 시, Customer Journey를 시작하여 유지 푸시, 잃게 될 기능에 대한 이메일 또는 접근이 만료되기 전에 갱신 할인이 포함된 인앱 메시지를 보냅니다.

신규 구독자 온보딩: 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를 할당했는지 여부에 관계없이 작동합니다.

StoreKit 2

// 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)

StoreKit 1

// applicationUsername must be a UUID string to populate appAccountToken
let payment = SKMutablePayment(product: product)
payment.applicationUsername = UIDevice.current.identifierForVendor?.uuidString
SKPaymentQueue.default().add(payment)

주의

앱이 Pushwoosh HWID를 재정의하는 경우(예: PushwooshKeychain 영구 HWID 모듈 또는 사용자 지정 값을 통해), appAccountToken을 동일한 HWID로 설정해야 합니다. 토큰은 Pushwoosh의 기기 HWID와 일치해야 하며, 그렇지 않으면 이벤트를 귀속시킬 수 없습니다.

Pushwoosh 애플리케이션 코드 찾기

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

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

App Store Connect에 알림 URL 추가하기

1. App Store Connect에서 앱 → 해당 앱 → 앱 정보(일반 아래)로 이동하여 App Store 서버 알림으로 스크롤합니다.
2. 버전 2 알림을 선택합니다.
3. 프로덕션 서버 URL과 샌드박스 서버 URL을 모두 다음으로 설정합니다:

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

4. YOUR_APPLICATION_CODE를 이전 단계에서 얻은 애플리케이션 코드로 교체합니다. 끝에 있는 슬래시를 유지하세요.

참고

계정이 미국 데이터 센터에 호스팅된 경우, 대신 https://appstore-notifications.pushwoosh.us/appstore/YOUR_APPLICATION_CODE/를 사용하세요. 계정이 어떤 데이터 센터를 사용하는지 확실하지 않은 경우, 고객 성공 관리자 또는 Pushwoosh 지원팀에 문의하세요.

Pushwoosh에서 이벤트 확인하기

Pushwoosh는 각 PW_Subscription* 이벤트가 처음 발생할 때 productID 및 expiresAt 속성과 함께 프로젝트에 등록합니다. 샌드박스 테스트 후 Audience → Events를 열어 이벤트가 나타나는지 확인하세요. 그러면 세분화, 통계 및 Customer Journeys에 사용할 준비가 됩니다.

캠페인 구축하기

Customer Journey를 생성하고, 예를 들어 이탈 방지를 위한 PW_SubscriptionCancel 또는 온보딩을 위한 PW_SubscriptionStart와 같은 PW_Subscription* 이벤트에 트리거 기반 진입을 설정하고 보내려는 메시지를 추가하세요.

테스트

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

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