이 가이드에서는 Google Play Developer API를 사용하여 Play 앱의 제품 카탈로그를 만들고 관리하는 방법을 설명합니다.
Google Play 결제 시스템을 통해 앱에서 제품을 판매하려면 사용자가 구매할 수 있도록 하려는 모든 제품이 포함된 카탈로그를 설정해야 합니다. Play Console을 통해 할 수도 있고 Google Play Developer API를 사용하여 카탈로그 관리를 자동화할 수도 있습니다. 자동화를 사용하면 카탈로그를 항상 최신 상태로 유지하고 수동 조정이 실용적이지 않은 대규모 카탈로그로 확장할 수 있습니다. 이 가이드에서는 Play Developer API를 사용하여 Play 앱의 제품 카탈로그를 만들고 관리하는 방법을 설명합니다. 백엔드 통합을 위해 Google Play Developer API를 설정하는 방법에 관한 안내는 준비하기 가이드를 참고하세요.
Catalog Management 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개의 쿼리 한도도 적용됩니다. 일회성 제품과 정기 결제 모두에 적용되며 생성, 업데이트, 활성화, 삭제를 비롯한 모든 수정 요청에 적용되는 단일 한도입니다. 일괄 수정 메서드 호출은 포함된 개별 요청 수 또는 지연 시간 민감도와 관계없이 이 할당량에 대해 하나의 쿼리로 집계됩니다.
- 지연 시간에 민감한 수정사항의 경우에도 시간당 7,200회로 제한됩니다. 일괄 메서드의 경우 이 할당량의 목적상 중첩된 모든 수정 요청이 별도로 집계됩니다. 이 할당량은 지연 시간에 민감한 업데이트를 실행하는 일괄 API 사용자에게만 실질적인 영향을 미칩니다. 다른 경우에는 할당량 2가 이 할당량보다 먼저 또는 동시에 소진되기 때문입니다.
다음은 다양한 요청의 할당량 사용량을 이해하는 데 도움이 되는 몇 가지 예입니다.
- 항목 하나를 가져오는 단일
get요청은 할당량 1 토큰 1개를 사용하고 할당량 2 및 3 토큰은 사용하지 않습니다 (수정 엔드포인트와만 관련이 있음). - 최대 100개의 항목을 가져오는 일괄
get요청도 할당량 1의 토큰 1개를 사용하고 할당량 2 및 3의 토큰은 사용하지 않습니다. - 항목 하나에 대한 단일
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 메서드를 사용할 수 있습니다.
또는 제품 업데이트 섹션에 설명된 대로 allowMissing 매개변수와 함께 inappproducts.update 메서드를 사용할 수 있습니다.
이 접근 방식의 이점은 스크립트가 상태 저장형일 필요가 없으며 문제가 발생하면 처음부터 다시 시작할 수 있다는 점입니다.
정기 결제 제품 만들기
초기 구독 대규모 카탈로그 생성의 경우 allowMissing 필드를 true로 설정하고 latencyTolerance 필드를 PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT로 설정하여 monetization.subscriptions.batchUpdate 메서드를 사용하는 것이 좋습니다.
이렇게 하면 할당량 한도 내에서 카탈로그를 만드는 데 걸리는 시간이 최소화됩니다.
소규모 정기 결제 카탈로그의 경우 Play Developer API는 monetization.subscriptions.create 메서드를 제공합니다.
또는 제품 업데이트 섹션에 설명된 대로 allowMissing 매개변수와 함께 monetization.subscriptions.patch 메서드를 사용하여 정기 결제를 만들 수 있습니다.
이전의 모든 메서드는 기본 요금제(Subscription 객체 내에 제공됨)와 함께 정기 결제를 만듭니다. 이러한 기본 요금제는 처음에는 비활성 상태입니다. 기본 요금제의 상태를 관리하려면 기본 요금제를 활성화하여 구매할 수 있도록 하는 등의 작업을 포함하여 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 시스템을 빌드하는 것이 좋습니다. 다음은 카탈로그를 동기화하는 데 도움이 되는 diff 시스템을 빌드할 때 고려해야 할 사항입니다.
- 데이터 모델 이해: 첫 번째 단계는 개발자 CMS 및 Google Play Developer API의 데이터 모델을 이해하는 것입니다. 여기에는 각 시스템에 저장된 다양한 데이터 유형과 다양한 데이터 요소가 서로 매핑되는 방식을 아는 것이 포함됩니다.
- 차이 규칙 정의: 데이터 모델을 이해한 후에는 차이 규칙을 정의해야 합니다. 이러한 규칙에 따라 두 시스템의 데이터가 비교됩니다. 예를 들어 제품 ID를 일치시키고 정기 결제 및 관련 기본 요금제 및 혜택의 주요 속성을 비교할 수 있습니다.
- 비교 알고리즘 구현: 차이점 규칙을 정의한 후에는 비교 알고리즘을 구현해야 합니다. 이 알고리즘은 두 시스템의 데이터를 가져와 정의한 규칙에 따라 비교합니다. Google Play에서 카탈로그 데이터를 가져오려면
inappproducts.list,inappproducts.batchGet,monetization.subscriptions.list,monetization.subscriptions.batchGet메서드를 사용하면 됩니다. - diff 보고서 생성: diff 알고리즘이 diff 보고서를 생성합니다. 이 보고서에는 두 시스템 간의 차이가 표시됩니다.
- 차이점 조정: 차이 보고서를 생성한 후에는 차이점을 해결해야 합니다. 일반적으로 카탈로그를 업데이트하는 방식에 따라 CMS의 데이터를 업데이트하거나 개발자 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 메서드를 사용하여 구독을 삭제할 수 있습니다. 하나 이상의 기본 요금제가 활성화된 후에는 정기 결제를 삭제할 수 없습니다.