이 페이지에서는 Play Integrity API를 사용하도록 앱이나 게임을 설정하는 방법을 설명합니다. API의 응답을 사용 설정한 다음 API를 앱과 앱의 백엔드 서버에 통합해야 합니다. Google Play Console에서 Play Integrity API에 사용 중인 Google Cloud 프로젝트를 연결하면 추가 구성 옵션, 테스트 기능, 보고가 제공됩니다.
Play Integrity API 응답 사용 설정
Play Integrity API를 호출하는 모든 앱 또는 SDK는 Google Cloud 프로젝트를 사용하여 API 사용을 모니터링해야 합니다. Google Play의 앱은 Google Play Console에서 Cloud 프로젝트를 연결하여 Play Integrity API 응답을 사용 설정할 수 있습니다. 새 Cloud 프로젝트를 만들거나 앱이 Google Play 외부에 독점적으로 배포되는 경우 Google Cloud 콘솔에서 Play Integrity API 응답을 사용 설정할 수 있습니다.
Google Play Console에서 설정(권장)
Google Play Console에서 Play Integrity API 응답을 사용 설정하면 추가 구성 옵션, 테스트 기능, API 보고에 액세스할 수 있습니다. 이 옵션은 Google Play에서 배포된 앱에만 제공됩니다. 출시 > 앱 무결성으로 이동합니다. Play Integrity API 아래에서 Cloud 프로젝트 연결을 선택합니다. 앱에 연결할 Cloud 프로젝트를 선택하면 Play Integrity API 응답이 사용 설정됩니다. 이제 Play Integrity API를 앱에 통합할 수 있습니다.
Google Cloud 콘솔에서 설정
Google Cloud 콘솔에서 새 Cloud 프로젝트를 만들거나 Play Integrity API와 함께 사용할 기존 Cloud 프로젝트를 선택합니다. API 및 서비스로 이동합니다. API 및 서비스 사용 설정을 선택합니다. Play Integrity API를 검색한 후 사용 설정합니다. 이제 Play Integrity API를 앱에 통합할 수 있습니다.
SDK 제공업체용 안내 설정
SDK 제공업체는 자체 Google Cloud 프로젝트를 사용하여 Play Integrity API를 호출해야 하므로 API 사용량은 SDK를 사용하는 개별 앱이 아닌 SDK에 기인합니다. 즉, SDK를 사용하는 앱이 Play Integrity API를 개별적으로 설정할 필요가 없습니다. Play Integrity API에 대한 요청은 앱이 아닌 SDK의 API 사용량에 자동으로 포함됩니다.
SDK 개발자는 두 가지 방법으로 Play Integrity API를 설정할 수 있습니다. 하나는 Google Play SDK Console을 사용하는 것이고 다른 하나는 Google Cloud 콘솔을 사용하는 것입니다.
Google Play SDK Console 사용(권장)
Google Play SDK Console에서 Play Integrity API 응답을 사용 설정하면 추가 구성 옵션에 액세스할 수 있습니다. SDK 무결성으로 이동하여 설정을 클릭합니다. 프로젝트 구성에서 Cloud 프로젝트 연결을 선택합니다. SDK에 연결할 Cloud 프로젝트를 선택하면 Play Integrity API 응답이 사용 설정됩니다. 이제 Play Integrity API를 SDK에 통합할 수 있습니다. Google Play SDK Console 액세스 권한은 자격 기준에 따라 달라집니다.
Google Cloud 콘솔 사용
Google Cloud 콘솔에서 Play Integrity API 응답을 사용 설정할 수 있습니다. Google Cloud 콘솔에서 새 Cloud 프로젝트를 만들거나 Play Integrity API와 함께 사용할 기존 Cloud 프로젝트를 선택합니다. API 및 서비스로 이동합니다. API 및 서비스 사용 설정을 선택합니다. Play Integrity API를 검색한 후 사용 설정합니다. 이제 Play Integrity API를 SDK에 통합할 수 있습니다.
SDK의 일일 Play Integrity API 요청 늘리기
일일 최대 요청을 늘리려는 SDK 제공업체는 할당량 요청 양식을 작성해야 합니다. 공개 의견 섹션에서 SDK 요청을 하고 있음을 명시하고 Maven 좌표(groupId:artifactId) 또는 SDK의 URL을 포함합니다.
일일 Play Integrity API 요청 늘리기
앱의 일일 최대 요청 수는 총 10,000개입니다. 앱이 증가된 사용자 수를 처리해야 하는 경우 아래 안내에 따라 이 일일 최대한도의 상향을 요청할 수 있습니다.
일일 최대 요청 수 늘리기
일일 최대 요청 수를 늘릴 수 있으려면 Google Play 외에 다른 배포 채널에서도 앱을 사용할 수 있어야 합니다. 일일 최대 요청 수가 증가하더라도 사용자당 기존 요청을 자주 발생하지 않는 중요 작업으로 계속 제한하여 사용자 데이터와 배터리를 보존해야 합니다.
일일 최대 요청 수 증가를 요청하려면 다음을 실행하세요.
- Play Console에서 Play Integrity API에 사용 중인 Google Cloud 프로젝트를 연결합니다.
- 권장되는 재시도 전략을 포함하여 API 로직을 올바르게 구현하고 있는지 확인합니다.
- 이 양식을 사용하여 할당량 상향 조정을 요청합니다.
Play Integrity API 할당량을 늘리는 데는 최대 일주일이 걸릴 수 있으므로 서비스가 중단되지 않도록 할당량 알림을 설정할 수도 있는 Google Play Console 또는 Google Cloud 콘솔에서 Play Integrity API 사용을 모니터링하는 것이 좋습니다.
기존 요청 할당량 증가는 무결성 토큰을 생성하는 클라이언트 호출과 무결성 토큰을 복호화하고 확인하는 서버 호출에 모두 자동으로 적용됩니다. 표준 요청 할당량 증가는 무결성 토큰을 복호화하고 확인하는 서버 호출에 적용됩니다.
앱에 Play Integrity API 통합
Play Integrity API를 앱이나 SDK에 통합하려면 개발 환경에 따라 다음 중 하나를 실행하세요.
Kotlin 또는 Java
Play Integrity API의 최신 Android 라이브러리는 Google Maven 저장소에서 확인할 수 있습니다.
앱의 build.gradle 파일에 다음 종속 항목을 추가합니다.
implementation 'com.google.android.play:integrity:1.4.0'
Unity
Unity용 Google Play Integrity 플러그인 1.3.0 이상을 설치합니다. 자세한 내용은 Unity용 Google 패키지 설치 방법을 참고하세요.
- 2019.x, 2020.x 이상의 모든 버전이 지원됩니다.
- Unity 2018.x를 사용하면 2018.4 이상 버전이 지원됩니다.
- Unity 2017.x 이하 버전은 지원되지 않습니다.
네이티브
Play Core Native SDK 1.13.0 이상을 설치합니다. 자세한 내용은 Play Core Native의 개발 환경 설정 가이드를 참고하세요.
API 응답 구성(선택사항)
API 응답에는 모든 요청에서 반환된 기본 확인 결과가 포함됩니다. Play Console에서 Play Integrity API 통합을 설정하면 API 응답을 맞춤설정할 수 있습니다.
기본 응답
다음 무결성 확인 결과는 기본적으로 Play Integrity API 응답에서 반환됩니다.
| 응답 필드 | 값 | 설명 |
|---|---|---|
| 기기 무결성 | MEETS_DEVICE_INTEGRITY |
앱이 Google Play 서비스에서 제공하는 Android 기기에서 실행됩니다. 기기는 시스템 무결성 검사를 통과하고 Android 호환성 요구사항을 충족합니다. |
| 비어 있음(빈 값) | 앱이 공격(예: API 후킹)이나 시스템 손상(예: 루팅됨) 징후가 있는 기기에서 실행되거나, 앱이 Google Play 무결성 검사를 통과하지 못한 에뮬레이터와 같은 실제 기기에서 실행되지 않습니다. | |
| Play 계정 세부정보 | LICENSED |
사용자에게 앱 사용 권한이 있습니다. 즉, 사용자가 기기에서 Google Play를 통해 앱을 설치했거나 업데이트했습니다. |
UNLICENSED |
사용자에게 앱 사용 권한이 없습니다. 예를 들어 사용자가 앱을 사이드로드한 경우 또는 Google Play에서 앱을 획득하지 않은 경우에 이러한 상황이 발생합니다. | |
UNEVALUATED |
요구사항을 충족하지 못하여 라이선스 세부정보가 평가되지 않았습니다. 이는 다음을 비롯하여 여러 가지 이유로 발생할 수 있습니다.
|
|
| 애플리케이션 무결성 | PLAY_RECOGNIZED |
앱과 인증서가 Google Play에서 배포된 버전과 일치합니다. |
UNRECOGNIZED_VERSION |
인증서나 패키지 이름이 Google Play 레코드와 일치하지 않습니다. | |
UNEVALUATED |
애플리케이션 무결성이 평가되지 않았습니다. 기기를 충분히 신뢰할 수 없는 등 필요한 요구사항을 충족하지 못했습니다. |
조건부 응답
PC용 Google Play 게임즈에 배포하면 기기 무결성 확인 결과에서 추가 라벨을 수신하도록 자동으로 선택됩니다.
| 응답 필드 | 라벨 | 설명 |
|---|---|---|
| 기기 무결성 | MEETS_VIRTUAL_INTEGRITY |
앱이 Google Play 서비스에서 제공하는 Android Emulator에서 실행됩니다. 에뮬레이터는 시스템 무결성 검사를 통과하고 핵심 Android 호환성 요구사항을 충족합니다. |
응답(선택사항)
Play Console 또는 Play SDK Console에서 Play Integrity API 통합을 설정하는 경우 API 응답으로 정보를 수신하도록 선택할 수 있습니다.
API 응답을 변경하려면 Play Console을 방문하여 출시 > 앱 무결성으로 이동합니다. 응답에서 변경사항을 수정하고 저장합니다.
기기 정보(선택사항)
앱과 SDK는 기기 무결성 확인 결과에서 추가 기기 라벨을 선택할 수 있습니다. 추가 라벨 수신을 선택하면 무결성 응답에는 각 라벨 기준이 충족되는 경우 같은 기기의 라벨이 여러 개 포함됩니다. 가능한 응답 범위에 따라 다르게 동작하도록 백엔드 서버를 준비할 수 있습니다. 예를 들어 3개의 라벨(MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY)을 반환하는 기기는 하나의 라벨만(MEETS_BASIC_INTEGRITY) 반환하는 기기보다 더 신뢰할 수 있습니다.
최근 기기 활동을 선택할 수도 있습니다. 최근 기기 활동은 LEVEL_1 (요청 수가 적음)에서 LEVEL_4(요청 수가 많음)까지의 수준을 반환합니다. 예를 들어 앱의 일반적인 것보다 훨씬 높은 활동 수준을 반환하는 기기는 신뢰할 수 없는 기기에 배포하기 위한 무결성 토큰을 많이 생성하려고 할 수 있습니다.
기기에서 실행 중인 Android OS의 Android SDK 버전을 알려주는 기기 속성을 선택할 수도 있습니다. 향후 다른 기기 속성으로 확장될 수 있습니다.
| 응답 필드 | 라벨 | 설명 | |
|---|---|---|---|
| 기기 무결성 | MEETS_BASIC_INTEGRITY |
앱이 기본 시스템 무결성 검사를 통과한 기기에서 실행됩니다. 기기는 Android 호환성 요구사항을 충족하지 못할 수 있고 Google Play 서비스 실행이 승인되지 않을 수도 있습니다. 예를 들어 기기가 인식할 수 없는 Android 버전을 실행하거나 잠금 해제된 부트로더를 보유하거나 제조업체의 인증을 받지 않았을 수 있습니다. | |
MEETS_STRONG_INTEGRITY |
앱이 Google Play 서비스에서 제공하는 Android 기기에서 실행되며 하드웨어 지원 부팅 무결성 증명과 같은 시스템 무결성을 강력히 보장합니다. 기기는 시스템 무결성 검사를 통과하고 Android 호환성 요구사항을 충족합니다. | ||
| 지난 1시간 동안 이 기기에서 앱별로 표준 API 무결성 토큰 요청 | 지난 1시간 동안 이 기기에서 앱당 기존 API 무결성 토큰 요청 | ||
| 최근 기기 활동 | LEVEL_1 (최저) |
10개 이하 | 5개 이하 |
LEVEL_2 |
11~25개 | 6~10개 | |
LEVEL_3 |
26~50세 | 11~15 | |
LEVEL_4 (최고) |
50개 초과 | 15개 초과 | |
UNEVALUATED |
최근 기기 활동이 평가되지 않았습니다. 다음과 같은 이유로 이 문제가 발생할 수 있습니다.
|
||
| 기기 속성 | sdkVersion: 19, 20, ..., 35 |
기기에서 실행되는 Android OS의 SDK 버전입니다.
반환된 숫자는 Build.VERSION_CODES에 매핑됩니다. |
|
| 비어 있음(빈 값) | 필요한 요구사항을 충족하지 못하여 SDK 버전이 평가되지 않습니다. 이 경우 sdkVersion 필드가 설정되지 않으므로 deviceAttributes 필드가 비어 있습니다.
다음과 같은 이유로 이 문제가 발생할 수 있습니다.
|
||
환경 세부정보(선택사항)
앱은 환경에 관한 추가 확인 결과를 수신하도록 선택할 수 있습니다. 앱 액세스 위험을 사용하면 화면을 캡처하거나 오버레이를 표시하거나 기기를 제어할 수 있는 다른 앱이 실행 중인지 알 수 있습니다. Play 프로텍트 확인 결과를 통해 기기에서 Play 프로텍트가 사용 설정되어 있는지, 알려진 멀웨어가 발견되었는지 알 수 있습니다.
이러한 확인 결과를 수신하도록 선택하면 API 응답에 확인 결과와 함께 환경 세부정보 필드가 포함됩니다.
| 응답 필드 | 값 | 설명 |
|---|---|---|
| 앱 액세스 위험 확인 결과 | KNOWN_INSTALLED |
앱이 Google Play에서 설치되거나 기기 제조업체가 시스템 파티션에 미리 로드합니다. |
KNOWN_CAPTURING |
요청하는 앱의 입력과 출력을 읽거나 캡처하는 데 사용할 수 있는 앱(예: 화면 녹화 앱)이 Google Play에서 설치되었거나 기기에 미리 로드되어 실행 중입니다. | |
KNOWN_CONTROLLING |
기기 및 요청하는 앱의 입력과 출력을 제어하는 데 사용할 수 있는 Google Play에서 설치했거나 기기에 미리 로드된 앱이 실행되고 있습니다(예: 원격 제어 앱). | |
KNOWN_OVERLAYS |
요청하는 앱에 오버레이를 표시할 수 있는 Google Play에서 설치했거나 기기에 미리 로드된 앱이 실행 중입니다. | |
UNKNOWN_INSTALLED |
Google Play에서 설치하지 않았거나 기기 제조업체에서 시스템 파티션에 미리 로드하지 않은 다른 앱이 설치되어 있습니다. | |
UNKNOWN_CAPTURING |
요청하는 앱의 입력과 출력을 읽거나 캡처하는 데 사용할 수 있는 다른 앱(Play에서 설치하지 않았거나 기기에 미리 로드하지 않음)이 실행되고 있습니다(예: 화면 녹화 앱). | |
UNKNOWN_CONTROLLING |
기기 및 요청하는 앱의 입력과 출력을 제어하는 데 사용할 수 있는 다른 앱(Play에서 설치하지 않았거나 기기에 미리 로드하지 않음)이 실행되고 있습니다(예: 원격 제어 앱). | |
UNKNOWN_OVERLAYS |
요청하는 앱에 오버레이를 표시할 수 있는 다른 앱 (Play에서 설치하지 않았거나 기기에 미리 로드되지 않음)이 실행 중입니다. | |
| 비어 있음(빈 값) | 필요한 요구사항을 충족하지 못하면 앱 액세스 위험이 평가되지 않습니다. 이 경우 appAccessRiskVerdict 필드가 비어 있습니다. 이는 다음을 비롯하여 여러 가지 이유로 발생할 수 있습니다.
|
|
| Play 프로텍트 확인 결과 | NO_ISSUES |
Play 프로텍트가 사용 설정되어 있으며 기기에서 앱 문제를 발견하지 못했습니다. |
NO_DATA |
Play 프로텍트가 사용 설정되어 있지만 아직 검사가 이루어지지 않았습니다. 기기 또는 Play 스토어 앱이 최근에 재설정되었을 수 있습니다. | |
POSSIBLE_RISK |
Play 프로텍트가 사용 중지되어 있습니다. | |
MEDIUM_RISK |
Play 프로텍트가 사용 설정되어 있으며 기기에 설치된 잠재적으로 위험한 앱을 발견했습니다. | |
HIGH_RISK |
Play 프로텍트가 사용 설정되어 있으며 기기에 설치된 위험한 앱을 발견했습니다. | |
UNEVALUATED |
Play 프로텍트 확인 결과가 평가되지 않았습니다. 기기를 충분히 신뢰할 수 없는 등 필요한 요구사항을 충족하지 못했습니다. |
기존 요청 설정 구성(선택사항)
표준 API 요청만 하려는 경우 이 섹션을 건너뛰세요.
기존 요청을 하면 기본적으로 Google Play 서버는 개발자가 Play Integrity API와 상호작용할 때 앱에서 사용하는 응답 암호화를 관리합니다. 이 기본 옵션을 사용하는 것이 좋지만 아래 안내에 따라 응답 암호화 키를 관리하고 다운로드할 수도 있습니다.
Google에서 응답 암호화를 관리하도록 허용(기본값이며 권장됨)
앱의 보안을 위해 Google에서 응답 암호화 키를 생성하고 관리하도록 허용하는 것이 좋습니다. 백엔드 서버에서는 Google Play의 서버를 호출하여 응답을 복호화합니다.
내 응답 암호화 키 관리 및 다운로드
자체 보안 서버 환경 내에서 로컬로 무결성 확인 결과를 복호화하려면 응답 암호화 키를 관리하고 다운로드하면 됩니다. 응답 암호화 키를 관리하고 다운로드하려면 Play Console을 사용해야 하며 Google Play 외에 다른 배포 채널에서도 앱을 사용할 수 있어야 합니다. 아래 안내에 따라 Google 관리 응답 암호화 키에서 직접 관리 응답 암호화 키로 전환합니다.
클라이언트 앱 내에서 수신한 토큰을 복호화하거나 확인하면 안 되며 복호화 키를 클라이언트 앱에 노출하면 안 됩니다.
Play Console에서 응답 암호화 관리 전략을 변경하기 전에 중단을 방지하기 위해 Google Play 서버에서 무결성 토큰을 복호화하고 확인하도록 서버가 올바르게 구성되어 있는지 확인합니다.
Google 관리 응답 암호화 키와 직접 관리 응답 암호화 키 간 전환
현재 Google에서 응답 암호화를 관리하고 있으나 개발자가 응답 암호화 키를 직접 관리하고 다운로드하도록 전환하려면 다음 단계를 따르세요.
- Play Console에 로그인합니다.
- Play Integrity API를 사용하는 앱을 선택합니다.
- 왼쪽 메뉴의 출시 섹션에서 앱 무결성으로 이동합니다.
- Play Integrity API 옆에 있는 설정을 클릭합니다.
- 페이지의 기존 요청 섹션에서 응답 암호화 옆에 있는 수정을 클릭합니다.
- 창이 표시되면 내 응답 암호화 키 관리 및 다운로드를 클릭합니다.
- 안내에 따라 공개 키를 업로드합니다.
- 창에 업로드가 완료되었다고 표시되면 저장을 클릭합니다. 암호화된 키가 자동으로 다운로드됩니다.
- 응답 암호화 키를 사용하여 자체 보안 서버 환경에서 로컬로 무결성 토큰을 복호화하고 확인하도록 서버 로직을 변경합니다.
- (선택사항) 응답 암호화 키를 직접 관리하는 경우에도 앱은 여전히 Google Play 서버를 통해 응답을 복호화하고 확인할 수 있습니다.
개발자가 응답 암호화 키를 직접 관리하고 있으나 Google에서 응답 암호화를 관리하도록 전환하려면 다음 단계를 따르세요.
- Google 서버에서만 복호화하고 확인하도록 서버 로직을 변경합니다.
- Play Console에 로그인합니다.
- Play Integrity API를 사용하는 앱을 선택합니다.
- 왼쪽 메뉴의 출시 섹션에서 앱 무결성으로 이동합니다.
- Play Integrity API 옆에 있는 설정을 클릭합니다.
- 페이지의 기존 요청 섹션에서 응답 암호화 옆에 있는 수정을 클릭합니다.
- 창이 표시되면 Google에서 응답 암호화를 관리하도록 허용(권장)을 클릭합니다.
- 변경사항 저장을 클릭합니다.