KappS 지식 베이스 · 블로그

2026년 Google Play 실시간 개발자 알림

블로그 튜토리얼

실시간 개발자 알림(RTDN)은 Google Play이 구매에 변화가 생겼음을 백엔드에 알리는 방식입니다. 웹훅 대시보드도, 앱별 API 키도 없습니다. Play는 여러분의 Google Cloud 프로젝트 안에 있는 Cloud Pub/Sub 주제로 메시지를 게시하고, 서버는 이를 HTTPS 푸시로 수신하거나 풀 방식으로 가져옵니다. 수익 운영이 여전히 Developer API를 폴링하는 예약 작업에 의존하고 있다면 RTDN이 업그레이드입니다. Google 문서에 따르면 Play Developer API를 비효율적으로 사용하면 "API 할당량 제한으로 이어질 수 있습니다."

이 튜토리얼은 실제 작업 순서를 따릅니다. 토픽을 생성하고, Play 게시 권한을 부여하고, 푸시 또는 풀을 선택하고, Play Console에서 알림을 활성화한 다음, 페이로드를 디코딩해 처리합니다. 아래의 모든 필드 이름, 알림 유형, 콘솔 단계는 끝부분에 인용한 Google의 공식 문서 두 페이지에서 가져온 것입니다.

RTDN을 한 줄로 정의하면: 구매 상태가 바뀔 때마다 오는 메시지로, 알림당 약 1KB, 발행 및 풀(pull) 포함 약 2KB이며, 이후 Google Play Developer API를 호출해야 하는 상시 의무가 따릅니다. 알림은 "구매에 대한 완전한 정보를 제공하지 않기" 때문입니다.

1단계 — 본인 GCP 프로젝트에 Pub/Sub 주제 생성하기

RTDN은 Android 앱별로 구성되지만, 메시징 계층은 귀하의 몫입니다. Cloud Pub/Sub API가 활성화된 Google Cloud 프로젝트와 Play가 게시할 주제가 필요합니다. 이미 Play Developer API에 사용 중인 프로젝트를 재사용하거나 별도 프로젝트를 만들 수 있습니다. 여러 앱의 경우 Play Developer API에는 동일한 Google Cloud 프로젝트를 사용해야 하지만, 각 앱은 자체 프로젝트로 게시할 수 있습니다.

구축 전에 규모를 산정하세요. 알림의 데이터 부분은 요청당 약 1 KB이며, 게시와 풀 각각이 별도 요청이므로 알림 하나당 약 2 KB입니다. 월간 볼륨은 청구 주기와 사용자 행동에 따라 달라지지만, 사용자당 청구 주기당 최소 1건의 알림을 기준으로 잡고, 해당 수치로 Pub/Sub 가격과 할당량을 확인하세요.

2단계 — Google Play에 게시 권한 부여하기

새로 만든 주제는 액세스 권한을 부여하기 전까지 Play의 게시 요청을 조용히 거부합니다. 많은 분이 놓치는 단계가 바로 이것이죠. Google Cloud Console에서 프로젝트를 선택하고 Pub/Sub을 연 뒤, 해당 주제를 찾아 권한 세부정보를 열고 서비스 계정을 추가하세요.

google-play-developer-notifications@system.gserviceaccount.com

그리고 Pub/Sub 게시자 역할을 부여하십시오. 저장하면 주제 설정이 완료됩니다. 기업 환경의 변수 하나: 조직의 도메인 제한 공유 설정이 이 부여를 차단한다면, Play가 무언가를 게시할 수 있도록 해당 Google Play 서비스 계정에 대한 예외를 추가해야 합니다.

3단계 — 구독에 푸시 또는 풀 방식 선택

토픽은 읽을 수 있는 메일함이 아닙니다. 토픽에 구독을 연결해야 합니다. 푸시 구독은 Cloud Pub/Sub이 보안 백엔드로 HTTPS 요청을 보내도록 합니다. 풀 구독은 백엔드가 Pub/Sub에 요청을 보내 메시지를 가져와야 합니다. RTDN에 대한 Google의 안내는 다음과 같습니다. 확실하지 않다면 푸시를 사용하세요. "일반적으로 구현이 더 쉽기 때문"입니다. 풀은 대량의 메시지를 처리할 때 리소스 활용을 최적화하는 데 주로 사용됩니다.

이 선택에서 두 가지 운영 규칙이 나옵니다. 풀 방식에서는 가져온 모든 메시지를 확인 응답해야 합니다. 그렇지 않으면 Pub/Sub가 계속 재전송합니다. 푸시 방식에서는 엔드포인트의 성공 응답 코드가 확인 응답 역할을 합니다. 엔드포인트가 느리거나 실패하면 전송이 반복됩니다.

4단계 — Play Console에서 RTDN을 활성화하고 테스트 전송하기

  1. Google Play Console을 열고 앱을 선택한 뒤 수익화 → 수익화 설정으로 이동하세요.
  2. 해당 페이지 상단의 실시간 개발자 알림 섹션에서 실시간 알림 사용을 체크하세요.
  3. 주제 이름 필드에 projects/{project_id}/topics/{topic_name} 형식으로 전체 주제 이름을 입력하세요.
  4. 테스트 메시지 전송을 클릭하세요. 풀 방식은 Cloud Console에서 구독을 열고 메시지 보기를 클릭해 가져온 뒤 확인 응답하세요. 푸시 방식은 테스트 메시지가 엔드포인트에 도달했는지 확인하세요.
  5. 알림 범위를 선택하세요. 구독 및 모든 무효화된 구매는 구독 및 무효화된 구매 이벤트만 제공합니다. 구독 및 일회성 상품에 대한 모든 알림은 ONE_TIME_PRODUCT_PURCHASED, ONE_TIME_PRODUCT_CANCELED과 같은 일회성 상품 구매 이벤트도 전송합니다.
  6. 변경사항 저장을 클릭하세요.

테스트 게시가 실패하면 콘솔에 오류가 표시되며, 현실적인 원인은 두 가지뿐입니다. 토픽 이름이 잘못되었거나, google-play-developer-notifications@system.gserviceaccount.com에 해당 토픽의 Pub/Sub 게시자 권한이 없는 경우입니다. 앱이 아니라 권한 부여를 고치세요.

메시지에 실제로 담기는 내용

토픽에 게시되는 모든 메시지는 동일한 구조를 가집니다. attributes 맵, base64로 인코딩된 data 필드, messageId, subscription 경로입니다. data를 디코딩하면 네 가지 정보(version, packageName, eventTimeMillis)와 정확히 하나의 페이로드 필드를 담은 DeveloperNotification이 나옵니다. 이 페이로드 필드들은 상호 배타적입니다. subscriptionNotification, oneTimeProductNotification, voidedPurchaseNotification, 또는 testNotification 중 하나입니다.

messageId는 알림의 고유 식별자이며, 참조 가이드는 중복 알림을 처리하거나 불필요한 백엔드 API 호출을 하지 않도록 고유성을 확인할 것을 권장합니다. 그런 호출은 RTDN이 보호하려는 API 할당량을 그대로 낭비하기 때문입니다.

구독 알림 유형

subscriptionNotification에는 notificationType 정수, purchaseToken, 그리고 자체 version이 포함됩니다. 현재 목록은 다음과 같습니다.

  • 1 — SUBSCRIPTION_RECOVERED: 계정 보류에서 복구되었거나 일시 중지에서 재개됨.
  • 2 — SUBSCRIPTION_RENEWED: 활성 구독이 갱신되었습니다.
  • 3 — SUBSCRIPTION_CANCELED: 자발적 또는 비자발적으로 취소됨. 자발적 취소의 경우 사용자가 취소할 때 전송됩니다.
  • 4 — SUBSCRIPTION_PURCHASED: 새 구독이 결제되었습니다.
  • 5 — SUBSCRIPTION_ON_HOLD: 계정 보류를 활성화한 경우 진입한 상태입니다.
  • 6 — SUBSCRIPTION_IN_GRACE_PERIOD: 유예 기간을 활성화한 경우 유예 기간 진입.
  • 7 — SUBSCRIPTION_RESTARTED: 사용자가 만료 전에 Play → 계정 → 구독에서 취소한 구독을 다시 활성화했습니다.
  • 9 — SUBSCRIPTION_DEFERRED: 반복 주기가 연장되었습니다.
  • 10 — SUBSCRIPTION_PAUSED / 11 — SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED: 일시중지되었거나 일시중지 일정이 변경되었습니다.
  • 12 — SUBSCRIPTION_REVOKED: 만료 시각 전에 취소됨.
  • 13 — SUBSCRIPTION_EXPIRED: 구독이 만료되었습니다.
  • 17 — SUBSCRIPTION_ITEMS_CHANGED: 구독 번들의 항목이 변경됨.
  • 18 — SUBSCRIPTION_CANCELLATION_SCHEDULED: 할부 약정 기간 종료 시점에 해지가 예약된 상태입니다.
  • 19 — SUBSCRIPTION_PRICE_CHANGE_UPDATED: 구독 항목의 가격 변경 세부 정보가 업데이트되었습니다.
  • 20 — SUBSCRIPTION_PENDING_PURCHASE_CANCELED: 대기 중인 구독 거래가 취소되었습니다.
  • 22 — SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED: 가격 인상 동의 기간이 시작되었거나 사용자가 동의했습니다. 가격 인상이 요구되는 지역에서만 전송됩니다.

8(SUBSCRIPTION_PRICE_CHANGE_CONFIRMED) 유형은 참조 문서에서 지원 종료로 표시되어 있으므로 새로운 로직을 여기에 구축하지 마세요. 또한 이 숫자들은 추론할 수 있는 생애주기가 아닙니다. 이벤트는 상태가 변경되었음을 알려줄 뿐, 결과 상태를 알려주지 않습니다.

일회성 상품 알림

더 넓은 범위를 선택한 경우에만 전송됩니다. oneTimeProductNotification은 토큰에 sku 필드를 추가하며 두 가지 유형이 있습니다. 1 — ONE_TIME_PRODUCT_PURCHASED(일회성 상품이 정상적으로 구매됨)와 2 — ONE_TIME_PRODUCT_CANCELED(대기 중인 일회성 구매가 사용자에 의해 취소됨)입니다. 두 경우 모두 Developer API 호출이 필요합니다. 구매 알림만으로는 상품을 아직 소비했는지 또는 확인했는지 알 수 없기 때문입니다.

무효 처리된 구매와 refundType 필드

voidedPurchaseNotification은 수익 팀이 가장 주목하는 RTDN이며, 2026년에는 단순한 토큰 그 이상을 담고 있습니다. 페이로드는 purchaseToken, orderId, productType, refundType입니다. productType은 구독의 경우 1, 일회성 구매의 경우 2입니다. refundType은 1 — REFUND_TYPE_FULL_REFUND 또는 2 — REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND이며, 후자는 여러 개 수량 구매에만 적용되어 여러 번 부분 무효화될 수 있습니다. 남은 총 수량이 모두 환불되면 유형은 전체 환불로 보고됩니다.

참조 가이드는 권한을 조정할 올바른 구매 및 주문을 찾는 데 알림 자체로 충분하다고 명시하며, Google Play 무효화된 구매 API가 타임스탬프 범위의 무효화된 구매 데이터를 반환하는 풀 방식의 보완 수단이라고 밝힙니다. 여러 수량 중 일부 환불의 경우 purchases.productsv2의 refundableQuantity 필드로 아직 무효화되지 않은 구매 제품 수를 확인할 수 있습니다. 이는 2026년 Play 환불 및 지불 거절 가이드에서 다룬 지불 거절 및 환불 회계 변경 사항과 직접 연결됩니다.

파이프라인을 올바르게 유지하는 서버 규칙

  • 알림을 답이 아닌 질문으로 취급하세요. RTDN이 올 때마다 Developer API를 호출해 전체 상태를 확인한 후 권한을 부여, 연장, 취소하세요.
  • messageId 기준으로 중복을 제거하세요. Pub/Sub은 최소 1회 전달을 보장하므로, 중복 처리는 곧 중복 API 호출과 중복 상태 전환을 의미합니다.
  • 항상 확인 응답 후 처리하세요. 풀: 가져온 메시지에 확인 응답합니다. 푸시: 성공 코드를 반환합니다. 처리 시간이 확인 응답보다 길다면 재전송을 허용하고 핸들러를 멱등하게 만드세요.
  • 사용자 한 명당 여러 이벤트가 발생할 수 있습니다. purchaseToken 하나로 같은 구독자에 대해 구매, 취소, 만료 알림이 차례로 발생할 수 있으므로, 핸들러는 반복 실행해도 안전해야 합니다.
  • 보완용으로 폴링하지 마세요. RTDN과 함께 Developer API를 폴링하는 것이 바로 할당량 제한을 유발하는 실패 패턴입니다.

설정 확인 중

콘솔의 테스트 메시지 전송은 가장 빠른 엔드투엔드 검증입니다. 구독을 연결해 두었다면 메시지를 받아야 합니다. testNotification 본문에는 version 필드만 있으므로 핸들러의 테스트 스위트에서 검증하기에 안전한 페이로드입니다. 아직 백엔드가 없다면 gcloud 명령줄로 구독에서 메시지를 가져오세요. 그리고 확인 응답(acknowledge)하는 것을 잊지 마세요. 건강한 파이프라인은 packageName이 앱과 일치하고 eventTimeMillis가 실시간 구독자 활동을 반영하는 이벤트 스트림으로 나타납니다.

일정 관련 참고 사항 하나: 서버 측 RTDN 작업은 클라이언트 측 결제 라이브러리 마감 기한과 맞물려 있습니다. 모든 신규 앱과 업데이트는 결제 라이브러리 버전 8 이상을 사용해야 하며, 연장 경로는 2026년 11월 1일까지 이어집니다. RTDN을 소비하는 서버 검증도 같은 시점에 준비되어야 합니다.

개발자 계정을 대규모로 운영하시나요? 운영 업무를 저희가 처리합니다.

클릭하여 파일 선택 · 우클릭 → 붙여넣기, 또는 Ctrl/⌘+V로 스크린샷 붙여넣기

파일을 이 상자로 끌어다 놓아도 됩니다.

입력하신 이메일로 답변드립니다. 고객님의 정보는 KappS에만 보관됩니다.

✔ 제출 완료

메시지를 접수했습니다. 24시간 이내에 답변드리겠습니다.


← 수정으로 돌아가기