KappS 지식 베이스 · 블로그

Google Play 2026년 개발자 리포팅 API

블로그 튜토리얼

Google Play 콘솔에서 이미 크래시와 ANR 수치를 확인할 수 있습니다. 다만 그 화면은 앱 하나, 사람 한 명, 반나절 작업을 전제로 만들어졌습니다. Play Developer Reporting API는 다른 용도를 위한 것입니다. 운영 중인 모든 앱의 동일한 품질 데이터를 정해진 주기로 자체 데이터 웨어하우스나 알림 파이프라인으로 가져오는 것이죠. 두 번째 콘솔이 아니라, 탭 40개를 열지 않고도 40개 앱에 같은 질문을 던지는 표준화된 방법입니다.

이 튜토리얼은 2026년에 실제로 통하는 순서, 즉 잘못했을 때 오류가 나타나는 순서대로 정리한 것입니다. 프로젝트, 서비스 계정, Play Console 권한, 앱 검색, 최신성, 쿼리, 측정기준, 이상 징후 순입니다. 모든 단계는 문서화된 호출이며, 대부분의 팀이 무너지는 지점은 3단계의 Play Console 초대와 7단계의 시간대 가정, 이 두 곳입니다.

1. 코드를 작성하기 전에 API가 반환하는 값을 파악하세요

이 서비스는 지표 세트를 제공합니다. 동일한 세분성을 공유하며 함께 조회할 수 있는 관련 지표의 논리적 그룹입니다. 문서화된 세트는 ANR 비율, 크래시율, 과도한 웨이크업 비율, 백그라운드 웨이크락 지연 비율, 느린 시작 비율, 느린 렌더링 비율, LMK(저메모리 킬) 비율, 익명 RSS 및 스왑 메모리 사용량, 비트맵 메모리 사용량, 오류 건수를 다룹니다. 각 세트에는 crashRate, userPerceivedCrashRate 같은 정규화 지표와 함께 7일·28일 사용자 가중 평균이 포함됩니다.

이 설계에서 두 가지 실용적인 사실이 나옵니다. 첫째, 이는 집계 값입니다. 즉 고유 사용자 비율, 메모리의 백분위수이므로 사용자 수준 데이터를 처리하지 않고도 서버에서 API를 안전하게 실행할 수 있습니다. 둘째, 일부 리소스는 버전 번호가 시사하는 것보다 범위가 좁습니다. 오류 횟수 집합은 API의 v1alpha1 버전에서만 사용할 수 있으며, 그 외에는 v1beta1과 v1alpha1이 동일한 메서드 형태로 동일한 리소스를 노출합니다. 버전은 프로젝트 단위가 아니라 리소스 단위로 결정하세요.

2. Cloud 프로젝트 생성 및 API 활성화

여전히 API가 활성화된 Google Cloud 프로젝트가 필요하지만, 2026년 변경 사항으로 인해 아직도 많은 팀이 준비하는 단계 하나가 사라졌습니다. Reporting API를 사용하기 위해 더 이상 Play 개발자 계정을 Cloud Console에 연결할 필요가 없습니다. 문서에 나온 네 단계는 다음과 같습니다. Cloud 프로젝트를 생성(또는 재사용)하고, 해당 프로젝트에서 Google Play Developer Reporting API를 활성화하고, 서비스 계정을 생성한 뒤, Play Console에서 해당 서비스 계정에 접근 권한을 부여합니다.

API 활성화는 Cloud Console의 API 페이지에서 클릭 한 번이면 됩니다. 일회용 프로젝트가 아니라 이미 결제와 IAM이 설정된 프로젝트에서 하세요. 서비스 계정 키는 이를 만든 사람보다 오래 살아남고, 방치된 프로젝트는 1년 뒤 모니터링이 조용히 죽는 원인이 됩니다.

3. 서비스 계정에 정확히 하나의 범위를 부여한 다음, Play Console 역할 하나를 부여하세요

서비스 계정은 무인 작업에 권장되는 방식이며, 서버 밖으로 절대 나가서는 안 되는 JSON 키로 인증합니다. 이 API의 모든 호출은 단일 OAuth 스코프로 권한을 부여합니다:

https://www.googleapis.com/auth/playdeveloperreporting

그다음은 첫 403 오류를 실제로 좌우하는 권한입니다. API를 활성화하는 것과 데이터를 읽을 권한을 갖는 것은 다릅니다. Play Console의 사용자 및 권한으로 이동해 서비스 계정 자체 주소(your-name@your-project.iam.gserviceaccount.com)를 초대하고, 조회하는 지표 집합에 필요한 최소 권한만 부여하세요. Google의 자체 지침도 API 작업별로 최소 권한 집합을 부여하라고 하며, 지표 집합마다 필요한 권한이 다릅니다. 보고 작업에는 관리자, 릴리스 관리, 재무 접근 권한이 전혀 필요하지 않습니다.

키 파일은 저장소 외부에 보관하고, 앱마다 하나씩 두는 대신 포트폴리오마다 서비스 계정 하나를 유지하세요. 자격 증명 하나를 교체하는 데는 5분이면 충분하지만, 서른 개를 교체하려면 주말이 통째로 사라집니다.

4. 계정에서 볼 수 있는 앱 ID 확인하기

Before any metric call, resolve which apps the credential can reach. The service endpoint is https://playdeveloperreporting.googleapis.com, and the app list comes from:

GET /v1beta1/apps:search

포트폴리오마다 한 번씩 실행하고 결과를 캐시하세요. 3단계의 초대가 제대로 작동했음을 증명하는 가장 저렴한 방법입니다. 유효한 토큰이 있는데 목록이 비어 있다면, 거의 항상 서비스 계정이 잘못된 계정에 초대되었거나, 초대는 되었지만 앱 가시성을 포함한 권한이 부여되지 않은 것입니다.

5. 숫자를 신뢰하기 전에 최신성 확인하기

각 지표 세트는 사용 가능한 최신 데이터 포인트의 타임스탬프, 즉 신선도를 반환하는 단순한 GET에 답하며, 지원되는 세분화 단위(일간 및 시간별)마다 값이 하나씩 나옵니다. 어제 데이터가 있을 것이라 가정하지 말고 모든 예약 실행을 여기서 시작하십시오. 반환된 신선도 값을 쿼리 범위의 종료점으로 그대로 사용하면 작업이 스스로 정렬됩니다. 하드코딩된 지연도, 조용한 릴리스 다음 날 아침의 빈 응답도 없습니다.

데이터 포인트 누락은 0이 아닙니다. 조회 범위에 행이 없어서 웨어하우스가 0.0%를 기록하면, 누군가 콘솔을 확인하는 날까지 대시보드는 완벽한 앱을 보여줄 것입니다.

6. POST :query 메서드로 세트 조회하기

데이터는 목록 호출이 아니라 지표 집합 리소스의 커스텀 :query 메서드에서 나옵니다. 모든 쿼리는 세분성, 시간 범위, 지표, 그리고 분류 기준 차원을 명시합니다:

POST https://playdeveloperreporting.googleapis.com/v1beta1/apps/<package>/crashRateMetricSet:query // body { "timelineSpec": { "aggregationPeriod": "DAILY", "startTime": { "year": 2026, "month": 10, "day": 14 }, "endTime": { "year": 2026, "month": 10, "day": 20 } }, "dimensions": ["versionCode", "countryCode"], "metrics": ["crashRate", "userPerceivedCrashRate", "distinctUsers"], "pageSize": 1000 }

응답은 요청한 차원을 기준으로 키가 지정된 행 목록이며, 읽을 내용이 더 있으면 pageToken이 함께 제공됩니다. filter는 차원 동등 조건으로 행을 좁힙니다. 페이지네이션은 지표 세트 전반에서 동일한 형태이므로, 범용 페이저 하나로 크래시율, ANR 비율, 메모리를 모두 처리할 수 있습니다.

7. 의도적으로 지표를 선택하라 — 그리고 두 가지 시간 함정을 주의하라

API가 콘솔보다 확실히 강점을 발휘하는 지점은 바로 차원(dimension)입니다. versionCode는 전체 크래시율을 릴리스별 회귀 검사로 바꿔 줍니다. countryCode는 새 SDK가 문제를 일으키는 시장을 분리해 냅니다. 기기 차원인 deviceModel, deviceType, apiLevel, deviceRamBucket, 그리고 SoC, CPU, GPU, 화면 필드는 "우리 코드가 깨졌다"와 "이 칩셋이 깨졌다"를 구분해 줍니다.

모든 팀이 한 번은 겪는 두 가지 시간대 함정이 있습니다. 일별 집계는 고정 America/Los_Angeles 시간대를 사용하고, 시간별 집계는 UTC로 고정된다고 문서화되어 있습니다. 업무일 기준이 CST라면 일별 버킷은 생각하는 시각에 시작되지 않으며, 현지 09:00에 배포한 릴리스는 두 버킷에 걸쳐 집계됩니다. 두 번째 함정: 빈 날짜는 대개 데이터 신선도 지연일 뿐이므로 5단계를 먼저 수행해야 합니다.

문서에는 설계 시 고려해야 할 성능상의 하드 리밋도 명시되어 있습니다. 요청하는 범위의 크기는 앱의 크기 및 분류 항목 수에 반비례해야 합니다. 규모가 큰 앱에서 6개 차원에 걸쳐 30일치를 요청하면 타임아웃이 발생합니다. 큰 앱이라면 무리한 단일 쿼리 대신 짧은 기간을 반복 조회하세요.

8. Google이(가) 이상 징후를 감지하도록 하세요

알림을 받기 위해 이 지표들 위에 임계값 계산을 직접 구현할 필요는 없습니다. API는 데이터셋 중 하나에서 Google가 이미 감지한 이상 항목을 활성 시점으로 필터링해 나열하는 anomalies 컬렉션을 제공합니다.

GET /v1beta1/apps/<package>/anomalies ?filter=activeBetween("2026-10-19T00:00:00Z","2026-10-21T00:00:00Z") &pageSize=50

두 경계값 모두 UTC 오프셋을 허용하는 RFC-3339 문자열이며, 한쪽 경계만 지정하는 경우 특수 값 UNBOUNDED를 사용할 수 있습니다. pageSize의 기본값은 10이고 최대 100입니다. 각 이상 항목에는 유형, 심각도, 영향을 받는 차원, 관련 지표가 포함되므로 정기 폴링 결과를 사람이 바로 조치할 수 있는 메시지로 깔끔하게 변환할 수 있습니다.

비율이 아닌 스택 트레이스가 필요하다면, 동일한 API가 오류 이슈와 오류 보고서를 — 클러스터링된 계층과 개별 계층 모두 — 두 버전에서 제공합니다. 이것이 "v1.4.2에서 크래시율이 두 배가 됐다"와 "문제를 일으킨 프레임은 이것이다"의 차이입니다.

9. 일정뿐 아니라 계정 라이프사이클에도 연동하라

3단계에서 부여한 권한은 개발자 계정에 속하므로 계정과 함께 이동합니다. Play 계정이 이전되거나, 포트폴리오가 매각되거나, 계정 정지 후 재구축되는 경우 새 소유자의 Play Console에서 서비스 계정을 다시 초대해야 하며, 그렇지 않으면 대시보드가 마지막으로 알려진 값을 유지하는 동안 모든 호출이 403을 반환합니다. 명시적으로 알림을 설정할 만한 실패 유형이 바로 이것입니다. 5xx뿐 아니라 403과 빈 앱 목록에도 알림을 걸어야 합니다. 자격 증명이 조용히 끊긴 상태에서도 API는 아무 문제 없이 "데이터 없음"으로 응답하기 때문입니다.

모니터링은 단순하게 유지하세요: 포트폴리오당 서비스 계정 하나, 최신 여부를 읽은 뒤 관심 있는 세트를 조회하는 예약 실행 하나, 두 번째 단계로 이상 징후 폴링, 그리고 변화가 없을 때는 조용한 하루 한 번의 메시지. 그 위에 얹는 것들 — 임계값, 추세 기준선, 국가별 보드 — 은 기반 구조를 다시 건드리지 않고 추가할 수 있는 분석입니다.

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

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

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

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

✔ 제출 완료

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


← 수정으로 돌아가기