이 페이지에서는 Play Integrity API를 사용하도록 앱, 게임 또는 SDK를 설정하는 방법을 설명합니다. API를 통합하려면 요청을 시작하는 데 필요한 Google Cloud 프로젝트가 있어야 합니다. 그런 다음 Google Play Console (앱의 경우) 또는 Google Play SDK Console (SDK의 경우)에서 Google Cloud 프로젝트를 연결할 수 있습니다. 추가 구성 옵션, 테스트 기능, API 보고에 액세스하고 일일 요청 할당량 증가를 요청하려면 프로젝트를 연결해야 합니다.
Play Integrity API 사용 설정
Play Integrity API를 호출하는 모든 앱 또는 SDK에는 API를 사용하고 사용량을 모니터링하는 Google Cloud 프로젝트가 있어야 합니다. 이는 모든 통합에 필수적인 첫 번째 단계입니다. Google Cloud 콘솔에서 Play Integrity API를 사용 설정하거나 Cloud 프로젝트를 Google Play에 연결하면 Play Integrity API가 자동으로 사용 설정됩니다.
Google Cloud 콘솔에서 새 Cloud 프로젝트를 만들거나 Play Integrity API와 함께 사용할 기존 Cloud 프로젝트를 선택합니다.
- API 및 서비스로 이동합니다.
- API 및 서비스 사용 설정을 선택합니다.
- Play Integrity API를 검색합니다.
- 사용 설정을 클릭합니다.
이제 Play Integrity API를 앱에 통합할 수 있습니다. 고급 기능과 할당량 증가를 이용하려면 연결 단계를 진행해야 합니다.
Google Play에 연결 (권장)
이 안내에 따라 앱 또는 SDK를 Google Play에 연결합니다.
Google Play의 앱 및 게임
Google Play에서 배포되는 앱은 Google Play Console에서 Google Cloud 프로젝트를 연결하여 추가 기능을 사용 설정하고 일일 API 할당량 증가를 요청해야 합니다.
- Google Play Console을 열고 앱을 선택합니다.
- 테스트 및 출시 > 앱 무결성으로 이동합니다.
- Play Integrity API에서 Cloud 프로젝트 연결을 클릭합니다.
- Play Integrity API와 함께 사용할 Google Cloud 프로젝트를 선택합니다. 프로젝트에 Play Integrity API가 아직 사용 설정되어 있지 않은 경우 연결 시 자동으로 사용 설정됩니다.
Play SDK Console의 SDK 제공업체
Google Play SDK Console을 사용하는 SDK 제공업체는 Google Cloud 프로젝트를 연결하여 API 사용량을 SDK에 귀속시키고, 추가 기능을 사용 설정하고, 일일 API 할당량 증가를 요청할 수 있습니다. Google Play SDK Console 액세스 권한에는 자격 요건이 적용됩니다.
- Google Play SDK Console을 열고 SDK를 선택합니다.
- SDK 무결성으로 이동합니다.
- Play Integrity API에서 Cloud 프로젝트 연결을 클릭합니다.
- Play Integrity API와 함께 사용할 Google Cloud 프로젝트를 선택합니다. 프로젝트에 Play Integrity API가 아직 사용 설정되어 있지 않은 경우 연결 시 자동으로 사용 설정됩니다.
Play Integrity API 사용량 한도 이해하기
앱 또는 SDK에는 연결된 Cloud 프로젝트 번호와 관련된 기본 일일 총 요청 수 한도 10,000개가 적용됩니다. 더 많은 볼륨이 예상되는 경우 할당량 상향 조정을 요청할 수 있습니다.
| 작업 | 일일 할당량 | 참고 |
|---|---|---|
| 토큰 요청 | 10,000명 | 기존 요청과 표준 토큰 준비 간에 공유됩니다. |
| Google 서버에서의 토큰 복호화 | 10,000명 | 기존 요청과 표준 요청 간에 공유됨 |
일일 최대 요청 수 늘리기
할당량 증가는 자격 기준에 따라 달라집니다. 할당량 증가는 클라이언트 측 토큰 생성과 서버 측 복호화 호출 모두에 적용됩니다. 요청을 처리하는 데 최대 1주일이 걸릴 수 있습니다. Google Cloud 콘솔에서 Play Integrity API 사용을 모니터링하고 서비스가 중단되지 않도록 할당량 알림을 설정하는 것이 좋습니다.
할당량이 증가하더라도 사용자 배터리와 데이터 사용량을 보존하기 위해 기존 요청을 자주 발생하지 않는 중요 작업으로 계속 제한해야 합니다.
Google Play의 앱 및 게임
할당량 증가를 신청하려면 Google Play 외에 다른 배포 채널에서도 앱을 사용할 수 있어야 합니다. Play Console에서 Google Cloud 프로젝트를 앱에 연결해야 합니다. 연결 해제된 프로젝트의 할당량 요청은 거부됩니다.
상향을 요청하려면 다음 단계를 따르세요.
- Play Console에서 관련 Google Cloud 프로젝트를 연결합니다.
- 적절한 재시도 전략을 포함하여 API 로직을 올바르게 구현했는지 확인합니다.
- 할당량 요청 양식을 제출합니다.
Play SDK Console의 SDK 제공업체
할당량 증가를 받으려면 SDK가 Google Play SDK Console에서 소유권 주장이 되어 있어야 하고 Cloud 프로젝트가 SDK에 연결되어 있어야 합니다. Google Play SDK Console 액세스 권한에는 자격 요건이 적용됩니다.
상향을 요청하려면 다음 단계를 따르세요.
- Google Play SDK Console에서 Google Cloud 프로젝트를 연결합니다.
- Google Play SDK Console 지원 양식을 작성합니다.
의견 입력란에 사용 사례, 요청하는 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.6.0'
Unity
다음 섹션에서는 지원되는 Unity 버전, 설치 방법, 환경 설정을 포함하여 Unity 프로젝트용 Google Play 무결성 API를 통합하고 설정하는 방법을 설명합니다.
지원되는 Unity 버전
- 2019.x, 2020.x 이상의 모든 버전이 지원됩니다.
- Unity 2018.x를 사용하면 2018.4 이상 버전이 지원됩니다.
- Unity 2017.x 이하 버전은 지원되지 않습니다.
개발 환경 설정
OpenUPM-CLI
OpenUPM CLI가 설치되어 있으면 다음 명령어를 실행하여 OpenUPM 레지스트리를 설치할 수 있습니다.
openupm add com.google.play.integrityOpenUPM
Unity 메뉴 옵션 Edit(수정) > Project Settings(프로젝트 설정) > Package Manager(패키지 관리자)를 선택하여 package manager settings(패키지 관리자 설정)를 엽니다.
OpenUPM을 Package Manager(패키지 관리자) 창에 범위가 지정된 레지스트리로 추가합니다.
Name: package.openupm.com URL: https://package.openupm.com Scopes: com.google.external-dependency-manager com.google.play.common com.google.play.core com.google.play.integrityUnity 메뉴 옵션 Window(창) > Package Manager(패키지 관리자)를 선택하여 package manager menu(패키지 관리자 메뉴)를 엽니다.
관리자 범위 드롭다운을 설정하여 My Registries(내 레지스트리)를 선택합니다.
패키지 목록에서 Google Play Integrity plugin for Unity(Unity용 Google Play 무결성 플러그인) 패키지를 선택하고 Install(설치)을 누릅니다.
GitHub에서 가져오기
GitHub에서 최신
.unitypackage버전을 다운로드합니다.Unity 메뉴 옵션 Assets > Import package > Custom Package를 선택하고 모든 항목을 가져와서
.unitypackage파일을 가져옵니다.
Unreal Engine
다음 섹션에서는 Unreal Engine 프로젝트에 Google Play Integrity API를 통합하고 설정하는 방법을 설명합니다.
지원되는 Unreal Engine 버전
이 플러그인은 Unreal Engine 5.0 및 이후의 모든 버전을 지원합니다.
개발 환경 설정
GitHub 저장소에서 Play Unreal Engine 플러그인을 다운로드합니다.
Unreal Engine 프로젝트의
Plugins폴더 내에 있는GooglePlay폴더를 복사합니다.Unreal Engine 프로젝트를 열고 편집 → 플러그인을 클릭합니다.
Google Play를 검색하고 사용 설정됨 체크박스를 선택합니다.
게임 프로젝트를 다시 시작하고 빌드를 트리거합니다.
프로젝트의
Build.cs파일을 열고PublicDependencyModuleNames에PlayIntegrity모듈을 추가합니다.using UnrealBuildTool; public class MyGame : ModuleRules { public MyGame(ReadOnlyTargetRules Target) : base(Target) { // ... PublicDependencyModuleNames.Add("PlayIntegrity"); // ... } }
네이티브
네이티브 설정 가이드를 따릅니다. 자세한 내용은 Play Integrity의 네이티브 API 참조 문서를 참고하세요.
API 응답 구성(선택사항)
API 응답에는 모든 요청에서 반환된 기본 확인 결과가 포함됩니다. Play Console 또는 Play SDK Console에서 Cloud 프로젝트를 연결한 경우 추가 정보를 포함하도록 API 응답을 맞춤설정할 수 있습니다.
기본 무결성 확인 결과
다음 무결성 확인 결과는 기본적으로 Play Integrity API 응답에서 반환됩니다.
| 응답 필드 | 값 | 설명 |
|---|---|---|
| 기기 무결성 | MEETS_DEVICE_INTEGRITY |
앱이 정품 인증된 Android 기기에서 실행됩니다. Android 13 이상에서는 기기 부트로더가 잠겨 있고 로드된 Android OS가 인증된 기기 제조업체 이미지임을 하드웨어 지원 증명으로 확인할 수 있습니다. |
| 비어 있음(빈 값) | 앱이 공격(예: API 후킹)이나 시스템 손상(예: 루팅됨) 징후가 있는 기기에서 실행되거나, 앱이 Google Play 무결성 검사를 통과하지 못한 에뮬레이터와 같은 실제 기기에서 실행되지 않습니다. | |
| Play 계정 세부정보 | LICENSED |
사용자에게 앱 사용 권한이 있습니다. 즉, 사용자가 Google Play에서 앱을 설치했거나 업데이트했습니다. |
UNLICENSED |
사용자에게 앱 사용 권한이 없습니다. 예를 들어 사용자가 앱을 사이드로드한 경우 또는 Google Play에서 앱을 획득하지 않은 경우에 이러한 상황이 발생합니다. | |
UNEVALUATED |
요구사항을 충족하지 못하여 라이선스 세부정보가 평가되지 않았습니다. 이는 다음을 비롯하여 여러 가지 이유로 발생할 수 있습니다.
|
|
| 애플리케이션 무결성 | PLAY_RECOGNIZED |
앱과 인증서가 Google Play에서 배포된 버전과 일치합니다. |
UNRECOGNIZED_VERSION |
인증서나 패키지 이름이 Google Play 레코드와 일치하지 않습니다. | |
UNEVALUATED |
애플리케이션 무결성이 평가되지 않았습니다. 기기를 충분히 신뢰할 수 없는 등 필요한 요구사항을 충족하지 못했습니다. |
PC용 Google Play 게임즈
PC용 Google Play 게임즈에 배포하면 기기 무결성 확인 결과에서 추가 라벨을 수신하도록 자동으로 선택됩니다.
| 응답 필드 | 라벨 | 설명 |
|---|---|---|
| 기기 무결성 | MEETS_VIRTUAL_INTEGRITY |
앱이 Google Play 서비스에서 제공하는 Android Emulator에서 실행됩니다. 에뮬레이터는 시스템 무결성 검사를 통과하고 핵심 Android 호환성 요구사항을 충족합니다. |
선택적 무결성 확인 결과
Play Console 또는 Play SDK Console에서 Cloud 프로젝트를 연결한 경우 추가 정보를 수신하도록 선택할 수 있습니다.
변경하려면 Play Console을 방문하여 테스트 및 출시 > 앱 무결성으로 이동합니다. Play Integrity API 옆에 있는 설정을 클릭합니다. 응답 변경을 클릭하고 변경사항을 수정하고 저장합니다.
기기 정보
deviceIntegrity 확인 결과의 추가 기기 라벨은 앱이 실행되는 기기 환경에 관해 자세히 알려줍니다.
단일 기기는 각 기준을 충족하는 경우 여러 라벨을 반환합니다.
이러한 라벨을 사용하여 단계별 시정 조치 전략을 만들 수 있습니다. 예를 들어 3개의 라벨(MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY)을 반환하는 기기를 하나의 라벨(MEETS_BASIC_INTEGRITY)만 반환하는 기기보다 더 신뢰할 수 있습니다.
기기 속성은 기기에 있는 Android OS의 Android SDK 버전을 알려줍니다. 향후 다른 기기 속성으로 확장될 수 있습니다.
최근 기기 활동은 LEVEL_1 (요청 수가 적음)에서 LEVEL_4 (요청 수가 많음)까지의 수준을 반환합니다. 활동 수준이 높으면 신뢰할 수 없는 기기에 악용 목적으로 배포하기 위해 과도한 토큰을 생성하는 데 기기가 사용되고 있음을 나타낼 수 있습니다.
기기 회상을 사용하면 특정 기기에 맞춤 기기별 데이터를 저장할 수 있으며, 나중에 동일한 기기에 앱을 다시 설치할 때 안정적으로 검색할 수 있습니다.
선택적 정보를 선택하면 API 응답에 확인 결과의 새로운 필드와 응답이 포함됩니다.
| 응답 필드 | 라벨 | 설명 | |
|---|---|---|---|
| 기기 무결성 | MEETS_BASIC_INTEGRITY |
앱이 기본 시스템 무결성 검사를 통과한 기기에서 실행됩니다. 기기 부트로더는 잠기거나 잠금 해제될 수 있으며 부팅 상태는 인증되거나 인증되지 않을 수 있습니다. 기기가 인증되지 않았을 수 있으며,
이 경우 Google에서 보안, 개인 정보 보호 또는 앱 호환성을 보장할 수 없습니다. Android 13 이상에서 MEETS_BASIC_INTEGRITY 판결을 받으려면 증명
신뢰할 수 있는 루트가 Google에서 제공되어야 합니다. |
|
MEETS_STRONG_INTEGRITY |
앱이 최신 보안 업데이트가 적용된 정품 인증된 Android 기기에서 실행됩니다.
|
||
| 기기 속성 | sdkVersion: 19, 20, ..., 36 |
기기에서 실행되는 Android OS의 SDK 버전입니다.
반환된 숫자는 Build.VERSION_CODES에 매핑됩니다. |
|
| 비어 있음(빈 값) | 필요한 요구사항을 충족하지 못하여 SDK 버전이 평가되지 않습니다. 이 경우 sdkVersion 필드가 설정되지 않으므로 deviceAttributes 필드가 비어 있습니다.
다음과 같은 이유로 인해 발생할 수 있습니다.
|
||
| 지난 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 |
최근 기기 활동이 평가되지 않았습니다. 다음과 같은 이유로 인해 이 문제가 발생할 수 있습니다.
|
||
| 기기 리콜 | values: bitFirst, bitSecond, bitThird |
이는 특정 기기에 대해 이전에 설정한 비트 값입니다. 각 비트의 의미는 사용자가 결정합니다. 세 비트 값은 기본적으로 false입니다. | |
writeDates: yyyymmFirst, yyyymmSecond, yyyymmThird |
연도와 월까지 정확한 비트 값 쓰기 날짜(UTC)입니다. 회상 비트의 쓰기 날짜는 비트가 true로 설정될 때마다 업데이트되고 비트가 false로 설정되면 삭제됩니다. | ||
환경 세부정보
앱 액세스 위험은 화면을 캡처하거나, 오버레이를 표시하거나, 기기를 제어하는 데 사용될 수 있는 다른 앱이 실행 중인지 알려줍니다. Google Play에 알려진 확인된 접근성 서비스는 이 확인 결과에서 자동으로 제외됩니다.
Play 프로텍트 확인 결과는 기기에서 Google 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는 응답 암호화를 관리합니다. 즉, 백엔드에서 Google 서버를 호출하여 평결을 복호화합니다. 또는 키를 직접 관리하여 보안 서버 환경 내에서 로컬로 복호화할 수 있습니다.
Google에서 응답 암호화를 관리하도록 허용 (권장)
앱의 보안을 위해 Google에서 키를 생성하고 관리하도록 허용하는 것이 좋습니다. 백엔드에서 Google Play의 서버를 호출하여 응답을 복호화하고 확인합니다.
자체 암호화 키 관리
자체 보안 서버 환경 내에서 로컬로 복호화하려면 Play Console 또는 Play SDK Console에서 암호화 키를 다운로드하면 됩니다. 이 기능을 사용하려면 앱이 Google Play에서 제공되어야 합니다.
Play Console에서 응답 암호화 관리 전략을 변경하기 전에 중단을 방지하기 위해 Google Play 서버에서 무결성 토큰을 복호화하고 확인하도록 서버가 올바르게 구성되어 있는지 확인합니다.
Google 관리 암호화 키와 자체 관리 암호화 키 간 전환
- Play Console을 열고 앱을 선택합니다 .
- 테스트 및 출시 > 앱 무결성으로 이동합니다.
- Play Integrity API 옆에 있는 설정을 클릭합니다.
- 기존 요청에서 응답 암호화 옆에 있는 수정을 클릭합니다.
자체 관리 키로 전환하려면 다음 단계를 따르세요.
- 내 응답 암호화 키 관리 및 다운로드를 선택하고 공개 키를 업로드합니다.
- 저장을 클릭하여 암호화된 키를 자동으로 다운로드합니다.
- 이 키를 사용하여 로컬로 복호화하도록 보안 백엔드 서버를 업데이트합니다.
Google 관리 키로 전환하려면 다음 단계를 따르세요.
- Google에서 응답 암호화를 관리하도록 허용 (권장)을 선택합니다.
- 변경사항 저장을 클릭합니다.