이 가이드에서는 Google Play Developer API를 사용하여 Play 앱의 제품 카탈로그를 만들고 관리하는 방법을 설명합니다.
Google Play 결제 시스템을 통해 앱에서 제품을 판매하려면 사용자가 구매할 수 있도록 제공하려는 모든 제품이 포함된 카탈로그를 설정해야 합니다. Play Console을 통해 이를 실행하거나 Google Play Developer API를 사용하여 카탈로그 관리를 자동화할 수 있습니다. 자동화는 카탈로그를 항상 최신 상태로 유지하고 수동 조정이 비현실적인 대규모 카탈로그로 확장하는 데 도움이 될 수 있습니다. 이 가이드에서는 Play Developer API를 사용하여 Play 앱의 제품 카탈로그를 만들고 관리하는 방법을 설명합니다. 백엔드 통합을 위해 Google Play Developer API를 설정하는 방법에 관한 안내는 준비하기 가이드를 참고하세요.
카탈로그 관리 API
Google Play 결제 시스템으로 판매할 수 있는 다양한 제품 유형에 관한 자세한 내용은 인앱 상품 유형 및 카탈로그 고려사항 이해를 참고하세요. Google은 Play의 카탈로그 관리를 위한 두 가지 기본 API 세트를 제공하며, 이는 두 가지 기본 제품 카테고리에 해당합니다.
- 일회성 제품
- 정기 결제 제품
일회성 제품
inappproducts 엔드포인트를 사용하면 백엔드의 일회성 제품을 관리할 수 있습니다. 여기에는 제품 생성, 업데이트, 삭제와
가격 및 재고 관리가 포함됩니다.
일회성 제품 구매를 처리하는 방법에 따라 소비성 제품 (원하는 만큼 구매할 수 있음) 또는 영구 사용 권한 (동일한 사용자가 두 번 구매할 수 없음)을 모델링합니다. 어떤 일회성 제품을 소비성으로 할지 결정할 수 있습니다.
정기 결제 제품
monetization.subscriptions 엔드포인트를 사용하면 개발자 백엔드에서 정기 결제 제품을 관리할 수 있습니다. 정기 결제를 생성, 업데이트, 삭제하거나 지역별 재고 및 가격을 제어하는 등의 작업을 수행할 수 있습니다.
monetization.subscriptions 엔드포인트 외에도 정기 결제의 기본 요금제와 혜택을 각각 관리하는 monetization.subscriptions.basePlans 및 monetization.subscriptions.basePlans.offers도 제공합니다.
일괄 메서드
inappproducts 및 monetization.subscriptions 엔드포인트는 동일한 앱에서 동시에 최대 100개의 항목을 검색하거나 관리할 수 있는 다양한 일괄 메서드를 제공합니다.
일괄 메서드는 사용 설정된 지연 시간 허용 오차와 함께 사용될 경우 높은 처리량을 지원하며 특히 초기 카탈로그 생성 또는 카탈로그 조정을 위해 대형 카탈로그 개발자에게 유용합니다.
업데이트 전파 지연 시간 및 처리량 비교
제품 생성 또는 수정 요청이 완료된 후에는 네트워크 또는 백엔드 처리 지연으로 인해 변경사항이 기기의 최종 사용자에게 즉시 표시되지 않을 수 있습니다.
기본적으로 모든 제품 수정 요청은 지연 시간에 민감합니다. 즉, 백엔드 시스템을 통한 빠른 전파에 최적화되어 있으며 일반적으로 몇 분 이내에 최종 사용자 기기에 반영됩니다. 하지만 수정 요청 수에는 시간 제한이 있습니다.
많은 제품을 만들거나 업데이트해야 하는 경우 (예: 초기 대규모 카탈로그 생성 중) latencyTolerance 필드가 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT로 설정된 일괄 메서드를 사용할 수 있습니다.
이렇게 하면 업데이트 처리량이 크게 증가합니다. 지연 시간 허용 업데이트가 최종 사용자 기기에 전파되는 데 최대 24시간이 걸립니다.
할당량 구성
Play Developer API를 사용하여 제품 카탈로그를 관리할 때 알아야 할 몇 가지 할당량 한도가 있습니다.
- Google Play Developer API에서는 기본 쿼리 한도가 일일 200,000개로 제한됩니다. 이 할당량 한도는 카탈로그 관리 API를 포함한 모든 엔드포인트의 사용량 집계에 적용됩니다.
- 또한 제품 수정 엔드포인트는 쿼리 수가 시간당 7,200개로 제한됩니다. 일회성 제품 및 구독과 생성, 업데이트, 활성화, 삭제를 포함한 모든 수정 요청에 적용되는 단일 한도입니다. 일괄 수정 메서드 호출은 포함된 개별 요청 수 또는 지연 시간 민감도에 관계없이 이 할당량의 쿼리 1회로 집계됩니다.
- 지연 시간에 민감한 수정 또한 시간당 7,200회로 제한됩니다. 일괄 메서드의 경우 모든 중첩된 수정 요청이 이 할당량의 목적에 따라 별도로 계산됩니다. 이 할당량은 지연 시간에 민감한 업데이트를 수행하는 일괄 API 사용자에게만 실질적인 영향을 미칩니다. 다른 경우 할당량 2는 이 할당량과 동시에 또는 동시에 소진되기 때문입니다.
다음은 다양한 요청의 할당량 사용량을 이해하기 위한 몇 가지 예시 예입니다.
- 항목 1개를 가져오는 단일
get요청은 할당량 1의 토큰 1개를 사용하고 할당량 2 및 3의 토큰은 수정 엔드포인트에만 해당하므로 사용하지 않습니다. - 항목을 최대 100개까지 가져오는 일괄
get요청도 할당량 1 토큰 1개를 사용하고 할당량 2 및 3 토큰은 사용하지 않습니다. - 항목 1개에 대한 단일
modification요청은 할당량 1의 토큰 1개와 할당량 2 토큰 1개를 사용합니다. 지연 시간에 민감한 요청도 할당량 3 토큰 1개를 사용합니다. 할당량 C에는 할당량 2와 동일한 한도가 있기 때문에 하나의 수정 메서드만 사용하는 사용자에게는 실질적으로 아무런 영향도 미치지 않습니다. - 지연 시간 허용 항목 100개에 대한 일괄
modification요청은 할당량 1의 토큰 1개와 할당량 2 토큰 1개를 사용합니다. 이 할당량 설정으로 카탈로그를 업데이트할 수 있는 충분한 여유가 있어야 하지만 알고리즘이 이 할당량을 의식하지 않고 이 속도를 초과하면 추가 호출당 오류가 발생할 수 있습니다. - 지연 시간에 민감한 항목 100개에 대한 일괄
modification요청은 할당량 1 토큰 1개, 할당량 2 토큰 1개, 할당량 3 토큰 100개를 사용합니다.
Catalog Management API 사용 권장사항
이 가이드라인을 준수하면 API와의 상호작용을 최적화하여 원활하고 효율적인 카탈로그 관리 환경을 보장할 수 있습니다.
사용량 모니터링
사용량이 많은 프로세스에 주의해야 합니다. 예를 들어 통합이 시작될 때 카탈로그 관리 엔드포인트는 전체 초기 카탈로그를 만들기 위해 더 많은 할당량을 사용할 가능성이 높으며 전체 사용량 한도에 근접한 경우 구매 상태 API와 같은 다른 엔드포인트의 프로덕션 사용에 영향을 미칠 수 있습니다. 할당량 사용을 모니터링하여 API 할당량을 초과하지 않도록 해야 합니다. 사용량을 모니터링하는 방법에는 여러 가지가 있습니다. 예를 들어 Google Cloud API 할당량 대시보드나 원하는 다른 사내 또는 타사 API 모니터링 도구를 사용할 수 있습니다.
API 할당량 사용 최적화
API 오류 가능성을 최소화하려면 비율 소비를 최적화하는 것이 좋습니다. 이를 효과적으로 구현하려면 다음과 같이 하는 것이 좋습니다.
- 적절한 카탈로그 관리 전략을 선택합니다. API 할당량을 이해했으면 카탈로그 관리 목표를 효율적으로 달성하기 위해 애플리케이션에 적합한 전략을 선택해야 합니다.
- 변경사항을 반영하는 데 필요한 최소한의 호출량만 실행합니다.
- 중복되거나 불필요한 수정 호출을 API에 전송하면 안 됩니다. 이를 위해서는 백엔드 카탈로그에 변경 로그를 유지해야 할 수도 있습니다.
- 제품 수정의 시간당 쿼리 7,200개 한도를 유지하세요. 단기간에 많은 수의 제품을 수정해야 하는 동기화 프로세스를 빌드하는 것이 좋습니다 (예: 초기 카탈로그 생성). 이러한 프로세스가 시간당 한도를 초과할 것으로 예상되면 필요한 경우 대기를 구현하여 사용량을 안전한 수준으로 늦추세요. 더 높은 처리량을 달성하려면 지연 시간 허용 업데이트와 함께 배치 메서드를 사용하는 것이 좋습니다.
- 사전에 확장을 준비하세요. 애플리케이션이 커짐에 따라 API 및 다양한 엔드포인트의 사용량을 늘려야 할 수도 있습니다. 최대 사용량에 근접했을 때 할당량을 늘리는 방법에 관한 자세한 내용은 Google Play Developer API 할당량 문서를 참고하세요.
- 대규모 프로세스의 일정을 전략적으로 예약합니다. 사용량이 급증하는 시기에 사용량이 많은 카탈로그 프로세스를 예약하세요. 예를 들어 주 중 판매량이 가장 많은 시간대에 전체 카탈로그 동기화를 실행하지 않아도 됩니다.
할당량 오류 처리 로직 추가
카탈로그 관리 로직을 아무리 효율적으로 빌드하더라도 일일 할당량은 통합의 독립적인 모듈에서 사용되는 엔드포인트에서 공유된다는 점을 감안하여 예상치 못한 할당량 한도에 대한 복원력을 만들어야 합니다. 오류 처리에 할당량 제한 오류를 포함하고 적절한 대기를 구현해야 합니다.
Google Play Developer API를 호출할 때마다 응답이 생성됩니다. 호출이 실패하면 HTTP 응답 상태 코드와 errors 객체가 포함된 실패 응답을 수신하여 오류 도메인과 디버그 메시지에 대한 세부정보를 제공합니다.
예를 들어 일일 한도를 초과하면 다음과 유사한 오류가 발생할 수 있습니다.
{
"code" : 403,
"errors" : [ {
"domain" : "usageLimits",
"message" : "Daily Limit Exceeded. The quota will be reset at midnight Pacific Time (PT). You may monitor your quota usage and adjust limits in the API
Console: https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxxx",
"reason" : "dailyLimitExceeded",
"extendedHelp" : "https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxx"
} ],
}
카탈로그 관리 구현
개발자는 Google Play Developer API 제품 게시 엔드포인트를 사용하여 백엔드와 Google Play 간에 카탈로그 동기화를 유지합니다. 백엔드의 카탈로그 최신 정보를 사용하여 Google Play 카탈로그를 항상 최신 상태로 유지하면 더 나은 사용자 환경을 만들 수 있는 이점이 있습니다. 예:
- 사용 가능한 혜택의 전체 목록을 참고하고 혜택 및 기본 요금제 태그를 관리하여 자체 자격 요건과 혜택 표시 로직에 영향을 줄 수 있습니다.
- 여러 플랫폼에서 사용자에게 표시되는 다양한 가격대와 제품 세부정보를 확인하고 일관성을 유지할 수 있습니다.
- 새 구매를 처리할 때 백엔드에서 제품 세부정보를 사용할 수 있으므로 사용자가 중요한 흐름 중에 Google Play Developer API를 추가로 호출하여 지연 시간과 실패 위험을 늘릴 필요가 없습니다.
Google Play에서 제품 카탈로그를 만들 때 유의해야 할 특정 제한사항 및 고려사항이 있습니다. 이러한 제한을 이해하고 카탈로그를 어떻게 구조화할 것인지 알게 되면 이제 동기화 전략을 결정할 차례입니다.
카탈로그 동기화 전략
Google Play Developer API 게시 엔드포인트를 사용하면 변경사항이 발생할 때 카탈로그를 업데이트할 수 있습니다. 경우에 따라 동일한 프로세스에서 변경사항의 배터리를 전송하는 주기적인 업데이트 접근 방식을 취해야 할 수도 있습니다. 접근 방식마다 다른 설계 옵션이 필요합니다. 각 동기화 전략은 일부 사용 사례에 다른 사용 사례에 더 적합하며 상황에 따라 두 가지를 모두 충족해야 하는 요구사항이 있을 수 있습니다. 긴급한 제품 업데이트 (예: 잘못된 가격을 가능한 한 빨리 수정해야 함)를 처리하기 위해 새로운 변경사항을 인지하는 즉시 제품을 업데이트해야 하는 경우가 있습니다. 아니면 주기적인 백그라운드 동기화를 사용하여 백엔드와 Play 카탈로그가 항상 일관되도록 할 수도 있습니다. 다양한 카탈로그 관리 전략을 구현할 수 있는 몇 가지 일반적인 사용 사례를 알아보세요.
현지 카탈로그 변경사항에 따라 업데이트를 전송해야 하는 경우
불일치를 최소화하기 위해 백엔드의 제품 카탈로그가 변경되는 즉시 업데이트하는 것이 가장 좋습니다.
이러한 유형의 업데이트는 다음과 같은 경우에 적합합니다.
- 제품이 항상 최신 상태인지 확인해야 합니다.
- 매일 제품에 몇 가지 변경사항을 적용해야 합니다.
- 이미 프로덕션 및 판매 중인 제품을 업데이트해야 합니다.
이 접근 방식은 구현이 더 간단하며 이를 통해 카탈로그를 최소 불일치 기간과 동기화된 상태로 유지할 수 있습니다.
주기적인 업데이트를 사용해야 하는 경우
주기적 업데이트는 백엔드의 제품 버전에 대해 비동기식으로 실행되며 다음과 같은 경우에 적합합니다.
- 갑작스러운 공지에 제품이 업데이트되도록 할 필요는 없습니다.
- 일괄 업데이트 또는 조정 프로세스를 계획해야 하는 경우
- 디지털 제품을 처리할 수 있는 콘텐츠 또는 카탈로그 관리 시스템이 이미 있으며 카탈로그가 지속적으로
대규모 카탈로그의 경우 지연 시간 허용 업데이트가 포함된 일괄 메서드를 사용하여 최대 처리량을 달성하는 것이 좋습니다.
제품 카탈로그 만들기
Google Play에 업로드할 대규모 카탈로그가 있는 경우 초기 로드를 자동화해야 할 수 있습니다. 이러한 유형의 고부하 프로세스는 지연 시간 허용 일괄 메서드와 함께 주기적인 전략을 따르는 경우에 가장 효과적입니다.
일회성 제품 만들기
일회성 제품 대규모 카탈로그를 처음 만들 때는 allowMissing 필드가 true로, latencyTolerance 필드가 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT로 설정된 inappproducts.batchUpdate 메서드를 사용하는 것이 좋습니다.
이렇게 하면 할당량 한도 내에서 카탈로그를 만드는 데 걸리는 시간이 최소화됩니다.
작은 카탈로그의 경우 inapp_products.insert 메서드를 사용할 수 있습니다.
또는 제품 업데이트 섹션에 설명된 대로 inappproducts.update 메서드를 allowMissing 매개변수와 함께 사용할 수 있습니다.
이 접근 방식을 사용하면 스크립트가 스테이트풀(Stateful)일 필요가 없으며, 문제가 발생할 경우 처음부터 다시 시작할 수 있습니다.
정기 결제 제품 만들기
정기 결제 대규모 카탈로그를 처음 만들 때는 allowMissing 필드가 true로, latencyTolerance 필드가 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT로 설정된 monetization.subscriptions.batchUpdate 메서드를 사용하는 것이 좋습니다.
이렇게 하면 할당량 한도 내에서 카탈로그를 만드는 데 걸리는 시간이 최소화됩니다.
소규모 정기 결제 카탈로그의 경우 Play Developer API는 monetization.subscriptions.create 메서드를 제공합니다.
또는 제품 업데이트 섹션에 설명된 대로 allowMissing 매개변수와 함께 monetization.subscriptions.update 메서드를 사용하여 정기 결제를 만들 수 있습니다.
앞의 모든 메서드는 (정기 결제 객체 내에서 제공됨) 기본 요금제와 함께 정기 결제를 만듭니다. 이러한 기본 요금제는 처음에는 비활성 상태입니다. 기본 요금제의 상태를 관리하려면 기본 요금제를 구매 가능하도록 활성화하는 등 monetization.subscriptions.basePlans 엔드포인트를 사용하면 됩니다.
또한 monetization.subscriptions.basePlans.offers 엔드포인트를 사용하면 오퍼를 만들고 관리할 수 있습니다.
제품 업데이트
다음 방법을 사용하면 기존 제품을 효율적으로 수정하여 서비스를 최신 조정에 맞게 조정할 수 있습니다.
일회성 제품 업데이트
기존의 일회성 제품을 업데이트하는 데 세 가지 방법을 사용할 수 있습니다.
inappproducts.patch: 패치 엔드포인트는 리소스를 부분적으로 업데이트하는 데 사용됩니다. 즉, 요청 본문에 지정하는 특정 필드를 업데이트할 수 있습니다. 패치 엔드포인트는 일반적으로 리소스의 일부 필드만 업데이트해야 할 때 사용됩니다.inappproducts.update: 업데이트 엔드포인트는 리소스 전체를 업데이트하는 데 사용됩니다. 즉, 요청 본문에서 전체 리소스 객체를 전송해야 합니다. 업데이트 엔드포인트는 일반적으로 리소스의 모든 필드를 업데이트해야 할 때 사용됩니다.allowMissing매개변수가true로 설정되어 있고 제공된 제품 ID가 아직 없는 경우 엔드포인트는 실패하지 않고 제품을 삽입합니다.inappproducts.batchUpdate: 업데이트 엔드포인트의 일괄 버전으로, 단일 쿼리로 여러 제품을 수정할 수 있습니다.latencyTolerance필드를PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT로 설정하여 함께 사용하면 처리량을 높일 수 있습니다.
정기 결제 제품 업데이트
기존 정기 결제를 업데이트하려면 monetization.subscriptions.patch 메서드를 사용하면 됩니다. 이 메서드는 다음과 같은 필수 매개변수를 사용합니다.
packageName: 정기 결제가 속한 앱의 패키지 이름입니다.productId: 정기 결제의 고유한 제품 ID입니다.regionsVersion: 리전 구성 버전입니다.
allowMissing 매개변수를 사용하여 새로운 정기 결제를 만들지 않는 한 updateMask 매개변수를 제공해야 합니다. 이 매개변수는 업데이트할 필드의 쉼표로 구분된 목록입니다.
예를 들어 정기 결제 제품의 등록정보만 업데이트하려면 listings 필드를 updateMask 매개변수에 지정합니다.
monetization.subscriptions.batchUpdate를 사용하면 여러 구독을 동시에 업데이트할 수 있습니다.
latencyTolerance 필드를 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT로 설정하여 함께 사용하면 처리량을 높일 수 있습니다.
기본 요금제를 활성화, 비활성화, 삭제하거나 정기 결제 사용자를 최신 기본 요금제 가격 버전으로 이전하려면 monetization.subscriptions.basePlans 엔드포인트를 사용하세요.
또한 monetization.subscriptions.basePlans.offers.patch 메서드를 사용하여 기본 요금제의 혜택을 업데이트할 수 있습니다.
카탈로그 조정
백엔드의 카탈로그가 변경될 때마다 또는 주기적으로 Google Play 카탈로그를 업데이트하든, 카탈로그 관리 시스템이나 Google Play 카탈로그 외부의 데이터베이스가 있는 경우 카탈로그가 Play의 앱 구성에 있는 카탈로그와 동기화되지 않을 수 있습니다. 이는 Console에서 긴급 수동 카탈로그 변경, 카탈로그 관리 시스템 중단 또는 최신 데이터가 손실되었기 때문일 수 있습니다.
카탈로그 조정 프로세스를 구축하여 불일치 기간이 길어지는 것을 방지할 수 있습니다.
diff 시스템 고려사항
불일치 시스템을 감지하여 불일치를 감지하고 두 시스템을 조정하는 것이 좋습니다. 다음은 카탈로그의 동기화를 유지하는 데 도움이 되도록 diff 시스템을 빌드할 때 고려해야 할 사항입니다.
- 데이터 모델 이해: 첫 번째 단계는 개발자 CMS 및 Google Play Developer API의 데이터 모델을 이해하는 것입니다. 여기에는 각 시스템에 저장되는 다양한 유형의 데이터 및 여러 데이터 요소가 서로 매핑되는 방식을 이해하는 것이 포함됩니다.
- 차이점 규칙 정의: 데이터 모델을 이해했으면 비교 규칙을 정의해야 합니다. 이 규칙은 두 시스템의 데이터를 비교하는 방법을 결정합니다. 예를 들어 제품 ID를 일치시키고 정기 결제의 주요 속성과 연결된 기본 요금제 및 혜택을 비교할 수 있습니다.
- diff 알고리즘 구현: diff 규칙을 정의한 후에는 diff 알고리즘을 구현해야 합니다. 이 알고리즘은 두 시스템의 데이터를 가져와 정의된 규칙에 따라 비교합니다. Google Play에서 카탈로그 데이터를 가져오려면
inappproducts.list,inappproducts.batchGet,monetization.subscriptions.list,monetization.subscriptions.batchGet메서드를 사용하면 됩니다. - 차이점 보고서 생성: 비교 알고리즘이 차이점 보고서를 생성합니다. 이 보고서는 두 시스템의 차이점을 보여줍니다.
- 차이 조정: diff 보고서를 생성한 후에는 차이를 해결해야 합니다. 여기에는 CMS의 데이터를 업데이트하거나 일반적으로 카탈로그를 업데이트하는 방법에 따라 Developer API 카탈로그 관리 엔드포인트를 사용하여 Google Play 측에서 데이터를 업데이트해야 할 수도 있습니다. 동기화되지 않은 제품을 조정하려면 제품 업데이트 섹션에 설명된 대로 업데이트 엔드포인트를 사용하세요.
제품 지원 중단
Google Play Developer API는 일회성 제품의 경우 inappproducts.delete 및 inappproducts.batchDelete, 정기 결제의 경우 monetization.subscriptions.delete 등 개발자가 제품을 지원 중단하는 데 도움이 되는 여러 가지 메서드를 제공합니다. 다음과 같은 다양한 시나리오에서 제품을 지원 중단해야 할 수 있습니다.
- 실수로 생성한 경우
- 기능 또는 서비스 중단
카탈로그 관리 전략에 제품 지원 중단을 포함하는 것이 좋습니다.
일회성 제품 지원 중단
Google Play Developer API로 일회성 제품을 삭제하려면 inappproducts.delete 또는 inappproducts.batchDelete 메서드를 사용해야 합니다.
정기 결제 제품 지원 중단
monetization.subscriptions.delete 메서드를 사용하여 정기 결제를 삭제할 수 있습니다. 하나 이상의 기본 요금제가 활성화되면 정기 결제를 삭제할 수 없습니다.