Google Play Integrity API 2026: 단계별 가이드
Play Integrity API는 백엔드에 하나의 좁고 실용적인 질문에 답합니다. 이 요청이 Google Play이 배포한 내 앱의 사본에서, 그리고 주장하는 그대로의 기기에서 오는 것인가? 서버는 Google에 무결성 판정을 요청하고 서명된 페이로드를 받은 뒤, 해당 상호작용을 어디까지 신뢰할지 결정합니다. 이 결정은 반드시 서버에서 내려야 하며 클라이언트에서 내려서는 안 됩니다. 변조된 빌드, 스크립트 클라이언트, 에뮬레이터, 사이드로드된 사본이 게임 경제, 구독 권한, 광고 수익에 도달하기 전에 차단 속도를 높이는 표준 방식입니다.
이 가이드는 실제로 작업하게 될 순서를 따릅니다. API 활성화, Cloud 프로젝트 연결, 표준 요청과 클래식 요청 중 선택, 토큰 제공자 워밍업, 토큰 요청 및 복호화, 판정 필드 읽기, 할당량과 오류 코드 처리, 유료 사용자를 차단하지 않으면서 시행 단계적 적용. 이 모든 과정을 관통하는 원칙이 하나 있습니다. API는 스스로 판단할 수 있는 신호를 제공할 뿐이며, 무결성 검사를 통과하는 유일하게 지속 가능한 방법은 공식 채널을 통해 정품 앱을 출시하는 것입니다.
1. API가 증명하는 것과 증명하지 않는 것
기본적으로 세 가지 판정 유형이 반환되며, 각각 다른 질문에 답합니다.
- appIntegrity — 수정되지 않은 바이너리에서 나온 것인가?
appRecognitionVerdict는 패키지와 인증서가 Google Play에서 배포하는 것과 일치하면PLAY_RECOGNIZED를, 인증서나 패키지 이름이 Play 기록과 일치하지 않으면UNRECOGNIZED_VERSION을, 사전 조건이 충족되지 않으면UNEVALUATED를 반환합니다. - deviceIntegrity — 기기가 정품인가? 기본적으로
deviceRecognitionVerdict에는MEETS_DEVICE_INTEGRITY가 포함될 수 있습니다. 이는 정품 인증된 Android 기기이며, Android 13 이상에서는 부트로더가 잠겨 있고 로드된 소프트웨어가 정품이라는 하드웨어 기반 증명이 제공됩니다. 어떤 레이블도 충족하지 못하는 기기는 해당 필드가 그냥 생략됩니다. - accountDetails — 사용자에게 이용 권한이 있나요?
appLicensingVerdict는LICENSED(Google Play에서 설치 또는 업데이트됨),UNLICENSED,UNEVALUATED중 하나를 반환합니다.
필드 목록보다 중요한 두 가지 원칙이 있습니다. 첫째, Google는 API가 다른 신호와 함께, 전반적인 어뷰징 방지 전략의 일부로 사용될 때 가장 잘 작동하며 단독 메커니즘이 아니라고 분명히 밝힙니다. 판정은 하나의 입력일 뿐이며, 이를 유일한 관문으로 삼으면 오탐과 손쉬운 우회가 동시에 발생합니다. 둘째, 이는 위험 신호이지 사용자에 대한 판단이 아닙니다. 루팅된 기기를 쓰는 취미 사용자가 범죄자가 아니며, 대응은 해당 화면에서 실제로 걸린 위험에 비례해야 합니다.
2. 1단계 — API 활성화 및 Cloud 프로젝트 연결
API를 호출하는 모든 앱이나 SDK에는 Google Cloud 프로젝트가 필요합니다. 사용량 모니터링과 할당량 관리가 이곳에서 이루어지기 때문입니다.
- Google Cloud Console에서 새 프로젝트를 만들거나 사용할 기존 프로젝트를 선택하세요.
- API 및 서비스 → API 및 서비스 사용 설정으로 이동해 Play Integrity API를 검색하고 사용 설정을 클릭하세요.
- 그런 다음 해당 프로젝트를 앱에 연결하세요. Play Console에서 앱을 열고 Protected with Play로 이동해 Play Integrity API를 찾은 뒤 시작하기를 선택하세요.
연결이 나머지 모든 것을 가능하게 하는 단계입니다. Cloud에서 활성화되었지만 Play Console(SDK의 경우 Play SDK Console)에서 연결되지 않은 프로젝트는 추가 구성 옵션이나 할당량 증가 대상이 되지 않습니다. 콘솔 단계를 건너뛰었다면 연결 흐름에서 API를 대신 활성화해 주므로 순서는 상관없지만, 연결을 건너뛰면 안 됩니다.
복호화에는 앱이 절대 보유해서는 안 되는 자격 증명이 필요합니다. 연결된 Cloud 프로젝트 안에 서비스 계정을 만들고 playintegrity 범위로 서버에서 디코드 엔드포인트를 호출하세요. 클라이언트는 토큰을 요청만 하고, 토큰을 여는 것은 서버뿐입니다.
3. 2단계 — 표준 요청 또는 클래식 요청 선택
요청 방식은 두 가지이며, 처음에 올바른 방식을 선택하면 나중에 재작업을 피할 수 있습니다.
- 표준 요청은 Google Play 앱의 기본 선택입니다. Android 5.0(API 레벨 21) 이상에서 작동하며, 두 번의 호출로 구성됩니다. 무결성 토큰 제공자를 미리 준비한 뒤, 실제로 토큰이 필요할 때 요청하세요.
- 클래식 요청은 표준 요청으로 처리되지 않는 경우, 특히 Google Play 외부에서만 배포되는 앱과 SDK를 위해 존재합니다. 구조적으로 클래식 요청은 직접 생성한
nonce를 받는 단일 호출이며, Play에서 배포되지 않는 앱은setCloudProjectNumber()로 Cloud 프로젝트 번호도 함께 전달해야 합니다. Play에 등록된 앱은 콘솔에서 연결되므로 요청에서 이를 설정하지 않습니다.
앱이 Google Play에 있다면 표준이 정답입니다. 클래식은 배포가 실제로 Play 외부에서 이루어지거나 특정 통합 때문에 제약을 받을 때만 선택하세요.
4. 3단계 — 공급자를 워밍업한 후 토큰 요청하기
표준 요청은 느린 부분이 사용자의 핵심 경로에 절대 걸리지 않도록 의도적으로 둘로 나뉩니다.
무결성 토큰 제공자를 준비하거나 워밍업하세요. 판정이 필요하기 훨씬 전에 호출하세요. 보통 앱 실행 시점이 좋은데, 호출이 비동기라 시작 시간에 영향을 주지 않기 때문입니다. 워밍업을 하면 Google Play가 기기에 부분 증명 정보를 캐시해 이후 요청이 빨라지고, 다시 준비하는 것도 다음 판정을 더 최신으로 만드는 가벼운 방법입니다. 제공자 자체는 너무 오래 유지하면 만료될 수 있으며, 이는 INTEGRITY_TOKEN_PROVIDER_INVALID로 나타납니다. 이 경우 오래된 제공자를 재시도하지 말고 새 제공자를 요청해 처리하세요.
필요할 때 무결성 토큰을 요청하세요. 앱이 서버 호출을 하면서 그 호출이 정당함을 보증하고 싶다면, 토큰을 요청해 백엔드로 전송하세요. 요청 해시를 함께 첨부하세요. 안정적인 파라미터의 SHA-256 다이제스트 같은 값을 계산해 전달하면 됩니다. API가 서명된 응답 안에 이 값을 그대로 되돌려 주기 때문입니다. 이 값이 없으면 토큰은 기기에만 묶이고 특정 요청에는 묶이지 않아, 프록시가 토큰을 다른 용도로 재사용할 수 있는 틈이 생깁니다.
클래식 요청은 대신 직접 제공하는 논스를 사용합니다. 이 값은 그대로 Google에 전달되므로 개인정보나 민감 정보를 절대 넣지 마세요. 또한 허용된 길이의 유효한 Base64여야 하며, 그렇지 않으면 판정 대신 NONCE_TOO_SHORT, NONCE_TOO_LONG 또는 NONCE_IS_NOT_BASE64 오류가 발생합니다.
5. 4단계 — 서버에서 복호화 및 검증하기
백엔드에 도달하는 토큰은 암호화되어 있으며 Google이(가) 복호화하기 전까지는 쓸모가 없습니다. 서비스 계정 자격 증명과 playintegrity 범위를 사용해 서버에서 호출합니다:
POST https://playintegrity.googleapis.com/v1/PACKAGE_NAME:decodeIntegrityToken { "integrity_token": "INTEGRITY_TOKEN" }
돌아오는 것은 일반 텍스트 JSON 페이로드입니다. 판정을 하나라도 보기 전에 요청 세부 정보를 검증하세요. 페이로드는 귀하의 요청에 대한 답일 때만 의미가 있습니다:
requestPackageName은 패키지 이름과 일치해야 합니다;requestHash가 전송한 해시와 일치해야 합니다;timestampMillis는 최근 값이어야 합니다 — 신선도 기간(허용되는 밀리초 범위)과 비교해 그보다 오래된 값은 거부하세요. 오래된 토큰은 재전송 공격 후보이기 때문입니다.
Google Play는 자동 재전송 방지도 적용하여 무결성 토큰이 여러 번 재사용되는 것을 막습니다. 이는 자체 신선도 검사를 대체하는 것이 아니라 안전망으로 여기고, 토큰을 하루 동안 캐시하지 말고 액션 시점에 서버 측에서 복호화하세요.
6. 과도한 차단 없이 페이로드 읽기
페이로드는 requestDetails, appIntegrity, deviceIntegrity, accountDetails, 그리고 옵트인하면 environmentDetails를 포함하는 JSON입니다. 필드 순서는 보장되지 않으므로 항상 키로 읽어야 합니다. 실용적인 판단 단계는 다음과 같습니다.
- 먼저 앱을 확인하세요:
PLAY_RECOGNIZED는 바이너리와 인증서가 Play에서 배포하는 것과 일치함을 의미합니다. - 그다음 기기를 확인하세요.
MEETS_DEVICE_INTEGRITY가 기본 기준입니다. 추가 라벨인MEETS_BASIC_INTEGRITY,MEETS_STRONG_INTEGRITY,MEETS_VIRTUAL_INTEGRITY는 선택 사항이며, 첫 출시가 아니라 단계별 전략에 속합니다. - 권한이 중요한 상황에서는
accountDetails를 사용하세요.UNLICENSED는 해당 계정에 Play 권한이 없다는 뜻이지만, 일부 구형 기기에서는 삭제 후에도 권한이 남아 있을 수 있으므로 사실로 단정하지 말고 신호로 읽어야 합니다. environmentDetails를 활성화했다면,appAccessRiskVerdict가 화면을 캡처하거나 오버레이를 그릴 수 있는 앱이 있는지 알려 줍니다. 이때appsDetected목록에는KNOWN_INSTALLED,UNKNOWN_INSTALLED,UNKNOWN_CAPTURING같은 값이 사용되며, Play Protect 판정은 기기의 Play Protect 상태를 요약합니다.
눈에 잘 띄지 않는 두 가지 사례에 설계상 주의가 필요합니다. 시스템 무결성 검사를 통과하고 핵심 Android 호환성 요건을 충족하는 에뮬레이터는 자체적인 기기 레이블을 받을 수 있으므로, "에뮬레이터"가 곧 "공격자"를 의미하지는 않습니다. 또한 어떤 레이블에도 해당하지 않는 기기는 해당 필드를 아예 생략하므로, 키가 항상 존재한다고 가정하는 코드는 안전하게 실패하는 대신 크래시가 발생합니다.
7. 할당량, 오류 코드, 안전한 실패 처리
기본적으로 앱은 모든 설치를 합산해 하루 최대 10,000건의 요청을 보낼 수 있습니다. 출시 후에는 팀이 예상하는 것보다 이 한도에 빨리 도달하므로, 연결된 Cloud 프로젝트에서 사용량을 주시하고 추세선에 여유가 있을 때 증량을 요청하세요. 한도를 초과하면 TOO_MANY_REQUESTS(오류 코드 -8)로 나타나며, 사용자를 차단하는 대신 지수 백오프로 대응해야 합니다.
연동에서 문제가 생기는 지점은 대개 오류 처리입니다. 다음은 일시적 오류로 보고 백오프를 적용해 재시도하세요: NETWORK_ERROR(-3), TOO_MANY_REQUESTS(-8), GOOGLE_SERVER_UNAVAILABLE(-12), CLIENT_TRANSIENT_ERROR(-18). 나머지는 환경 문제입니다. Play 스토어가 없거나, Play 서비스가 없거나, Play 서비스 버전이 오래되었거나, Play 계정이 없거나, API가 거부하는 Cloud 프로젝트 번호인 경우입니다. 이런 경우 Google의 안내에 따르면 클라이언트가 검사를 통과하지 못한 것으로 간주하되, 합리적으로 가능한 범위에서는 사용자가 계속 조작할 수 있게 유지해야 합니다.
오류는 단순한 코드 경로가 아니라 정책 문제로 다루세요. 기기가 특이해 보이는 모든 사용자를 차단하면 남용 방지 신호가 리텐션 문제로 바뀌고, 모든 실패를 조용히 무시하는 것은 정반대의 실수입니다. 화면별로 결정하세요 — 리더보드는 관대하게, 지갑 충전은 엄격하게 — 그리고 그 결정을 문서로 남겨 다음 엔지니어가 판단 근거를 이어받을 수 있게 하세요.
Google는 시정 조치 대화상자도 제공합니다. 앱이 트리거하고 Google가 안내하는 흐름으로, 정당한 사용자가 Play에서 공식 빌드를 설치하거나 연결을 복원하는 등 근본 문제를 해결하도록 돕습니다. 막다른 상황에 내버려 두지 않습니다. 그리고 시행 이후 동일한 하드웨어에서 반복적인 남용을 찾아내야 한다면, 기기 리콜 기능(베타)이 바로 그 용도로 만들어졌습니다.
8. 사용자에게 문제 없이 배포하기
시행 전에 텔레메트리부터. 무언가를 차단하기 전에 몇 주 동안 판정 결과와 그 분포를 기록하세요. 그러면 다른 사람의 블로그 글이 아니라 자사 설치 기반에서 UNEVALUATED와 UNLICENSED 결과의 실제 비율을 알 수 있습니다. 그다음 단계적으로 시행하세요. 먼저 기본 기기 라벨, 나중에 추가 라벨, 한 번에 한 화면씩. 클라이언트가 "재시도"와 "불가"를 구분할 수 있게 유지하고, API를 단순히 사용할 수 없을 때 앱이 우아하게 성능을 낮추도록 하세요. 불안정한 네트워크의 사용자가 이미 결제한 콘텐츠에 대한 접근을 잃어서는 안 됩니다.
9. KappS의 위치
KappS는 개발자가 계정과 릴리스를 플랫폼의 심사 기준을 견디는 상태로 유지하도록 돕습니다 — 컴플라이언스 자료를 준비하고 제출하는 것이지, 심사를 우회하는 것이 아닙니다. 실제로는 다음을 의미합니다:
- 릴리스 위생. Play 앱 서명으로 서명되고, 공식 채널을 통해 업로드되며, 버전 코드와 인증서가 Google Play이 인식하는 기록과 일치해야 합니다.
PLAY_RECOGNIZED가 가능한 조건입니다. - 계정 준비 상태. 개발자 확인, 결제 프로필, 세금 기록을 계정의 법적 신원과 일치시켜, 무관한 심사 때문에 출시가 지연되지 않도록 합니다.
- 연동 검토. 클라이언트가 토큰을 어떻게 요청하는지, 서버가 무엇을 기준으로 분기하는지, 시행 단계가 비즈니스 리스크에 맞는지 한 번 더 점검합니다.
저희는 무결성 우회, 판정 스푸핑, 또는 변조된 빌드를 Play에서 숨기는 도구를 제공하지 않으며 앞으로도 제공하지 않습니다. 그것들은 바로 이 API가 탐지하기 위해 존재하는 대상이고, 계정을 위험에 빠뜨리며, 저희가 제공하는 서비스가 아닙니다. 무결성 검사를 통과하는 유일하게 지속 가능한 방법은 진짜 정품이 되는 것입니다.
출처(Google 공식 문서): Play Integrity API — 개요, 설정, 표준 요청 보내기, 클래식 요청 보내기, 무결성 판정 정보, 기기 리콜 사용, 오류 코드 처리, 시정 조치 대화상자(developer.android.com).
개발자 계정을 대규모로 운영하시나요? 운영 업무를 저희가 처리합니다.
메시지를 접수했습니다. 24시간 이내에 답변드리겠습니다.
← 수정으로 돌아가기