KappS 지식 베이스 · 블로그

Google Play Install Referrer API 2026: 어트리뷰션 데이터와 연결 상태

블로그 가이드

설치 어트리뷰션은 모든 유료 설치가 의존하는 단 하나의 측정값이며, Google Play에서는 작은 인터페이스 하나로 제공됩니다. 바로 Install Referrer API입니다. 대시보드 기능도 아니고 숫자를 메일로 보내주지도 않습니다. 설치 시점에 Play가 기록한 추천 콘텐츠를 앱에 한 번 전달할 뿐이고, 이후 저장하고 대조하는 것은 직접 해야 합니다. 이 튜토리얼은 API가 반환하는 내용, 연결 방법, 응답 해석법, 대부분의 팀이 너무 늦게 알게 되는 90일 규칙, 그리고 각 연결 상태별 대응까지 전 과정을 다룹니다.

아래 내용은 모두 Google의 Install Referrer API 및 Play Install Referrer 클라이언트 라이브러리 공식 레퍼런스 문서를 근거로 하며, 두 문서 모두 2026-10-27에 확인했습니다.

1단계 — API를 설계에 반영하기 전에 API가 정확히 무엇을 반환하는지 파악하세요

이 API는 Play 스토어 앱이 기록한 추천 콘텐츠를 가져오며, 문서화된 페이로드는 좁고 구체적입니다:

  • 설치된 패키지의 리퍼러 URL
  • 리퍼러 클릭의 타임스탬프(초 단위) — 클라이언트와 서버 양쪽에서 확인 가능;
  • 설치가 시작된 시점의 타임스탬프(초 단위) — 역시 클라이언트와 서버 양쪽 모두;
  • 최초 설치 시점의 앱 버전;
  • 사용자가 지난 7일 이내에 앱의 인스턴트 체험과 상호작용했는지 여부.

모든 것을 좌우하는 두 가지 조건이 있습니다. API는 기기의 Play 스토어 앱에서 제공되며, Play 스토어 8.3.73 이상이 설치된 기기는 자동으로 사용할 수 있습니다. Google Play Console 계정도 필요합니다. 내부적으로 이 API는 AIDL 인터페이스이므로, Kotlin과 Java 개발자는 원시 AIDL 대신 클라이언트 라이브러리 래퍼를 사용해야 합니다.

설계상의 결과: 이는 클릭 타임스탬프와 설치 시작 타임스탬프가 있는 최초 설치 어트리뷰션입니다. 응답에는 멀티터치 체인도, 조회 기반 어트리뷰션도, 교차 기기 그래프도 없습니다. 리포팅 모델이 이 중 하나를 전제한다면 데이터는 다른 곳에서 가져와야 합니다.

2단계 — 클라이언트 라이브러리 추가하기

앱 모듈의 build.gradle에 의존성을 추가하세요. 클라이언트 라이브러리 페이지에 문서화된 버전은 2.2입니다:

dependencies { ... implementation "com.android.installreferrer:installreferrer:2.2" }

모듈이 Kotlin DSL로 구성되어 있다면 동일한 좌표를 implementation("com.android.installreferrer:installreferrer:2.2")로 추가합니다. 그 외에 필요한 것은 없습니다. 매니페스트 리시버도, 권한도, Play Console 토글도 필요하지 않습니다. 이 라이브러리는 기존 브로드캐스트 리시버 방식을 대체하는 것이므로 두 방식을 함께 사용하지 마세요.

3단계 — Play 스토어 앱에 연결하기

연결은 비동기 방식이며, 바로 이 점에서 대부분의 잘못된 구현이 시작됩니다. 문서에 나온 순서는 다음과 같습니다. InstallReferrerClient.newBuilder(this).build()로 클라이언트를 생성하고, startConnection()을 호출한 뒤, 결과를 받는 InstallReferrerStateListener를 전달합니다.

referrerClient = InstallReferrerClient.newBuilder(this).build() referrerClient.startConnection(object : InstallReferrerStateListener { override fun onInstallReferrerSetupFinished(responseCode: Int) { when (responseCode) { InstallReferrerResponse.OK -> { /* 연결됨 */ } InstallReferrerResponse.FEATURE_NOT_SUPPORTED -> { /* 이 Play 스토어 앱에서 API를 사용할 수 없음 */ } InstallReferrerResponse.SERVICE_UNAVAILABLE -> { /* 연결할 수 없음 */ } } } override fun onInstallReferrerServiceDisconnected() { /* 다음 요청 전에 startConnection()을 다시 호출하세요 */ } })

콜백 계약을 문자 그대로 읽으세요. OK는 연결에 성공했으며 계속 진행해도 된다는 뜻입니다. FEATURE_NOT_SUPPORTED는 해당 기기의 Play 스토어 앱에서 API를 사용할 수 없다는 뜻으로, 오래되었거나 비표준 스토어 빌드일 뿐 코드의 버그가 아닙니다. SERVICE_UNAVAILABLE는 연결 자체가 이루어지지 않았다는 뜻으로, 판정이 아니라 타이밍 문제입니다.

연결 끊김은 예외가 아니라 예상되는 일입니다. Google의 설명에 따르면 Play Store 서비스가 백그라운드에서 업데이트 중이면 클라이언트 연결이 끊길 수 있으며, 이후 요청 전에 startConnection()을 다시 호출해 연결을 재시작해야 합니다. 따라서 리스너는 일회성이 아니며, 직접 구동하는 상태 머신으로 다뤄야 합니다.

4단계 — 리퍼러 세부 정보 확인

연결되면 getInstallReferrer()는 동기화 호출로 ReferrerDetails 객체를 반환합니다. 각 필드는 1단계에 나열된 페이로드와 일대일로 대응합니다.

val response: ReferrerDetails = referrerClient.installReferrer val referrerUrl: String = response.installReferrer val referrerClickTime: Long = response.referrerClickTimestampSeconds val appInstallTime: Long = response.installBeginTimestampSeconds val instantExperienceLaunched: Boolean = response.googlePlayInstantParam

이 중 두 가지는 보기보다 유용합니다. referrerClickTimestampSeconds와 installBeginTimestampSeconds를 사용하면 캠페인별 클릭-설치 간격을 계산할 수 있습니다. 간격이 길면 보통 광고가 아니라 스토어 페이지에서 사용자를 놓쳤다는 뜻입니다. googlePlayInstantParam는 지난 7일 이내에 인스턴트 환경에서 설치가 이루어졌는지 알려주며, 응답에서 유일한 인스턴트 어트리뷰션 신호입니다.

5단계 — 90일 기간을 준수하고 한 번만 요청하세요

팀의 과거 데이터를 날려버리는 문장이 바로 이것입니다: 설치 리퍼러 정보는 90일 동안 제공되며 앱을 재설치하지 않는 한 변경되지 않습니다. 이어지는 Google의 안내도 마찬가지로 명확합니다. 불필요한 API 호출을 피하려면 설치 후 첫 실행 시 API를 한 번만 호출하세요.

90일은 저장 기한이 아닙니다. Play에서 해당 값을 여전히 조회할 수 있는 기간이므로, 이후 세션에서 지연 조회만 하는 앱에는 엄격한 마감 기한이 있습니다. 설치 후 첫 실행 시 읽고 영구 저장하세요. 앱을 재설치하지 않는 한 값이 바뀌지 않으므로 갱신 루프는 아무 이득도 없고 호출만 늘립니다.

작업이 끝나면 연결을 닫으세요. 클라이언트에서 endConnection()을 호출하면 됩니다. Google의 이유는 명확합니다. 연결을 닫으면 기기에서 누수와 성능 문제를 방지할 수 있습니다.

6단계 — 응답 코드에 따라 분기하고, 무작정 재시도하지 마세요

최초 실행 시 어트리뷰션 조회는 사용자의 첫 경험에서 핵심 경로에 놓이므로, 실패 정책이 코드만큼 중요합니다. 실용적인 매핑은 다음과 같습니다.

  • 확인 — 읽고 저장한 뒤 endConnection()을 호출하세요. 이후 실행 시 다시 읽지 마세요.
  • SERVICE_UNAVAILABLE — "지금은 아님"으로 처리하세요. 아무것도 저장하지 말고 첫 화면을 차단하지 않으며, 90일 이내에 다음 실행 시 다시 시도하세요.
  • FEATURE_NOT_SUPPORTED — 이 기기에 해당 API가 없습니다. 자체 링크에 담긴 캠페인 식별자로 대체하고, 읽기가 지원되지 않았음을 기록해 보고서에서 자연 유입으로 조용히 집계되지 않도록 하세요.
  • 연결 끊김 — 다음 요청 전에 startConnection()으로 다시 시작하세요. 클라이언트가 아직 살아 있다고 가정하지 마세요.

네 가지 원칙 위에 놓이는 엔지니어링 규칙이 하나 있습니다. 바로 어트리뷰션이 첫 실행 UX를 막아서는 안 되고, 읽기 실패가 잘못된 '오가닉' 어트리뷰션 행을 기록해서도 안 된다는 것입니다. '데이터 없음'과 '오가닉'의 차이는 정확히 설치 리포트 집계가 어긋나기 시작하는 지점입니다.

7단계 — 리퍼러 문자열을 신뢰할 수 없는 입력으로 취급하기

클라이언트 라이브러리는 리퍼러 값을 문자열로 반환합니다. 플랫폼이 전달하지만 여전히 앱 외부에서 온 값이므로 외부 입력에 대한 일반적인 위생 수칙이 적용됩니다. 키-값 쌍으로 방어적으로 파싱하고, 길이를 제한하며, 검증 없이 URL, 딥링크 경로, 데이터베이스 쿼리에 삽입하지 마세요.

실무적으로는 이렇게 하세요. 값을 디코딩하고, 문서화된 구분자로 분리하고, 실제로 인식하는 캠페인 키만 화이트리스트에 넣고, 나머지는 모두 버립니다. 그런 다음 결제나 수익 입력값이 되기 전에 자체 서버 측 이벤트와 대조하세요. 어트리뷰션 데이터는 어느 채널에 예산을 줄지 결정합니다. 검증되지 않은 문자열이 돈을 움직이게 해서는 안 됩니다.

리퍼러 문자열이 광고 네트워크나 MMP로 전달된다면, 파이프라인이 출시된 후가 아니라 감사 전에 Play 데이터 보안 신고와 개인정보처리방침이 이미 해당 공유를 포함하고 있는지 확인하세요. 어트리뷰션 구성은 데이터 수집이며, 신고서는 이를 설명해야 합니다.

8단계 — API가 알려주지 않는 내용을 기록하세요

어트리뷰션 분쟁 대부분은 정상적인 응답에 잘못된 기대를 걸어서 생깁니다. 두 참조 문서에서 확인할 수 있는 솔직한 한계는 다음과 같습니다.

  • Play 스토어 8.3.73 미만 기기는 해당 API 자체가 없습니다. 대체 처리를 미리 계획하세요. FEATURE_NOT_SUPPORTED는 로그만 남기고 잊어버릴 오류가 아니라 실제로 발생하는 결과입니다.
  • 이 값은 최초 설치 시 고정되며 앱을 재설치하지 않는 한 바뀌지 않습니다. 따라서 재참여 유도, 업그레이드, 이후의 캠페인 접점을 표현할 수 없습니다.
  • 조회 가능 기간은 90일 후 종료됩니다 — 그 기간 내에 저장하지 않은 것은 사라집니다.
  • 인스턴트 체험 플래그는 7일 소급 범위에만 적용됩니다.
  • 이는 Play에서의 설치에 대한 기기 및 계정 수준의 신호이며, 사용자 신원이 아니고 기기 간 설치를 중복 제거하지도 않습니다.

이 다섯 가지 한도를 어트리뷰션 스키마와 같은 문서에 정리하세요. 캠페인 보고서와 수익 보고서가 어긋날 때, 그 불일치는 대개 클라이언트의 버그가 아니라 이 다섯 가지 중 하나입니다.

출처: Android Developers — Google Play Install Referrer API(developer.android.com/google/play/installreferrer): 페이로드 필드, Play 스토어 8.3.73 이상 요건, AIDL 인터페이스, Play Console 계정 요건. Android Developers — Play Install Referrer Library(developer.android.com/google/play/installreferrer/library, 페이지 최종 업데이트 2026-10-23): 의존성 버전 2.2, 연결 흐름과 응답 코드, getInstallReferrer() 및 ReferrerDetails 필드, 90일간 사용 가능 안내, 설치당 1회 호출 권장 사항, endConnection(). 두 문서 모두 2026-10-27에 확인했습니다. Google는 캠페인별 어트리뷰션 비율이나 스토어 측 지연 수치를 공개하지 않으며, 본문에서도 이를 추정하지 않습니다.

개발자 계정을 대규모로 운영하시나요? 운영 업무를 저희가 처리합니다.

클릭하여 파일 선택 · 우클릭 → 붙여넣기, 또는 Ctrl/⌘+V로 스크린샷 붙여넣기

파일을 이 상자로 끌어다 놓아도 됩니다.

입력하신 이메일로 답변드립니다. 고객님의 정보는 KappS에만 보관됩니다.

✔ 제출 완료

메시지를 접수했습니다. 24시간 이내에 답변드리겠습니다.


← 수정으로 돌아가기