유지 혜택은 정기 결제 사용자가 Google Play에서 정기 결제를 취소하려고 할 때 할인을 표시하여 자발적 이탈을 줄이는 데 도움이 됩니다.
자격 요건을 충족하는 정기 결제 사용자가 취소를 시작하면 Google Play에서 개발자가 구성한 유지 혜택(예: '정기 결제를 유지하고 다음 2개월 동안 50% 할인받기')을 표시합니다. 정기 결제 사용자가 혜택을 수락하면 정기 결제가 취소되지 않습니다. 할인된 가격은 다음 청구일부터 적용됩니다.
이 페이지에서는 유지 혜택의 작동 방식, 구성 방법, 백엔드에서 결과 이벤트를 처리하는 방법, 테스트 방법을 설명합니다.
시작하기 전에
유지 혜택을 설정하기 전에 다음을 완료했는지 확인하세요.
- 하나 이상의 자동 갱신 기본 요금제로 정기 결제를 만들었습니다. 유지 혜택은 자동 갱신 기본 요금제에만 추가할 수 있습니다.
- 실시간 개발자 알림(RTDN)을 구성하고
purchases.subscriptionsv2.get메서드를 호출하도록 백엔드를 설정했습니다. 백엔드는 이를 사용하여 정기 결제 사용자가 유지 혜택을 수락하는 시점을 감지합니다.
Google Play는 앱 외부에서 유지 혜택을 표시하므로, 유지 혜택을 사용하기 위해 앱을 변경하거나 Google Play Billing Library 통합을 업데이트할 필요가 없습니다. 모든 통합 작업은 Google Play Console과 백엔드에서 이루어집니다.
유지 혜택 작동 방식
유지 혜택은 Google Play 정기 결제 관리(Google Play 스토어 앱 및 웹의 Google Play)에만 표시됩니다. 앱 내에 표시되지 않습니다. Google Play Billing Library는 queryProductDetailsAsync() 결과에서 유지 혜택을 반환하지 않으므로 ProductDetails.getSubscriptionOfferDetails()에 포함되지 않으며 launchBillingFlow()를 통해 판매할 수 없습니다. 앱에서 딥 링크를 사용하여 정기 결제 사용자를 Google Play 정기 결제 센터 또는 특정 정기 결제로 보내 정기 결제를 관리하거나 취소할 수 있도록 하는 경우, 정기 결제 사용자가 취소를 시작할 때 유지 혜택이 표시될 수 있습니다.
다음 단계에서는 정기 결제 사용자가 취소를 시도할 때 어떤 일이 발생하는지 설명합니다.
- 정기 결제 사용자가 Google Play에서 정기 결제를 열고 취소를 시작합니다.
Google Play는 정기 결제 사용자가 혜택에 설정한 자격 요건 규칙 또는 해당 정기 결제 사용자를 대상으로 혜택을 타겟팅했는지에 따라 유지 혜택 중 하나를 받을 수 있는지 확인합니다.
정기 결제 사용자가 자격 요건을 충족하는 경우 Google Play에서 취소 대신 유지 혜택을 표시할 수 있습니다. Google Play에서는 지역 규정 준수 요구사항과 같은 추가 플랫폼 수준 검사도 수행하므로 자격 기준을 충족한다고 해서 혜택이 표시되는 것은 아닙니다. Google Play에 혜택이 표시되면 정기 결제 사용자는 다음 중 하나를 수행할 수 있습니다.
- 혜택 수락: 정기 결제 사용자가 한 번의 탭으로 수락합니다. 정기 결제는 활성 상태로 유지되고 자동 갱신됩니다. 정기 결제 사용자에게 즉시 청구되지 않으며 할인된 가격은 다음 결제 기간부터 적용됩니다.
- 취소 계속: 정기 결제 사용자가 혜택을 거부하고 표준 취소 흐름을 완료합니다. 일반적인
SUBSCRIPTION_CANCELED알림을 받습니다. 자세한 내용은 취소를 참고하세요.
정기 결제 사용자가 혜택을 수락하거나 취소하지 않고 취소 과정을 종료하면 정기 결제가 변경되지 않습니다. 이는 Google Play 스토어 앱과 웹의 Google Play 모두에 적용됩니다. 유지 혜택을 수락하지 않고 보기만 하면 혜택의 신청 한도에 반영되지 않으며 혜택 간 대기 기간이 시작되지 않습니다. Google Play는 혜택을 표시할 때와 정기 결제 사용자가 혜택을 수락할 때 신청 한도를 확인합니다. 수락된 혜택은 정기 결제가 할인된 가격으로 갱신될 때 신청 한도에 반영됩니다. 혜택 간 대기 기간은 동일한 기본 요금제의 이전 유지 혜택의 할인 기간이 종료될 때 시작됩니다. 정기 결제 사용자가 여전히 자격 요건을 충족하는 경우 다음에 취소하려고 할 때 혜택이 다시 표시될 수 있습니다.
예약된 요금제 전환
정기 결제 사용자가 유지 혜택을 수락하면 Google Play는 이를 정기 결제 사용자의 기존 구매에 대한 예약된 요금제 전환으로 모델링합니다. 이는 새로운 구매 흐름이 필요하고 새로운 구매 토큰을 생성하는 지연된 교체와 다릅니다. 유지 혜택을 사용하면 정기 결제 사용자는 동일한 purchaseToken를 유지하고 향후 결제 약관만 변경됩니다.
정기 결제 사용자가 혜택을 수락하면 Google Play는 다음을 실행합니다.
SUBSCRIPTION_PLAN_TRANSITION_UPDATED(21) RTDN을 백엔드로 전송합니다.SubscriptionPurchaseV2리소스에서 영향을 받는 광고 항목의autoRenewingPlan필드에planTransitionDetails객체를 추가합니다.
이러한 이벤트를 처리하는 방법에 관한 자세한 내용은 백엔드에서 유지 혜택 이벤트 처리를 참고하세요.
자격 요건
다음이 모두 충족되는 한 정기 결제는 다음 갱신 전에 언제든지 유지 혜택을 받을 수 있습니다.
- 정기 결제가 활성 상태이며 자동 갱신됩니다. 유예 기간, 계정 보류 또는 일시중지 상태의 정기 결제는 유지 혜택을 받을 수 없습니다.
- 구독이 단일 구독입니다. 부가기능이 포함된 정기 결제에는 유지 혜택이 지원되지 않습니다.
- 정기 결제에서 할부 기본 요금제를 사용하지 않습니다. 할부 기본 요금제는 유지 혜택을 받을 수 없습니다.
- 다음 결제는 정기적으로 반복되는 기본 요금제 가격으로 이루어집니다. 정기 결제 사용자가 무료 체험판 또는 신규 할인 가격 단계에 있는 경우, 예정된 갱신이 정가로 이루어지는 해당 단계의 마지막 결제 기간에만 혜택을 사용할 수 있습니다.
- 정기 결제 사용자가 이전에 수락한 유지 제안의 할인 결제 기간에 있지 않습니다. 유지 혜택의 할인 단계에 있는 정기 결제 사용자는 정기 결제가 일반 기본 요금제 가격으로 갱신될 때까지 다른 유지 혜택을 신청할 수 없습니다.
- 정기 결제에 대기 중인 예약된 요금제 전환이 없습니다. 정기 결제에는 대기 중인 예약된 요금제 전환이 최대 하나 있을 수 있으며, 이는
IN_PROGRESS상태의planTransitionDetails객체입니다. 예를 들어 아직 적용되지 않은 유지 혜택을 이미 수락한 정기 결제 사용자는 다른 혜택을 받을 수 없습니다. - 정기 결제에 미확인 가격 변경이 없습니다.
- 유지 혜택의 할인된 가격이 정기 결제 사용자의 다음 기본 요금제 갱신 가격보다 작거나 같습니다.
- 정기 결제 사용자가 오퍼에 구성된 자격 요건 규칙을 충족합니다. 사용자별 유지 혜택의 경우
activateOfferTargeting메서드를 사용하여 정기 결제 타겟팅을 활성화했습니다.
유지 혜택 구성
Google Play Console에서 또는 Google Play Developer API를 사용하여 유지 혜택을 만들 수 있습니다. 각 유지 혜택은 다음 타겟팅 모드 중 하나를 사용합니다.
- 규칙 기반 타겟팅: Google Play는 개발자가 설정한 자격 요건 규칙(예: 최소 유료 구독 기간)에 따라 자격 요건을 충족하는 유료 구독자를 결정합니다.
- 사용자별 타겟팅: 백엔드에서 특정 정기 결제를 타겟팅하여 혜택을 볼 수 있는 정기 결제 사용자를 결정합니다.
기본 요금제는 동일한 국가 또는 지역에서 활성 상태인 유지 혜택을 두 개 이상 가질 수 있습니다. 정기 결제 사용자가 두 개 이상의 혜택을 받을 수 있는 경우 Google Play는 취소 과정에서 최대 하나의 유지 혜택을 표시합니다. Google Play는 다음 순서로 혜택을 선택합니다.
- 타겟팅 모드: 사용자별 타겟팅 혜택(
retentionPerUserRule)은 규칙 기반 혜택(retentionRule)보다 항상 우선 적용됩니다. 규칙 기반 혜택의 할인율이 더 높은 경우에도 마찬가지입니다. - 할인율: 동일한 타겟팅 모드를 사용하는 적격 혜택 중에서 Google Play는 표시된 할인율이 가장 높은 혜택을 표시합니다.
- 할인 가격: 혜택의 할인율이 동일한 경우 Google Play는 할인 가격이 가장 낮은 혜택을 표시합니다.
- 혜택 ID: 혜택이 여전히 연결되어 있는 경우 Google Play는
offerId가 알파벳순으로 마지막에 오는 혜택을 표시합니다.
Play Console에서 유지 혜택 만들기
Google Play Console에서 유지 혜택을 만들려면 다음 단계를 따르세요.
- Google Play를 통한 수익 창출 > 제품 > 정기 결제로 이동합니다.
- 정기 결제를 선택한 다음 혜택을 추가할 기본 요금제를 선택합니다.
- 기존 정기 결제 사용자가 취소하려고 시도 중에 대한 혜택을 추가합니다.
- 사용자 집단 수준 유지 혜택 또는 사용자 수준 유지 혜택을 선택합니다.
Play Developer API로 유지 혜택 만들기
프로그래매틱 방식으로 유지 혜택을 만들고 업데이트할 수도 있습니다. 오퍼를 만들려면 monetization.subscriptions.basePlans.offers.create 메서드를 호출합니다. 기존 혜택을 업데이트하려면 monetization.subscriptions.basePlans.offers.patch 또는 monetization.subscriptions.basePlans.offers.batchUpdate 메서드를 호출합니다. 세 가지 메서드 모두 retentionRule, retentionPerUserRule, startTime, endTime 필드를 지원합니다. SubscriptionOffer 객체에서 다음 필드를 설정합니다.
offerId: 고유한 유지 혜택 ID입니다.targeting:retentionRule를 혜택을 받을 수 있는 사용자를 정의하는RetentionTargetingRule객체로 설정합니다. 사용 가능한 필드는 보관 자격 요건 규칙 설정을 참조하세요. 대신 백엔드에서 자격 요건을 충족하는 정기 결제 사용자를 선택하려면retentionPerUserRule를 설정합니다. 자세한 내용은 특정 정기 결제 사용자를 대상으로 한 유지 혜택을 참고하세요.phases[]: 유지 혜택은 단일 가격 책정 단계만 지원합니다. 이 단계에서 다음 필드를 설정합니다.recurrenceCount: 할인이 지속되는 결제 기간 수(1~52)입니다.recurrenceCount가 1보다 크면duration단계는 기본 요금제의 결제 기간과 같아야 합니다.regionalConfigs[]:relativeDiscount를 0보다 크고 1보다 작은 분수로 할인에 설정합니다. 예를 들어 50% 할인의 경우0.5를 사용합니다. 유지 혜택은relativeDiscount만 지원합니다. 고정 가격(price), 정액 할인(absoluteDiscount), 무료(free) 단계는 지원되지 않습니다.
startTime: 선택사항. 자격 요건을 충족하는 정기 결제 사용자가 유지 혜택을 사용할 수 있게 되는 시간입니다(RFC 3339 타임스탬프). 이 필드를 설정해도 혜택이 활성화되지 않습니다. 이 필드를 설정하지 않으면 상태에 따라 오퍼를 사용할 수 있습니다.endTime: 선택사항. 혜택 상태와 관계없이 유지 혜택이 더 이상 제공되지 않는 시간입니다(RFC 3339 타임스탬프). 이 필드를 설정하지 않으면 오퍼에 종료일이 없습니다. 이 필드를 설정하는 경우 미래의 시간이고startTime보다 이후여야 합니다.
monetization.subscriptions.basePlans.offers.create 메서드는 startTime를 설정하더라도 항상 DRAFT 상태로 오퍼를 만듭니다. 혜택을 활성화하려면 monetization.subscriptions.basePlans.offers.activate 메서드를 호출합니다.
보관 자격 요건 규칙 설정
RetentionTargetingRule 객체에는 다음 필드가 포함됩니다.
scope: (필수사항) 규칙에서 고려하는 정기 결제입니다. 유지 혜택의 경우 지원 값은thisSubscription, 즉 혜택이 정의된 정기 결제입니다. 이 필드를{"thisSubscription": {}}로 설정합니다.minDuration: (필수사항) 사용자가 유료 정기 결제 사용자여야 하는 최소 기간으로, ISO 8601 기간(일)으로 표시되며P0D~P1826D입니다. 예를 들어 90일 동안P90D을 사용합니다. 최소 유료 정기 결제 기간을 요구하지 않으려면 이 필드를P0D으로 설정합니다.allowMultipleClaims: 선택사항. 정기 결제 사용자가 혜택을 두 번 이상 신청할 수 있는지 여부입니다.false인 경우 이 혜택을 신청한 적이 있는 정기 결제 사용자는 다시는 이 혜택을 이용할 수 없습니다.true인 경우 이전 유지 혜택의 할인 기간이 종료된 후minOfferCooldownDuration의 시간이 지나면 정기 결제 사용자가 다시 자격을 얻을 수 있습니다. 기본값은false입니다.minOfferCooldownDuration:allowMultipleClaims가true인 경우 필수입니다. 정기 결제 사용자가 다시 자격을 얻기 전에 이전 유지 혜택의 할인 기간이 종료된 후 경과해야 하는 최소 시간입니다. ISO 8601 기간(일)으로P1D~P1826D입니다. 예를 들어 180일 동안P180D을 사용합니다.allowMultipleClaims가false이거나 설정되지 않은 경우 이 필드를 설정하지 마세요.
다음 예에서는 90일 이상 결제한 정기 결제 사용자가 사용할 수 있고 이전 유지 할인 종료 후 180일이 지나면 다시 신청할 수 있는 유지 혜택의 SubscriptionOffer 객체에 대한 startTime, endTime, targeting 필드를 보여줍니다.
{
"offerId": "retention-50off-2m",
"startTime": "2026-12-01T00:00:00Z",
"endTime": "2027-03-01T00:00:00Z",
"targeting": {
"retentionRule": {
"scope": {
"thisSubscription": {}
},
"minDuration": "P90D",
"allowMultipleClaims": true,
"minOfferCooldownDuration": "P180D"
}
}
}
특정 정기 결제 사용자를 타겟팅하는 유지 혜택
Google Play에서 RetentionTargetingRule를 사용하여 자격 요건을 결정하도록 하는 대신 백엔드에서 선택한 정기 결제 사용자에게만 유지 혜택을 제공할 수 있습니다. 예를 들어 이탈 예측 모델에서 위험으로 표시한 정기 결제 사용자나 앱에서 취소 과정을 시작한 정기 결제 사용자를 대상으로 혜택을 제공할 수 있습니다.
정기 결제 사용자는 다른 유지 혜택과 동일한 Google Play 취소 흐름에서 사용자당 유지 혜택을 볼 수 있으며, 개발자는 동일한 방식으로 수락을 처리합니다. 자세한 내용은 백엔드에서 유지 혜택 이벤트 처리를 참고하세요.
특정 정기 결제 사용자를 대상으로 유지 혜택을 타겟팅하려면 다음 단계를 따르세요.
사용자당 유지 혜택을 만듭니다.
monetization.subscriptions.basePlans.offers.create,monetization.subscriptions.basePlans.offers.patch또는monetization.subscriptions.basePlans.offers.batchUpdate메서드를 호출할 때targeting를retentionRule객체 대신retentionPerUserRule객체로 설정합니다.RetentionPerUserTargetingRule객체에는 필드가 없습니다. 혜택은retentionRule또는retentionPerUserRule중 하나를 사용할 수 있지만 둘 다 사용할 수는 없습니다.{ "offerId": "retention-peruser-30off", "targeting": { "retentionPerUserRule": {} } }정기 결제 사용자를 타겟팅하기 전에 혜택을 활성화하세요. 활성화된 적이 없는 오퍼에 대해
activateOfferTargeting메서드를 호출하면 HTTP400 Bad Request상태 코드와INVALID_ARGUMENT오류 상태와 함께 호출이 실패합니다. 자세한 내용은 타겟팅 오류 처리를 참고하세요. 혜택이 활성 상태인 경우에도 Google Play는 다음 단계에서 타겟팅하는 정기 결제 사용자에게만 혜택을 표시합니다.혜택을 정기 결제에 타겟팅합니다. 앱의 패키지 이름, 정기 결제의
purchaseToken, 사용자별 유지 혜택의offerId를 사용하여purchases.subscriptionsv2.activateOfferTargeting메서드를 호출합니다.POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/subscriptionsv2/tokens/{purchaseToken}:activateOfferTargeting { "offerId": "retention-peruser-30off" }호출이 성공하면 응답 본문 없이 HTTP
204 No Content상태 코드가 반환됩니다. Google Play 스토어는 정기 결제와 함께 타겟팅을 저장하므로 정기 결제 사용자가 취소하는 순간에 API를 호출할 필요가 없습니다. 정기 결제 사용자가 다음에 Google Play에서 정기 결제를 취소하려고 할 때 정기 결제가 자격 요건을 충족하는 경우 Google Play에서 혜택을 표시할 수 있습니다. 사용자별 타겟팅은retentionRule에서 정의하는 자격 요건 규칙만 대체합니다. 다른 모든 자격 요건과 Google Play에서 수행하는 플랫폼 수준 검사(예: 지역 규정 준수 요구사항)는 계속 적용됩니다.동일한 정기 결제에 사용자당 유지 혜택을 두 개 이상 타겟팅할 수 있습니다. 이렇게 하려면 각 혜택에 대해
activateOfferTargeting메서드를 한 번 호출합니다. Google Play는 취소 과정에서 최대 하나의 유지 혜택을 계속 표시합니다. Google Play에서 혜택을 선택하는 방법에 관한 자세한 내용은 유지 혜택 구성을 참고하세요.activateOfferTargeting메서드는 멱등성을 갖습니다. 이미 정기 결제에 타겟팅된 혜택에 대해 호출하면 호출이 성공하고 Google Play는 혜택의activateTime를 최신 요청 시간으로 업데이트합니다.필요한 경우 타겟팅을 삭제합니다. 예를 들어 이탈 위험이 변경되어 정기 결제 사용자가 더 이상 혜택을 받지 않도록 하려면 동일한 패키지 이름,
purchaseToken,offerId를 사용하여purchases.subscriptionsv2.deactivateOfferTargeting메서드를 호출합니다. 호출이 성공하면 응답 본문 없이 HTTP204 No Content상태 코드가 반환됩니다.deactivateOfferTargeting메서드도 멱등적입니다. 예를 들어 타겟팅을 활성화하지 않아 혜택이 정기 결제를 타겟팅하지 않는 경우 호출이 성공하고 아무런 영향을 미치지 않습니다.
타겟팅은 단일 purchaseToken에 적용되며 구독이 활성 상태이고 자동 갱신되는 동안에는 만료되지 않습니다. 정기 결제 사용자가 혜택을 확인, 수락 또는 거부한 후에도 계속 표시됩니다. Google Play는 deactivateOfferTargeting 메서드를 호출하거나 정기 결제가 만료된 후 60일이 지나야만 이를 삭제합니다. 요금제 변경 또는 정기 결제 재신청으로 인해 새 purchaseToken가 생성되면 타겟팅이 이월되지 않습니다.
정기 결제를 타겟팅하는 사용자별 유지 혜택을 확인하려면 purchases.subscriptionsv2.get 메서드를 호출합니다. 각 광고 항목의 developerTargetedOffers 필드에는 타겟팅된 오퍼가 나열됩니다. 각 항목에는 타겟팅을 활성화한 시점의 offerId 및 activateTime가 포함됩니다.
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"developerTargetedOffers": [
{
"offerId": "retention-peruser-30off",
"activateTime": "2026-12-03T15:04:05Z"
}
]
}
]
}
타겟팅 오류 처리
activateOfferTargeting 또는 deactivateOfferTargeting 메서드 호출이 실패하면 응답에 HTTP 상태 코드와 원인을 설명하는 오류 상태가 포함됩니다. 다음 표에는 이러한 메서드가 반환할 수 있는 HTTP 상태 코드와 오류 상태가 나와 있습니다.
| HTTP 상태 코드 | 오류 상태 | 메서드 | 원인 |
|---|---|---|---|
404 Not Found |
NOT_FOUND |
둘 다 | purchaseToken이(가) 존재하지 않습니다. |
400 Bad Request |
INVALID_ARGUMENT |
activateOfferTargeting |
offerId가 정기 결제의 현재 기본 요금제에 없거나 혜택이 아직 초안 상태이며 활성화된 적이 없습니다. |
400 Bad Request |
FAILED_PRECONDITION |
activateOfferTargeting |
혜택의 targeting가 retentionPerUserRule로 설정되지 않았습니다. |
400 Bad Request |
FAILED_PRECONDITION |
activateOfferTargeting |
정기 결제가 이미 만료되었습니다. |
activateOfferTargeting 메서드는 만료되지 않은 정기 결제가 혜택을 받을 수 있는지 확인하지 않습니다. 예를 들어 정기 결제가 취소되었지만 아직 만료되지 않은 경우 호출이 성공하고 Google Play 스토어에서 타겟팅을 저장합니다. Google Play는 정기 결제 사용자가 취소 흐름을 시작할 때 정기 결제의 자격 요건을 평가합니다.
백엔드에서 유지 혜택 이벤트 처리
정기 결제 사용자가 유지 혜택을 수락하고 나중에 할인된 갱신이 발생하면 Google Play에서 백엔드로 RTDN을 전송합니다. 각 알림을 받은 후 알림의 purchaseToken를 사용하여 purchases.subscriptionsv2.get 메서드를 호출하여 최신 정기 결제 상태를 가져옵니다.
유지 혜택을 수락해도 새 구매가 생성되지 않습니다. purchaseToken는 동일하게 유지되므로 구매를 다시 확인할 필요가 없으며 Google Play에서 linkedPurchaseToken를 생성하지 않습니다. 정기 결제 사용자의 기존 사용 권한을 그대로 유지합니다. 다른 구독 갱신과 동일한 방식으로 할인된 갱신 주문을 처리합니다.
| 알림 유형 | 전송 시점 | 필요한 조치 |
|---|---|---|
SUBSCRIPTION_PLAN_TRANSITION_UPDATED(21) |
정기 결제 사용자가 취소 과정에서 유지 혜택을 수락하는 경우 | purchases.subscriptionsv2.get 메서드를 호출하고 planTransitionDetails를 확인합니다. transitionState은 IN_PROGRESS입니다. 정기 결제가 활성 상태로 유지되고 자동 갱신되므로 계속 액세스 권한을 부여합니다. |
SUBSCRIPTION_RENEWED(2) |
현재 결제 기간이 종료되고 할인된 유지 혜택 가격으로 정기 결제가 갱신되는 경우 | purchases.subscriptionsv2.get 메서드를 호출하고 offerDetails.offerId가 유지 혜택 ID이고 planTransitionDetails가 더 이상 존재하지 않는지 확인한 후 정기 결제 사용자의 액세스 권한을 새 expiryTime로 연장합니다. |
planTransitionDetails 객체에는 다음 필드가 포함됩니다.
productId: 구독이 전환되는 요금제의 제품 ID입니다. 유지 혜택의 경우 동일한 제품입니다.basePlanId: 정기 결제가 전환되는 요금제의 기본 요금제 ID입니다.offerId: 정기 결제 사용자가 수락한 유지 혜택의 ID입니다. 이 필드를 사용하여 사용된 유지 혜택을 식별합니다.transitionInfo.transitionState: 전환 상태입니다. 유지 혜택의 경우 전환이 대기 중인 동안 상태는IN_PROGRESS입니다.transitionInfo.expectedTransitionTime: 유지 혜택 약관이 적용될 것으로 예상되는 시점입니다.
Google Play는 전환이 대기 중인 동안에만 planTransitionDetails를 포함합니다. 정기 결제가 할인된 유지 혜택 가격으로 갱신되면 전환이 완료되고 Google Play는 purchases.subscriptionsv2.get 응답에서 planTransitionDetails를 삭제합니다. 그 이후에는 광고 항목 자체에 활성 유지 할인이 표시됩니다.
offerDetails.offerId는 수락된 유지 혜택의 ID입니다.offerPhase은 할인된 결제 기간 동안{"introductoryPrice": {}}입니다. 할인된 결제 기간이 종료되고 정기 결제가 일반 기본 요금제 가격으로 갱신되면offerPhase가{"basePrice": {}}로 변경됩니다.
정기 결제 사용자가 혜택을 수락한 후의 응답
정기 결제 사용자가 유지 혜택을 수락하면 현재 결제 기간이 변경되지 않고 계속됩니다. planTransitionDetails 객체는 IN_PROGRESS의 transitionState로 예약된 전환을 보여줍니다.
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"expiryTime": "2026-12-15T10:00:00Z",
"offerDetails": {
"basePlanId": "monthly-base"
},
"autoRenewingPlan": {
"autoRenewEnabled": true,
"planTransitionDetails": {
"productId": "premium_monthly_sub",
"basePlanId": "monthly-base",
"offerId": "retention-50off-2m",
"transitionInfo": {
"transitionState": "IN_PROGRESS",
"expectedTransitionTime": "2026-12-15T10:00:00Z"
}
}
}
}
]
}
할인된 갱신 후 응답
갱신일이 지나고 정기 결제 사용자에게 할인된 가격이 청구되면 offerDetails.offerId에 유지 혜택이 표시되고 offerPhase에 introductoryPrice가 표시되며 응답에 더 이상 planTransitionDetails가 포함되지 않습니다.
{
"lineItems": [
{
"productId": "premium_monthly_sub",
"expiryTime": "2027-01-15T10:00:00Z",
"offerDetails": {
"basePlanId": "monthly-base",
"offerId": "retention-50off-2m"
},
"offerPhase": {
"introductoryPrice": {}
},
"autoRenewingPlan": {
"autoRenewEnabled": true,
"recurringPrice": {
"currencyCode": "USD",
"units": "9",
"nanos": 990000000
}
}
}
]
}
수명 주기 상호작용
유지 혜택을 처리할 때는 다음 사항에 유의하세요.
- 할인 종료: 할인된 결제 기간이 종료되면 정기 결제가 일반 기본 요금제 가격으로 자동 갱신됩니다. 다른 갱신과 마찬가지로
SUBSCRIPTION_RENEWED알림을 수신하고 광고 항목의offerPhase가{"basePrice": {}}로 변경됩니다. 정기 결제 사용자는 별도의 조치를 취할 필요가 없습니다. - 할인 후 결제 복구: 할인 종료 후 정규 기본 요금제 가격으로 갱신이 거부되고 정기 결제가 유예 기간 또는 계정 보류 상태가 되면 결제 복구 시 정규 기본 요금제 가격이 청구됩니다. Google Play는 완료된 유지 혜택 할인을 적용하지 않습니다. 첫 번째 할인된 갱신 결제가 거부되면 대기 중인 전환이 유지되고 결제가 복구되면 유지 혜택 가격이 적용됩니다.
- 지연 결제: 유지 혜택 전환이
IN_PROGRESS인 동안purchases.subscriptionsv2.defer메서드를 호출하면 대기 중인 전환이 유지되고 지연된 갱신 시 적용됩니다. 새 갱신 날짜를 가져오려면 광고 항목의expiryTime를 확인하세요. - 전환 전 요금제 변경: 유지 혜택은 정기 결제 사용자가 수락한 정기 결제의
purchaseToken에만 적용됩니다.expectedTransitionTime전에 정기 결제 사용자가 다른 기본 요금제나 정기 결제로 전환하면 Google Play는 새 구매 토큰을 생성하고 예약된 전환을 취소하며planTransitionDetails를 지웁니다. 대기 중인 유지 혜택은 새 요금제에 적용되지 않습니다. - 취소 및 복원: 정기 결제 사용자가 유지 혜택을 수락한 후 정기 결제를 취소하면 예약된 전환이 대기 중 상태로 유지되고
transitionState는IN_PROGRESS상태로 유지됩니다. 정기 결제가 만료되기 전에 정기 결제 사용자가 정기 결제를 복원하면 갱신 시에도 유지 혜택 할인이 계속 적용됩니다. - 만료 및 정기 결제 재신청: 정기 결제가 복원되지 않고 만료되면 Google Play에서 대기 중인 전환을 취소합니다. 사용자가 나중에 정기 결제를 재신청하거나 다시 가입하면 Google Play에서 새로운 정기 결제 구매를 생성하며 이전에 수락한 유지 혜택은 적용되지 않습니다.
- 혜택 변경: 유지 혜택의 할인 또는 결제 기간을 변경하는 경우 변경사항은 향후 사용에만 적용됩니다. 이미 혜택을 수락한 정기 결제 사용자는 원래 약관을 유지합니다.
- 혜택 비활성화: 유지 혜택을 비활성화하거나 혜택이 종료일에 도달하면 이미 혜택을 수락한 정기 결제 사용자는 동의한 약관을 유지합니다.
IN_PROGRESS전환이 있는 정기 결제 사용자는 다음 갱신 시에도 할인을 받으며, 이미 할인된 결제 기간에 있는 정기 결제 사용자는 합의된 전체 기간 동안 할인을 유지합니다. - 가격 변경: 기본 요금제 가격 변경은 계속 적용됩니다. Google Play는 정기 결제 사용자가 정가를 지불하고 있고 대기 중인 유지 혜택 전환이 없는 경우에만 정기 결제 사용자를 새 가격으로 이전합니다. 자세한 내용은 정기 결제 가격 변경을 참고하세요.
- 환불:
purchases.subscriptionsv2.revoke메서드와 같은 표준 환불 및 취소 API를 사용하여 정기 결제 사용자에게 환불할 수 있습니다. 이렇게 하면 가장 최근 결제 금액이 환불되고 정기 결제 사용자의 액세스가 종료됩니다.
유지 혜택 테스트
Google Play는 취소 과정에서 활성 상태의 유지 혜택만 표시하며 실제 달력 시간을 기준으로 자격 요건 규칙을 평가합니다. 라이선스 테스터 계정으로 유지 혜택을 테스트하려면 다음 방법 중 하나를 사용하세요.
- 실제 정기 결제 사용자에게 혜택을 표시하지 않고 프로덕션 기본 요금제에서 사용자별 유지 혜택을 테스트합니다.
- 프로덕션 사용자가 액세스할 수 없는 테스트 앱 또는 테스트 기본 요금제에서 규칙 기반 유지 혜택을 테스트합니다.
두 방법 중 하나를 사용하기 전에 Google Play Console의 설정 > 라이선스 테스트로 이동하여 테스트 Google 계정을 라이선스 테스터로 추가합니다.
사용자별 유지 혜택 테스트
Google Play는 타겟팅하는 정기 결제에만 사용자별 유지 혜택을 표시하므로 실제 정기 결제 사용자에게 노출하지 않고 프로덕션 기본 요금제에서 테스트할 수 있습니다. 사용자별 유지 혜택을 테스트하려면 다음 단계를 따르세요.
- 기본 요금제에서 사용자별 유지 혜택을 만든 후 활성화합니다. Google Play Console에서 사용자 수준 유지 혜택을 선택합니다.
Google Play Developer API를 사용하여
targeting를retentionPerUserRule객체로 설정합니다. 자세한 내용은 특정 정기 결제 사용자를 대상으로 한 유지 혜택 타겟팅을 참고하세요. - 혜택을 방금 활성화한 경우 변경사항이 전파될 때까지 10~15분 정도 기다린 후 Google Play 스토어 앱 캐시를 지웁니다.
- 테스트 기기에서 라이선스 테스터 계정으로 로그인한 다음 앱에서 기본 요금제를 구매합니다.
- 백엔드에서 앱의 패키지 이름, 라이선스 테스터의
purchaseToken, 유지 혜택의offerId를 사용하여purchases.subscriptionsv2.activateOfferTargeting메서드를 호출합니다. - Google Play 스토어 앱에서 결제 및 정기 결제 > 정기 결제로 이동하여 정기 결제를 선택하고 정기 결제 취소를 탭합니다. 유지 혜택은 취소 과정에서 표시됩니다.
- 혜택을 수락한 후 백엔드가
SUBSCRIPTION_PLAN_TRANSITION_UPDATEDRTDN을 수신하고 할인된 갱신을 처리하는지 확인합니다.
규칙 기반 유지 혜택 테스트
규칙 기반 유지 혜택을 활성화하면 Google Play에서 기본 요금제를 사용하는 자격 요건을 충족하는 정기 결제 사용자에게 이 혜택을 표시할 수 있습니다. 프로덕션 사용자에게 혜택이 노출되지 않도록 하려면 프로덕션이 아닌 테스트 앱이나 프로덕션 사용자가 액세스할 수 없는 전용 테스트 기본 요금제에서 테스트하세요. 규칙 기반 유지 혜택을 테스트하려면 다음 단계를 따르세요.
- 테스트 앱 또는 테스트 기본 요금제에서 규칙 기반 유지 혜택을 만들고
minDuration를P0D(0일)로 설정합니다. Google Play Console에서 동질 집단 수준 유지 혜택을 선택합니다. Google Play Developer API를 사용하여targeting를retentionRule객체로 설정합니다. 자세한 내용은 보관 자격 요건 규칙 설정을 참조하세요. - 혜택을 활성화하고 변경사항이 적용될 때까지 10~15분 정도 기다린 다음 Google Play 스토어 앱 캐시를 지웁니다.
- 테스트 기기에서 라이선스 테스터 계정으로 로그인한 후 테스트 기본 요금제를 구매합니다.
- Google Play 스토어 앱에서 결제 및 정기 결제 > 정기 결제로 이동하여 정기 결제를 선택하고 정기 결제 취소를 탭합니다. 혜택에 최소 유료 구독 기간이 필요하지 않으므로 구매 직후 취소 흐름을 시작할 수 있습니다. 유지 혜택은 취소 과정에서 표시됩니다.
- 혜택을 수락한 후 백엔드가
SUBSCRIPTION_PLAN_TRANSITION_UPDATEDRTDN을 수신하고 할인된 갱신을 처리하는지 확인합니다.
통합을 확인한 후 프로덕션 기본 요금제에서 규칙 기반 유지 혜택을 만들고 활성화합니다.
유지 혜택 테스트 문제 해결하기
유지 혜택이 표시되지 않으면 다음을 확인하세요.
- 유지 혜택이 활성 상태이고 현재 시간이
startTime와endTime사이입니다(설정한 경우). - 사용자별 유지 혜택의 경우 라이선스 테스터의
purchaseToken에 대한purchases.subscriptionsv2.get응답의developerTargetedOffers필드에 혜택이 포함됩니다. - 정기 결제가 부가기능이 포함된 정기 결제가 아닌 단일 정기 결제입니다.
- 정기 결제가 유예 기간, 계정 보류 또는 일시중지 상태가 아닙니다.
- 정기 결제에 대기 중인 요금제 변경 또는 가격 변경이 없습니다.
- 다음 갱신 시에는 정가 기본 요금제 가격이 적용됩니다. 무료 체험 및 신규 할인 혜택의 경우 유지 혜택은 체험 또는 신규 할인 단계의 마지막 결제 기간에만 사용할 수 있습니다.
- 혜택을 활성화하거나 변경한 후 10~15분 동안 기다렸으며 Play 스토어 앱 캐시를 삭제했습니다.