KappS 지식 베이스 · FAQ

Google Play의 Google Play Integrity API 구현 및 이관

FAQ 기술 컴플라이언스

1. 이관은 선택이 아닙니다. SafetyNet은 완전히 종료되었습니다. Google은(는) 지원 종료 일정에서 이렇게 밝힙니다. "SafetyNet Attestation API는 2022년에 지원이 중단되었고 2025년 1월에 완전히 종료되었습니다. 개발자는 여러 무결성 기능(SafetyNet Attestation 무결성 판정 포함)을 단일 API로 통합한 Play Integrity API로 이관해야 합니다." 남아 있는 호출은 이제 실패합니다. "SafetyNet Attestation API를 호출하면 오류가 발생합니다. attest API는 항상 ApiException과 상태 코드 7(NETWORK_ERROR)로 onFailure 리스너를 호출하는 태스크를 반환합니다." SafetyNet을 호출하는 버전을 아직 배포하고 있다면 이용자에게 업데이트를 안내하십시오. (https://developer.android.com/privacy-and-security/safetynet/deprecation-timeline)

2. API가 실제로 검증하는 것. "Play Integrity API는 사용자 행동과 서버 요청이 Google Play이 설치하고 정품 인증된 Android 기기에서 실행 중인 정품 앱에서 오는지 확인하는 데 도움을 줍니다." 이 API는 세 가지 핵심 판정을 반환합니다. accountDetails(무단 접근 - 사용자가 Google Play에서 앱을 설치하거나 결제했는지 여부), appIntegrity(코드 변조 - 바이너리가 Google Play이 인식하는 수정되지 않은 버전인지 여부), deviceIntegrity(위험한 기기 및 에뮬레이션 환경 - 정품 인증된 Android 기기 또는 Google Play Games for PC의 정품 인스턴스인지 여부)입니다. 선택적 판정으로는 MEETS_STRONG_INTEGRITY(최근 보안 업데이트, Android 13 이상), appAccessRiskVerdict(다른 앱의 화면 캡처, 오버레이, 접근성 악용), playProtectVerdict(Play Protect 활성화 및 위험한 앱 없음), recentDeviceActivity(비정상적으로 높은 요청량), deviceRecall(베타)이 있습니다. (https://developer.android.com/google/play/integrity/overview)

3. Google Cloud 프로젝트를 만들고 연결하세요. "API를 통합하려면 Google Cloud 프로젝트가 있어야 합니다... 그런 다음 Google Play Console(앱의 경우) 또는 Google Play SDK Console(SDK의 경우)에서 Google Cloud 프로젝트를 연결할 수 있습니다. 프로젝트 연결은 필수입니다"라고 하며, 그래야 고급 기능과 할당량 증가가 열립니다. Google Cloud Console에서 Play Integrity API를 사용 설정하거나, 먼저 연결하면 자동으로 사용 설정됩니다. 함정을 주의하세요. "Google Cloud Console에서 사용 설정되었지만 Play Console 또는 Play SDK Console에서 연결되지 않은 프로젝트는 추가 기능을 사용할 수 없습니다." (https://developer.android.com/google/play/integrity/setup)

4. 표준 요청과 클래식 요청 중에서 선택하세요. 지연 시간과 캐싱에서 차이가 있습니다. 표준 요청은 지연 시간이 가장 짧고("평균 수백 밀리초") 사용 가능한 판정을 얻을 신뢰성이 높으며, 스마트 온디바이스 캐싱을 사용하고 특정 공격에 대한 보호를 Google Play에 위임합니다. 토큰 제공자를 한 번 준비("워밍업")하면("인스턴스는 분당 최대 5회까지만 무결성 토큰을 준비할 수 있습니다") 필요할 때 토큰을 요청합니다. 원래 경로인 클래식 요청은 지연 시간이 더 길고("평균 몇 초") 사용자의 데이터와 배터리를 더 많이 사용하는 새 평가를 시작하며 특정 완화 조치를 개발자에게 맡기므로, 매우 민감하거나 중요한 작업에 대해 "일회성으로 드물게" 수행해야 합니다. 두 방식 모두 Android 6.0(API 레벨 23) 이상이 필요합니다. 명확한 규칙: "클래식 요청을 수행하고 나중에 사용하려고 캐싱하는 것을 고려하고 있다면, 공격 위험을 줄이기 위해 대신 표준 요청을 수행해야 합니다." (https://developer.android.com/google/play/integrity/overview, https://developer.android.com/google/play/integrity/standard)

5. 검증은 반드시 서버에서, 클라이언트에서는 절대 하지 마세요. 흐름은 이렇습니다. 앱이 Google 클라우드 프로젝트 번호로 토큰 제공자를 준비하고, 요청 해시를 넘겨 무결성 토큰을 요청합니다. 서명되고 암호화된 토큰을 받으면 백엔드로 전달하고, 그다음 "앱의 백엔드가 토큰을 Google Play 서버로 보냅니다. Google Play 서버가 복호화해 판정 결과를 검증한 뒤 앱의 백엔드로 결과를 반환합니다." 판정은 백엔드에서만 적용하세요. 클라이언트 측 검사는 패치로 우회될 수 있습니다. (https://developer.android.com/google/play/integrity/standard)

6. 토큰을 특정 요청에 바인딩하세요. 표준 요청은 토큰을 요청할 때 제공한 요청 해시에 바인딩되고, 클래식 요청은 요청 데이터나 서버 측 로직에 기반한 콘텐츠 바인딩과 함께 nonce 필드를 사용합니다. 판정 결과를 캐시해 재사용하지 마세요. "판정을 캐시하면 유출과 재전송 같은 공격 위험이 커집니다." 클래식 판정을 나중을 위해 캐시할 생각이었다면 표준 요청으로 전환하세요. (https://developer.android.com/google/play/integrity/classic)

7. 할당량을 준수하세요. "기본적으로 앱은 모든 설치를 통합해 하루 최대 10,000건의 요청을 보낼 수 있습니다." 일일 최대치 상향을 요청할 수는 있지만 그 범위 안에서 계획을 세우고, 토큰 제공자는 드물게(인스턴스당 분당 최대 5회) 준비하세요. (https://developer.android.com/google/play/integrity/overview)

8. 정당한 사용자를 해치지 않으면서 판정을 단계적으로 적용하세요. Google의 명시적 권고 사항은 다음과 같습니다. 먼저 "시행 없이 API를 구현"하고, "조치를 취하기 전에 텔레메트리를 수집해 이용자층을 파악"한 다음, 계획 중인 시행의 영향을 추정해 남용 방지 전략을 조정하라는 것입니다. API는 전체 전략이 아닌 하나의 신호로 취급하세요. "Play Integrity API는 단독 남용 방지 수단이 아니라 전체 남용 방지 전략의 일부로 다른 신호와 함께 사용할 때 가장 효과적입니다." 이 API는 스마트폰, 태블릿, 폴더블, Android Auto, Android TV, Android XR, ChromeOS, Wear OS, PC용 Google Play Games 전반에서 사용할 수 있습니다. (https://developer.android.com/google/play/integrity/overview)

버전 및 할당량 경계 (2026-10-13 기준 Google 페이지 확인):

라이브러리 버전. 현재 릴리스(1.5.x 계열)는 표준 및 클래식 요청에 Android API 레벨 23(Android 6.0) 이상이 필요하며, 1.4.0 계열은 API 레벨 21(Android 5.0) 이상을 지원했습니다. 튜토리얼 대신 라이브러리 릴리스 노트에서 실제 배포 버전의 최소 요구 사항을 확인하세요.

할당량 유형. 기본 한도는 연결된 Cloud 프로젝트 번호에 묶인 하루 10,000건의 요청이며, Google는 토큰 요청(클라이언트 측)과 토큰 복호화(서버 측)를 별도의 할당량 작업으로 집계합니다. 클라이언트 측 요청이 많다고 해서 그 자체로 서버 측 복호화 할당량이 소모되지는 않습니다. 더 많은 볼륨이 필요하면 Google에 할당량 증액을 요청해야 합니다.

프로젝트 연결. API를 사용하려면 Play Console에서 앱에 연결된 Google Cloud 프로젝트(또는 Play SDK Console에서 SDK에 연결된 프로젝트)가 필요합니다. 할당량은 해당 프로젝트 번호에 연결되므로, 하나의 Cloud 프로젝트를 공유하는 앱들은 하나의 한도를 공유합니다.