KappS 지식 베이스 · 블로그

2026년 Google Play 결제 라이브러리

블로그 가이드

무언가를 판매하는 모든 Android 앱(구독, 일회성 잠금 해제, 코인 팩)에는 Google Play의 결제 라이브러리 사본이 포함되어 있습니다. 이 라이브러리는 영구적이지 않습니다. Google는 각 주요 버전을 2년 주기로 지원 종료하며, 버전이 지원 종료되면 앱은 계속 실행되지만 업데이트를 출시할 수 없습니다. 2026년 8월 31일 기준 최소 지원 버전은 Play Billing Library 8이며, 여전히 버전 7 이하로 빌드된 모든 릴리스에는 2026년 11월 1일의 연장 마감 기한이라는 단 하나의 남은 기회가 있습니다.

이 글은 그 이관의 실무 버전입니다. 지원 종료 표가 현재 실제로 무엇을 말하는지, 특정 APK가 어떤 버전을 탑재했는지 확인하는 방법, 7에서 8 또는 9로 넘어갈 때 컴파일을 깨뜨리는 정확한 API 이름 변경, 연장 신청 양식이 있는 위치, 빌드를 출시하기 전에 테스트해야 할 항목을 다룹니다.

이 마이그레이션을 결정하는 네 가지 숫자: 2년 — Google이 2019년 I/O에서 정책을 발표한 이후 모든 Play Billing Library 주요 버전에 적용된 지원 종료 주기입니다. 2026년 8월 31일 — 신규 앱과 업데이트가 버전 8 이상을 사용해야 하는 날짜입니다(v7 마감 기한). 2026년 11월 1일 — 동일 버전에 대한 연장 마감 기한입니다. 8 — 현재 Google Play이 새 릴리스에서 허용하는 최저 버전입니다.

1. 현재 마감 기한의 실제 상황

Google의 Play 결제 라이브러리 버전 지원 종료 페이지 상단 배너에는 이렇게 적혀 있습니다. "2026년 8월 31일까지 모든 신규 앱과 기존 앱 업데이트는 결제 라이브러리 버전 8 이상을 사용해야 합니다. 앱 업데이트에 시간이 더 필요하면 2026년 11월 1일까지 연장을 요청할 수 있습니다." 이 문장이 곧 규정 전체이며, 사람들이 흔히 혼동하는 두 부분으로 나뉩니다.

전반부는 제거가 아닌 배포 제한입니다. 지원 종료된 버전을 여전히 포함한 앱은 이미 설치한 사용자에게는 계속 작동하지만, Play는 새 릴리스를 받아주지 않습니다. 지원 종료 FAQ는 그 당연한 결과를 분명히 밝힙니다. 유지 관리되지 않는 APK는 업데이트할 필요가 없지만, 새 앱과 업데이트는 지원되는 버전을 사용해야 합니다. 따라서 리스크는 '내 앱이 스토어에서 사라진다'가 아니라 '이 작업을 끝내기 전까지는 수정 사항, 새로운 스토어 등록정보 실험, 컴플라이언스 업데이트를 배포할 수 없다'입니다.

나머지 절반은 탈출구, 즉 연장입니다. 연장은 Play Console 내에서 요청하며, 새로운 카운트다운이 아닌 동일한 고정 캘린더 날짜를 기준으로 부여됩니다. 따라서 2026년 9월 말에도 여전히 v7을 사용 중인 개발자에게 실질적인 질문은 시간이 있는지가 아니라 연장을 이미 신청했는지입니다.

2. 지원 종료 시점은 고정되어 있으며 사전에 공지됩니다

Google가 전체 지원 종료 일정표를 공개했으며, 이는 경고가 아니라 일정으로 읽어야 합니다. 각 주요 버전에는 "신규 앱 및 업데이트" 마감일인 8월 31일과 2년 후 연장 마감일인 11월 1일이 있습니다.

  • 버전 5 — 신규 앱 및 업데이트 마감 기한 2024년 8월 31일, 연장 마감 기한 2024년 11월 1일.
  • 버전 6 — 2025년 8월 31일; 연장 2025년 11월 1일.
  • 버전 7 — 2026년 8월 31일; 연장 2026년 11월 1일.
  • 버전 8 — 2027년 8월 31일; 연장 2027년 11월 1일.
  • 버전 9 — 2028년 8월 31일; 연장 2028년 11월 1일.

여기서 두 가지 결론이 나옵니다. 첫째, 2025년에 이미 두 버전 뒤처져 있던 앱은 이제 세 버전 뒤처졌으며, 지금 드는 노력은 그때 들었을 노력과 같습니다. 둘째, 이는 일회성 프로젝트가 아니라 영구적인 유지보수 항목입니다. 이번에 어떤 버전을 선택하든 2년 안에 다시 이 자리로 돌아오게 됩니다. 정기 릴리스 일정에 맞춰 버전 상향을 계획하는 편이 Console 경고에 대응하는 것보다 비용이 적게 듭니다.

3. 1단계 — 릴리스에 실제로 포함되는 항목 파악하기

build.gradle부터 시작하세요. Billing Library는 com.android.billingclient:billing 의존성으로 선언되어 있으며, 버전 문자열이 답입니다.

dependencies { def billingVersion = "8.3.0" implementation "com.android.billingclient:billing:$billingVersion" }

지원 종료 FAQ에는 중요한 세부 사항이 하나 더 있습니다. 이러한 의존성은 com.android.vending.BILLING 권한을 요구하는 APK에만 나타납니다. 멀티 모듈 프로젝트나, 일부 앱이 오래된 공유 모듈을 사용하는 포트폴리오에서는 문제가 되는 빌드가 결제를 선언한 빌드이지, 반드시 생각하는 그 앱은 아닙니다. 결제 코드를 작성했다고 기억하는 번들만이 아니라 결제가 포함된 모든 번들을 감사하세요.

고집스러운 경고를 설명해 주는 두 번째 확인 절차도 있습니다. Play는 병합된 AndroidManifest.xml의 com.google.android.play.billingclient.version 속성에서 라이브러리 버전을 식별합니다. 이미 의존성을 업그레이드했는데도 Console에서 여전히 지원 종료된 버전을 보고한다면, 공식 안내는 해당 속성이 존재하는지 확인하라는 것입니다. 매니페스트 병합이 이 속성이 사라지는 흔한 원인입니다.

4. 2단계 — 목표 선택: 버전 8 또는 버전 9

요건은 "버전 8 이상"이므로 8.x와 9.x 모두 충족합니다. 트레이드오프가 실제로 존재하니 의도적으로 선택하세요.

  • 버전 8 — 2025년 6월 30일 출시, 8.x 라인은 2025년 12월 23일 8.3.0으로 마무리되었습니다. 변경 폭이 더 작은 쪽이며, 코드가 v7에 있다면 컴파일 오류는 적고 기계적으로 고칠 수 있습니다.
  • 버전 9 — 9.0.0은 2026년 5월 19일, 9.1.0은 2026년 6월 18일 출시되었습니다. 최신 API를 제공하며 targetSdkVersion을 35로 업데이트합니다. 이는 이미 처리 중인 Play 타깃 API 레벨 정책 요구 사항과 견주어 저울질할 만합니다.

다음 주기를 계획하려고 이 글을 읽고 있다면: v8 자체의 마감 기한은 2027년 8월 31일이며 2027년 11월 1일까지 연장되었습니다. 지금 9.1.0으로 이관하면 가장 긴 여유 기간을 확보할 수 있고, v9 이관 가이드는 7이나 8에서 곧바로 넘어오는 팀을 위해 작성되었습니다.

5. 3단계 — v7 → v8 이관 작업

Play Billing Library 8 공식 이관 가이드에 따르면, 업그레이드는 세 가지 작업과 선택적 작업으로 구성됩니다.

첫 단계: 의존성 올리기. com.android.billingclient:billing을 8.0.0 이상으로 지정하세요(특별한 이유가 없다면 .0 릴리스가 아닌 해당 라인의 최신 패치를 사용).

두 번째 단계: 이름이 변경된 구독 API를 처리하세요. PBL 6에서 넘어올 때 컴파일을 깨뜨리는 호출이 바로 이것이며, 대체 API는 이름만 바꿔 그대로 적용됩니다.

  • setOldSkuPurchaseToken → setOldPurchaseToken
  • setReplaceProrationMode → setSubscriptionReplacementMode
  • setReplaceSkusProrationMode → setSubscriptionReplacementMode

세 번째 변경: queryProductDetailsAsync 수정. ProductDetailsResponseListener.onProductDetailsResponse의 시그니처가 바뀌었으므로 구현 코드를 수정해야 합니다. 시그니처보다 중요한 것은 그 배경에 있는 동작 변화입니다. 8.0.0 이전에는 가져오지 못한 상품이 그냥 반환되지 않았지만, PBL 8에서는 상품을 찾을 수 없음 또는 해당 사용자에게 제공 가능한 상품 없음 등 이유를 설명하는 상품 수준 상태 코드를 담아 반환됩니다. 이전에 UI가 아무 응답이 없는 것만 보고 "이 사용자는 자격이 없다"고 추론했다면, 이제는 추측하지 말고 상태 코드를 읽어야 합니다.

코드에서 아직 이들을 호출하고 있다면 PBL 8에서 함께 제거되었습니다. queryPurchaseHistoryAsync(구매 내역 조회의 대안 사용), querySkuDetailsAsync(queryProductDetailsAsync 사용), 매개변수 없는 enablePendingPurchases()(enablePendingPurchases(PendingPurchaseParams) 사용), 그리고 기존 queryPurchasesAsync(String skuType, PurchasesResponseListener) 오버로드가 해당됩니다. v6 이하에서 곧바로 v8로 넘어온 독자는 enableAlternativeBilling / AlternativeBillingListener / AlternativeChoiceDetails에서도 벗어나야 하며, 이들은 enableUserChoiceBilling / UserChoiceBillingListener / UserChoiceDetails로 대체되었습니다.

선택 사항이지만 도입할 만합니다: BillingClient.Builder.enableAutoServiceReconnection()을 사용하면 연결이 끊긴 뒤 startConnection()을 다시 호출하지 않아도 라이브러리가 Play Billing 서비스 연결을 스스로 복구합니다. Android에서 "구매 버튼이 아무 반응이 없다"는 신고가 가장 많이 나오는 원인이 바로 이것입니다. 같은 릴리스에서는 선불 요금제와 가상 할부 구독에 대한 대기 중 구매 지원도 추가됩니다.

6. 4단계 — 아니면 9.1.0까지 한 번에

The migration guide for Play Billing Library 9 covers teams coming from 7 or 8. Beyond the dependency bump to 9.1.0, the recurring theme is that the legacy SKU vocabulary finally disappears (BillingClient.SkuType → ProductType, SkuDetails → ProductDetails, SkuDetailsParams → QueryProductDetailsParams, SkuDetailsResponseListener → ProductDetailsResponseListener, getSkuDetailsList/setSkuDetailsList → setProductDetailsParamsList), and one change lands directly on subscription revenue logic:

사용자가 무료 체험 자격이 있는지 판단하기 위해 queryPurchaseHistoryAsync를 사용하고 있었다면, 가이드는 사용자가 어떤 오퍼에 자격이 있는지 확인하려면 ProductDetails.getSubscriptionOfferDetails()를 사용하라고 합니다.

v9의 작은 변경 세 가지는 놓치기 쉽습니다. Play 스토어 차단 처리의 응답 코드가 바뀌었습니다. Play 스토어 앱 자체가 차단된 경우(예: 제조사 키즈 모드), 결과 코드가 ERROR에서 BILLING_UNAVAILABLE로 바뀌고 "Play Store is blocked" 디버그 메시지가 표시됩니다. 이 동작이 올바르게 작동하려면 androidx.core 버전 1.9 이상이 필요합니다. DeveloperProvidedBillingDetails.getLinkUri()는 이제 @Nullable이므로, null 및 빈 문자열 검사 없이 해당 URI를 실행하는 코드는 곧바로 크래시로 이어집니다. 또한 9.0.0에는 옵트인 가격 인상에 대한 인앱 메시징이 추가되어, 앱을 벗어나지 않고도 사용자에게 미결 인상을 보여 줍니다. 단, 메시지는 7일마다 한 건으로 제한됩니다.

7. 5단계 — 필요하다면 연장 신청서 작성

앱이 아직 지원되지 않는 버전을 배포하고 있다면 Play Console에서 경고가 표시됩니다. 연장은 경고의 세부정보 페이지에서 신청합니다. 정책 상태를 열고, 경고를 열고, 거기 연결된 연장 양식을 사용하세요. 공식적으로 이것이 유일한 경로입니다. 이메일 신청은 없으며, 해당 버전에 대해 공지된 11월 1일 이후에는 두 번째 연장도 없습니다.

이미 정해진 마감 기한 안에서의 여유분으로 보아야 하며, 추가로 확보한 시간으로 보아서는 안 됩니다. 연장을 신청하더라도 작업은 여전히 2026년 11월 1일 전에 완료되어야 하며, 그 이후에는 v7 기반 신규 릴리스가 더 이상 승인되지 않습니다. 전혀 무관한 정책 때문에 기다리고 있던 컴플라이언스 릴리스도 마찬가지입니다.

8. 6단계 — 출시 전 확인하기

결제 관련 회귀는 크래시로 드러나지 않습니다. 결제하려는 유료 사용자가 구매하지 못하는 형태로 드러납니다. 릴리스가 프로덕션으로 넘어가기 전에:

  • Play 스토어가 실제로 설치된 기기에서 라이선스 테스터를 사용해 실제 구매, 구독 업그레이드 또는 다운그레이드, 복원까지 실행해 보세요. Play 스토어가 없는 에뮬레이터에서는 방금 변경한 연결 처리가 검증되지 않습니다.
  • 이제 상품 상세 조회가 미조회 상품을 상태 코드와 함께 반환하는지, UI가 "찾을 수 없음"과 "이 사용자에게 제공 가능한 오퍼 없음"에 대해 올바른 메시지를 표시하는지 확인하세요.
  • 출시 후 Play Console에서 지원 종료 경고가 사라지는지, 병합된 매니페스트에 com.google.android.play.billingclient.version 속성이 포함되어 있는지 확인하세요.
  • 단계적으로 배포해 결제 관련 회귀가 전체가 아닌 일부 사용자에게만 도달하도록 하고, 이를 대체할 더 높은 버전 코드를 준비하세요.

9. 최신 버전이 수익 측면에서 돌려주는 것

이관은 유상 작업이므로, 최신 라이브러리가 제공하는 이점을 따져보는 것이 타당합니다. PBL 8.0.0은 "인앱 상품"을 일회성 상품으로 이름을 바꾸고, 이에 대한 다중 구매 옵션과 오퍼를 추가했습니다. 덕분에 같은 상품을 여러 가격대로 판매할 때 생성해야 하는 개별 상품 수가 줄어듭니다. 또한 launchBillingFlow()에 하위 응답 코드를 추가했습니다. PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS, USER_INELIGIBLE(사용자가 구독 오퍼에 설정된 자격 요건을 충족하지 않음), 그리고 기본값인 NO_APPLICABLE_SUB_RESPONSE_CODE입니다. 이는 막연한 "문제가 발생했습니다"와 사용자에게 카드 충전을 안내하는 화면의 차이를 만들어 줍니다.

2025년 12월의 8.2.x 및 8.3.0 릴리스에서는 외부 콘텐츠 링크, 외부 오퍼, 외부 결제 API가 추가되었고, 9.1.0에서는 결제 선택 API가 추가되었습니다. 로드맵에 이런 프로그램이 포함되어 있다면 버전 업그레이드는 별도 프로젝트가 아니라 선행 조건입니다. 이미 이 코드를 다루고 있는 김에 9.1.0으로 올리라는 실무적 근거가 바로 여기에 있습니다.


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

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

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

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

✔ 제출 완료

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


← 수정으로 돌아가기