Play Integrity API를 사용하여 위험한 상호작용 감지 및 악용 방지

Play Integrity API를 사용하여 위험한 상호작용으로부터 앱과 게임을 보호할 수 있습니다. 이러한 상호작용을 식별함으로써 앱이 적절히 대응하여 공격 및 악용의 위험을 줄일 수 있습니다.

작동 원리

Integrity API는 Android 앱 및 게임 개발자가 잠재적으로 위험한 허위 트래픽을 감지할 수 있도록 무결성 신호 모음과 Google Play 악용 방지 기능을 통합합니다. 이 트래픽은 수정된 버전의 앱 또는 게임, 신뢰할 수 없는 기기, 기타 신뢰할 수 없는 환경에서 발생할 수 있습니다. 이 트래픽을 감지하면 적절한 조치로 대응하여 공격뿐 아니라 사기, 속임수, 무단 액세스와 같은 악용을 줄일 수 있습니다.

사용자가 앱이나 게임에서 정의된 작업을 수행하면 서버에서 클라이언트 측 코드에 Integrity API를 호출하도록 지시합니다. Google Play 서버는 이 기기 및 바이너리를 신뢰할 수 있는지에 관한 무결성 확인 결과가 포함된 암호화된 응답을 반환합니다. 그런 다음 앱에서 확인을 위해 이 응답을 서버로 전달합니다. 서버는 앱이나 게임이 다음으로 수행해야 하는 작업을 결정할 수 있습니다.

API는 다음 정보가 포함된 무결성 확인 결과를 응답으로 제공합니다.

애플리케이션 무결성: Google Play에서 인식한 수정되지 않은 바이너리와 상호작용하는지 알려줍니다.
계정 세부정보: 현재 사용자 계정에 라이선스가 부여되어 있는지, 즉 사용자가 Google Play에서 앱과 게임을 설치했거나 비용을 지불했는지를 나타냅니다.
기기 무결성: 앱이 Google Play 서비스를 사용하는 정품 Android 기기에서 실행되고 있는지 알려줍니다.

도움말:

Google Play 상태 대시보드를 사용하여 Play Integrity API 및 기타 Play 서비스의 상태를 모니터링할 수 있습니다.
Android 개발자 사이트에 제공되는 문서의 각 권장사항을 따르면 Integrity API를 앱에 가장 잘 활용할 수 있습니다.

Play Integrity API 설정 및 관리하기

앱에 Integrity API 사용 설정

중요: Integrity API에 액세스하거나 이를 사용하면 Play Integrity API 서비스 약관에 동의하는 것으로 간주됩니다.

앱에 Integrity API 응답을 사용 설정하려면 Play Console에서 Google Cloud 프로젝트를 연결해야 합니다. 프로젝트를 연결하려면 다음 안내를 따르세요.

Play Console을 열고 앱 무결성 페이지(출시 > 설정 > 앱 무결성)로 이동합니다.
Integrity API 탭을 클릭합니다.
'기존 프로젝트 연결'과 연결하려는 프로젝트를 선택하거나 '새 프로젝트 만들기'를 선택합니다.
프로젝트 연결을 클릭합니다.

Integrity API를 앱에 통합하려면 다음 작업을 해야 합니다.

자바/Kotlin 앱의 경우 Google Maven 저장소에서 Play Integrity API에 사용할 수 있는 최신 Android 라이브러리를 설치합니다.
Unity 게임의 경우 최신 버전의 Unity용 Google Play 플러그인을 설치합니다. 2019.x, 2020.x 이상의 모든 버전이 지원됩니다. Unity 2018.x를 사용하는 경우 2018.4 이상을 설치합니다. Unity 2017.x를 사용하는 경우 2017.4.40 이상을 설치합니다. Unity 5.x 및 이전 버전은 지원되지 않습니다.
네이티브 앱 및 게임의 경우 최신 Play Core Native SDK를 설치합니다.

이제 Android 개발자 사이트에서 다음 단계에 따라 앱 또는 게임에 Play Integrity API를 사용할 수 있습니다.

(선택사항) 응답 암호화 관리 방법 선택하기

응답 암호화는 기본적으로 Google에서 관리합니다. 그러나 원하는 경우 응답 암호화를 직접 관리할 수 있습니다.

중요: 응답 암호화 관리를 Google 관리형과 직접 관리형 간에 전환하려면 백엔드 서버에서 코드를 변경해야 합니다.

응답 암호화를 직접 관리하려면 다음 안내를 따르세요.

Play Console을 열고 앱 무결성 페이지(출시 > 설정 > 앱 무결성)로 이동합니다.
Integrity API 탭을 클릭합니다.
'설정' 섹션으로 스크롤합니다.
'응답 암호화' 옆에 상태가 기본적으로 'Google에서 관리하는 키'로 표시됩니다. 변경을 클릭합니다.
'내 응답 암호화 키 관리 및 다운로드'를 선택하고 변경사항 저장을 클릭합니다. Google에서 개발자를 대신해 응답 암호화를 생성하여 다운로드하고 관리합니다. 이 키를 사용해 응답을 복호화하려면 백엔드 서버 로직을 업데이트해야 합니다.
화면에 표시된 안내에 따라 .pem 파일을 생성하고 업로드하여 API 키를 다운로드합니다.
응답 암호화 관리 설정이 업데이트되었음을 확인하는 메시지가 화면에 표시됩니다.
새 응답 암호화 키를 다운로드하고 프로덕션에서 새 응답 암호화 키로 응답을 복호화하는 데 사용할 백엔드 서버를 업데이트합니다. 앱 무결성 페이지의 Integrity API 탭으로 돌아가 Google Play에서 기존 키가 아닌 새 응답 암호화 키를 사용하도록 합니다. 이 변경사항은 즉시 적용됩니다.

자체 관리형에서 Google 관리형으로 되돌리려면 다음 안내를 따르세요.

Play Console을 열고 앱 무결성 페이지(출시 > 설정 > 앱 무결성)로 이동합니다.
Integrity API 탭을 클릭합니다.
'설정' 섹션으로 스크롤합니다.
이전에 변경한 적이 있으므로 '응답 암호화' 옆에 상태가 '자체 관리형'으로 표시됩니다. 변경을 클릭합니다.
'Google에서 응답 암호화를 관리하도록 허용(권장)'을 선택하고 변경사항 저장을 클릭합니다. Google에서 응답 암호화 키를 생성하고 관리합니다. 백엔드 서버에서는 Google Play의 서버를 호출하여 응답을 복호화합니다.

(선택사항) Integrity API 응답 구성하기

기본적으로 다음과 같은 API 응답이 구성됩니다.

API 응답	라벨	설명
기기 무결성	`MEETS_DEVICE_INTEGRITY`	앱이 Google Play 서비스에서 제공하는 Android 기기에서 실행됩니다. 기기는 시스템 무결성 검사를 통과했고 Android 호환성 요구사항을 충족합니다.
기기 무결성	라벨 없음(빈 값)	앱이 공격(예: API 후킹)이나 시스템 손상(예: 루팅됨) 징후가 있는 기기에서 실행되거나, 앱이 Google Play 무결성 검사를 통과하지 못한 에뮬레이터와 같은 실제 기기에서 실행되지 않습니다.
계정 세부정보	`LICENSED`	사용자에게 앱 권한이 있습니다. 즉, 사용자가 Google Play에서 앱을 설치했거나 구매했습니다.
	`UNLICENSED`	사용자에게 앱 권한이 없습니다. 예를 들어 사용자가 앱을 사이드로드한 경우 또는 Google Play에서 앱을 획득하지 않은 경우에 이러한 상황이 발생합니다.
	`UNEVALUATED`	필요한 요구사항을 충족하지 못하여 라이선스 세부정보가 평가되지 않았습니다. 이는 다음을 비롯하여 여러 가지 이유로 발생할 수 있습니다. 기기를 충분히 신뢰할 수 없습니다. 기기에 설치된 앱 버전을 Google Play에서 알 수 없습니다.
애플리케이션 무결성	`PLAY_RECOGNIZED`	앱과 인증서가 Google Play에서 배포된 버전과 일치합니다.
	`UNRECOGNIZED_VERSION`	인증서나 패키지 이름이 Google Play 레코드와 일치하지 않습니다.
	`UNEVALUATED`	애플리케이션 무결성이 평가되지 않았습니다. 기기를 충분히 신뢰할 수 없는 등 필요한 요구사항을 충족하지 못했습니다.

또한 다음과 같은 API 응답을 수신하도록 선택할 수 있습니다.

API 응답	라벨	설명
기기 무결성	`MEETS_BASIC_INTEGRITY`	앱이 기본 시스템 무결성 검사를 통과한 기기에서 실행됩니다. 기기는 Android 호환성 요구사항을 충족하지 못할 수 있고 Google Play 서비스 실행이 승인되지 않을 수도 있습니다. 예를 들어 기기가 인식할 수 없는 Android 버전을 실행하거나 잠금 해제된 부트로더를 보유하거나 제조업체의 인증을 받지 않았을 수 있습니다.
기기 무결성	`MEETS_STRONG_INTEGRITY`	앱이 Google Play 서비스에서 제공하는 Android 기기에서 실행되며 하드웨어 지원 키 저장소와 같은 시스템 무결성을 강력히 보장합니다. 기기는 시스템 무결성 검사를 통과했고 Android 호환성 요구사항을 충족합니다.

추가 라벨을 수신하도록 선택하면 무결성 응답에는 각 라벨 기준이 충족되는 경우 같은 기기의 라벨이 여러 개 포함됩니다. 따라서 가능한 응답 범위에 따라 다르게 동작하도록 백엔드 서버를 준비할 수 있습니다. 예를 들어 MEETS_BASIC_INTEGRITY, MEETS_DEVICE_INTEGRITY, MEETS_STRONG_INTEGRITY를 반환하는 기기는 MEETS_BASIC_INTEGRITY만 반환하는 기기보다 더 신뢰할 수 있으며 서버의 응답 방식은 적절하게 조정할 수 있습니다.

API 응답을 수정하려면 다음 안내를 따르세요.

Play Console을 열고 앱 무결성 페이지(출시 > 설정 > 앱 무결성)로 이동합니다.
Integrity API 탭을 클릭합니다.
'응답' 섹션으로 스크롤합니다.
수정을 클릭합니다.
변경할 API 응답 옆에 있는 체크박스를 선택하거나 선택 해제합니다.
변경사항 저장을 클릭합니다.

중요: API 응답에 대한 변경사항은 앱이 프로덕션 단계에 있는 경우를 포함하여 저장하는 즉시 적용됩니다. Play Console에서 API 응답 세트를 변경하기 전에 서버가 이러한 응답을 수락할 준비가 되어 있는지 확인합니다.

Play Integrity API 사용 모니터링 및 등급 변경

앱의 사용 등급에 따라 API에 전송할 수 있는 일일 최대 요청 수가 앱에 적용됩니다. 표준 등급의 앱은 Integrity API에 하루당 최대 10,000개의 요청을 전송할 수 있습니다.

앱의 사용 등급을 확인하려면 다음 안내를 따르세요.

Play Console을 열고 앱 무결성 페이지(출시 > 설정 > 앱 무결성)로 이동합니다.
Integrity API 탭을 클릭합니다.
'설정' 섹션으로 스크롤합니다.
사용 등급을 확인합니다.

앱의 일일 요청량을 보려면 Google Cloud Console에서 연결된 Cloud 프로젝트를 확인하세요.

일일 요청 수를 10,000개 이상으로 상향 조정하려면 앱 사용 등급을 높음 등급으로 변경해 달라고 요청할 수 있습니다. 높음 등급을 사용하려면 다음 자격요건을 충족해야 합니다.

재시도를 포함하여 API 로직의 올바른 구현을 확인합니다.
다른 배포 채널은 물론 Google Play에도 앱을 게시합니다.

앱의 사용 등급을 변경하려면 이 양식을 작성하세요.

Play Integrity API 통합 테스트하기

Gmail 계정 목록을 설정하여 Integrity API 통합을 테스트할 수 있습니다. 먼저 테스터가 버전에 액세스할 수 있는지 확인합니다.

내부 테스트 트랙 또는 테스트하려는 트랙에 앱을 게시합니다. 그런 다음 테스터가 버전에 액세스할 수 있도록 이메일 주소로 테스터 관리 또는 Google 그룹스 사용 관련 안내를 따릅니다.

테스트를 설정하려면 다음 안내를 따르세요.

Play Console을 열고 앱 무결성 페이지(출시 > 설정 > 앱 무결성)로 이동합니다.
Integrity API 탭을 클릭합니다.
'테스트' 섹션으로 스크롤합니다.
새 테스트 만들기를 클릭합니다.
이메일 목록을 선택하거나 새로 만듭니다.
테스트 만들기를 클릭합니다.

Google Play에서 기기 제외 설정하기

Play 스토어에 관한 Integrity API 응답에 따라 Google Play에 앱을 배포할 때 기기를 제외할 수 있습니다. 제외된 기기에서는 Google Play에 앱이 표시되지 않거나 앱을 설치할 수 없게 됩니다. 기기를 제외하더라도 사용자가 다른 배포 채널 또는 사이드로드 등을 통해 다른 방식으로 앱을 가져오는 것을 막을 수는 없습니다.

중요: 기기 제외는 Play 스토어 앱에서 받은 Integrity API 응답을 사용하므로 API를 통합한 후 앱에서 받은 응답과는 관련이 없습니다.

Integrity API 기기 제외 옵션에는 다음 세 가지가 있습니다.

제외하지 않음: Integrity API를 기반으로 기기를 제외하지 않습니다.
기본 장애만 제외: 기본 무결성을 충족하지 않는 신뢰할 수 없는 기기를 제외합니다.
모든 기기 장애 제외: 기기 무결성을 충족하지 않는 신뢰할 수 없는 기기를 제외합니다.

도움말: Android 개발자 사이트의 Play Integrity API 문서에서 기본 무결성 및 기기 무결성의 정의를 확인할 수 있습니다.

Play Console에서 기기 제외 설정을 변경하는 방법은 다음과 같습니다.

Play Console을 열고 앱 무결성 페이지(출시 > 설정 > 앱 무결성)로 이동합니다.
Integrity API 탭을 클릭합니다.
'기기 제외' 옆에서 무결성 API 응답에 따라 앱을 배포할 때 기기를 제외할지 여부를 선택합니다. 제외된 기기에서는 Google Play를 통해 앱을 검색하거나 설치할 수 없게 됩니다.
변경사항을 저장합니다.

중요: 이렇게 하면 기기 카탈로그 제외 규칙이 자동으로 업데이트됩니다.