경고: AIDL은 현재 지원이 중단되었으며 향후 출시되는 버전에서 삭제될 예정입니다. Google Play의 결제 기능을 구현하려면 Google Play 결제 라이브러리를 사용하세요.
이 문서에서는 Google Play 결제 AIDL을 사용하기 위한 기술 참조 정보를 제공합니다.
서버 응답 코드
다음 표에는 Google Play에서 애플리케이션으로 전송되는 모든 서버 응답 코드가
나열되어 있습니다. Google Play는 응답 코드를 응답 Bundle의
RESPONSE_CODE 키에 매핑되는 정수로 동기식으로
보냅니다. 애플리케이션은 이러한 응답 코드를 모두 처리해야
합니다.
표 1. Google Play 결제 AIDL 호출의 응답 코드 요약
| 응답 코드 | 값 | 설명 |
|---|---|---|
BILLING_RESPONSE_RESULT_OK |
0 | 완료되었습니다. |
BILLING_RESPONSE_RESULT_USER_CANCELED |
1 | 사용자가 뒤로를 눌렀거나 대화를 취소했습니다. |
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE |
2 | 네트워크 연결이 끊겼습니다. |
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE |
3 | 요청한 유형에 Google Play 결제 AIDL 버전이 지원되지 않습니다. |
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE |
4 | 요청한 제품을 구매할 수 없습니다. |
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR |
5 | API에 잘못된 인수가 제공되었습니다. 이 오류는 애플리케이션이 결제용으로 올바르게 서명 또는 설정되지 않았거나, 매니페스트에 필요한 권한이 없음을 나타낼 수도 있습니다. |
BILLING_RESPONSE_RESULT_ERROR |
6 | API 작업 중 치명적인 오류가 발생했습니다. |
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED |
7 | 항목을 이미 소유하고 있기 때문에 구매할 수 없습니다. |
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED |
8 | 항목을 소유하고 있지 않기 때문에 사용할 수 없습니다. |
Google Play 결제 AIDL 참조 - 지원
이 섹션에서는 앱에 사용할 수 있는 결제 지원 유형에 관한 정보를 가져오는 메서드를 설명합니다.
isBillingSupported() 메서드
이 메서드는 다음을 나타냅니다.
- 해당 AIDL 버전이 앱에서 지원되는지
- Google Play가 사용자 국가에서 결제를 지원하는지
- Google Play 결제 시스템이 앱 패키지에 사용 설정되어 있는지
- 앱에서 결제 목적으로 해당 유형의 항목을 사용할 수 있는지
표 2. isBillingSupported() 매개변수
| 키 | 유형 | 설명 |
|---|---|---|
apiVersion
|
int
|
앱에서 사용 중인 Google Play 결제 AIDL의 버전 번호입니다. |
packageName
|
String
|
이 메서드를 호출하는 앱의 패키지 이름입니다. |
type
|
String
|
값은 인앱 상품의 경우 inapp, 정기 결제의 경우 subs여야 합니다.
|
이 메서드는 Google Play 결제 AIDL 버전 3 이상에서 사용할 수 있습니다.
isBillingSupportedExtraParams() 메서드
이 메서드는 추가 매개변수를 포함할 수 있는
네 번째 인수 Bundle을 전달할 수
있다는 점을 제외하면
isBillingSupported()와 동일합니다.
표 3. isBillingSupportedExtraParams()
매개변수.
| 키 | 유형 | 설명 |
|---|---|---|
apiVersion
|
int
|
앱에서 사용 중인 Google Play 결제 AIDL의 버전 번호입니다. |
packageName
|
String
|
이 메서드를 호출하는 앱의 패키지 이름입니다. |
type
|
String
|
값은 인앱 상품의 경우 inapp, 정기 결제의 경우 subs여야 합니다. |
extraParams
|
Bundle
|
앱에서 지원하는 Google Play 결제 시스템의 유형을 추가로 지정하는 추가 매개변수의 집합입니다. 이 번들은 부울 값을 갖는 |
이 메서드는 Google Play 결제 AIDL 버전 7 이상에서 사용할 수 있습니다.
Google Play 결제 AIDL 참조 - 세부정보
Google Play 결제 AIDL은 버전 3 샘플 애플리케이션에 포함된 IInAppBillingService.aidl 파일에 정의되어 있습니다.
getSkuDetails() 메서드
getSkuDetails() 메서드를 사용하면 관련 제품 ID 목록의 제품 세부정보를 가져올 수 있습니다.
표 4. GetSkuDetails() 매개변수
| 키 | 유형 | 설명 |
|---|---|---|
apiVersion
|
int
|
앱에서 사용 중인 Google Play 결제 AIDL의 버전 번호입니다. |
packageName
|
String
|
이 메서드를 호출하는 앱의 패키지 이름입니다. |
type
|
String
|
인앱 상품 유형(일회성 구매의 경우 'inapp', 정기 결제의 경우 'subs')입니다. |
skusBundle
|
Bundle
|
키가 ITEM_ID_LIST인 SKU의 StringArrayList를 포함하는 번들입니다.
|
getSkuDetails() 메서드가 성공하면 Google Play에서 응답 Bundle을 보냅니다. 쿼리 결과는 DETAILS_LIST 키에 매핑된 문자열 ArrayList 내 Bundle에 저장됩니다. 세부정보 목록의 각 문자열에는 단일 제품에 관한
JSON 형식의 제품 세부정보가 포함됩니다. 제품 세부정보를 포함한 JSON 문자열의 필드는
표 5에 요약되어 있습니다.
표 5. getSkuDetails() 요청에서 반환된 제품 항목 세부정보가 포함된 JSON 필드에 관한 설명
| 키 | 설명 |
|---|---|
productId |
제품의 제품 ID입니다. |
type |
값은 인앱 상품의 경우 inapp, 정기 결제의 경우 subs여야 합니다. |
price |
형식이 지정된 항목 가격(통화 기호 포함)입니다. 세금을 제외한 가격입니다. |
price_amount_micros |
마이크로 단위 가격입니다. 1,000,000마이크로 단위는 실제 통화의 1단위와 같습니다. 예를 들어 price가 "€7.99"인 경우,
price_amount_micros는 "7990000"입니다. 이 값은 특정 통화의 현지화된 반올림 가격을 나타냅니다. |
price_currency_code |
ISO 4217
통화 코드는 price입니다. 예를 들어 price가
영국 파운드로 지정되어 있으면 price_currency_code는
"GBP"입니다. |
title |
제품 이름입니다. |
description |
제품 설명입니다. |
subscriptionPeriod |
ISO 8601 형식으로 지정된
구독 기간입니다.
예를 들어 P1W는 1주,
P1M은 1개월, P3M은 3개월,
P6M은 6개월, P1Y는 1년에
해당합니다.
참고: 정기 결제의 경우에만 반환됩니다. |
freeTrialPeriod |
Google Play Console에서 설정된 평가판 기간에
ISO 8601 형식을 지정한 것입니다. 예를 들어
P7D는 7일에 해당합니다.
무료 체험판 자격요건에 관해 자세히 알아보려면 인앱 정기 결제를 참조하세요.
참고: 체험판 기간이 설정된 정기 결제의 경우에만 반환됩니다. |
introductoryPrice |
€3.99와 같이 통화 기호가 포함되었으며 형식이 지정된 신규 할인 가격입니다. 세금을 제외한 가격입니다.
참고: 할인 기간이 설정된 정기 결제의 경우에만 반환됩니다. |
introductoryPriceAmountMicros |
신규 할인 가격은 마이크로 단위로 되어 있습니다. 통화는 price_currency_code와 동일합니다.
참고: 할인 기간이 설정된 정기 결제의 경우에만 반환됩니다. |
introductoryPricePeriod |
ISO 8601 형식이 지정된 할인 가격
결제 기간입니다.
참고: 초기 기간이 설정된 구독의 경우에만 반환됩니다. |
introductoryPriceCycles |
사용자에게 할인 가격이 주어지는 구독 결제 기간
수입니다(예: 3). 참고: 할인 기간이 설정된 정기 결제의 경우에만 반환됩니다. |
getBuyIntent() 메서드
이 메서드는 Google Play 결제 구현에 설명된 것과 같이 RESPONSE_CODE 키에 매핑된 응답 코드 정수 및 PendingIntent를 반환하여 BUY_INTENT 키에 매핑된 인앱 상품의 구매 절차를 시작합니다. 이 메서드에서 PendingIntent를 수신하면 Google Play가 관련 구매주문서에 관한 데이터를 포함한 응답 Intent를 보냅니다.
응답 Intent에 반환되는 데이터는 표 6에 요약되어 있습니다.
참고: 이 메서드를 사용하는 대신 추가 기능을 제공하는
getBuyIntentExtraParams()를
사용하는 것이 좋습니다.
표 6. Google Play 구매 요청의 응답 데이터
| 키 | 설명 |
|---|---|
RESPONSE_CODE |
구매에 성공하면 값이 0, 그러지 않으면 오류입니다. |
INAPP_PURCHASE_DATA |
구매주문서의 세부정보가 포함된 JSON 형식의 문자열입니다. JSON 필드에 관한 설명은 표 7을 참조하세요. |
INAPP_DATA_SIGNATURE |
개발자의 개인 키로 서명된 구매 데이터의 서명이 포함된 문자열입니다. 데이터 서명에는 RSASSA-PKCS1-v1_5 스키마가 사용됩니다. |
표 7에는 구매주문서에 대한 응답 데이터에서 반환되는 JSON 필드가 설명되어 있습니다.
표 7. INAPP_PURCHASE_DATA의 JSON 필드에 관한 설명
| 필드 | 설명 |
|---|---|
autoRenewing |
구독이 자동으로 갱신되는지 여부를 나타냅니다. true인 경우
정기 결제가 활성 상태로, 다음 결제 날짜에
자동으로 갱신됩니다. false인 경우
사용자가 정기 결제를 취소했다는 의미입니다. 사용자는 다음 결제 날짜까지 정기 결제 콘텐츠에 액세스할 수 있으며, 자동 갱신을 다시 활성화하거나 수동 갱신에 설명되어 있는 것처럼 수동으로 갱신하지 않으면 결제 날짜에 액세스 권한을 잃게 됩니다.
유예 기간을 제공하면 유예 기간이 경과되지 않는 한 모든 정기 결제에서 이 값이 true로 유지됩니다. 유예 기간이 끝나거나 사용자가 결제 수단 문제를 해결할 때까지는 다음 결제 날짜가 매일 동적으로 연장됩니다.
|
orderId |
거래의 고유 주문 식별자입니다. 이 식별자는 Google 결제 주문 ID에 대응됩니다. |
packageName |
구매가 시작된 애플리케이션 패키지입니다. |
productId |
항목의 제품 식별자입니다. 항목마다 제품 ID가 있는데, Google Play Console의 애플리케이션 제품 목록에서 이 ID를 지정해야 합니다. |
purchaseTime |
제품이 구매된 시간을 Epoch 기준 시간(1970년 1월 1일) 이후 밀리초 단위로 나타낸 것입니다. |
purchaseState |
주문의 구매 상태입니다. 항상 0(구매함)이 반환됩니다. |
developerPayload |
주문의 추가 정보가 포함된 개발자 지정 문자열입니다. getBuyIntent 요청을 할 때 이 필드의 값을 지정할 수 있습니다. |
purchaseToken |
특정 항목 및 사용자 쌍에 관해 구매를 고유하게 식별하는 토큰입니다. |
consumePurchase() 메서드
주어진 구매 토큰에 해당하는 구매를 사용합니다. 이렇게 하면 이 항목이 getPurchases()에 관한 이후의 모든 응답에서 삭제되며, 같은 SKU의 항목을 재구매할 수 있도록 허용됩니다.
표 8. consumePurchase() 매개변수
| 키 | 유형 | 설명 |
|---|---|---|
apiVersion
|
int
|
앱에서 사용 중인 Google Play 결제 AIDL의 버전 번호입니다. |
packageName
|
String
|
이 메서드를 호출하는 앱의 패키지 이름입니다. |
purchaseToken
|
String
|
사용될 구매를 식별하는 구매 정보 JSON의 토큰입니다. |
이 메서드는 성공한 사용의 RESULT_OK(0)를 반환하고, 실패 시 적절한 응답 코드를 반환합니다.
getBuyIntentToReplaceSkus() 메서드
이 메서드는 구독 구매를 업그레이드하거나 다운그레이드하는 데 사용됩니다. 구매 중인 SKU로 대체될 기존 구매 SKU가 정확히 1개 포함된 목록을 가져온다는 점을 제외하면 getBuyIntent()와 유사합니다. 사용자가 구매를 완료하면
Google Play는 이전의 SKU를 교환하고, 비례 계산을 통해
사용하지 않은 정기 결제 시간만큼의 금액을 사용자에게 크레딧으로 돌려줍니다. Google Play는
이 크레딧을 신규 구독에 적용하고, 크레딧이 소진될 때까지 사용자에게 신규 구독
금액을 청구하지 않습니다.
참고: 이 메서드를 사용하는 대신 추가 기능을 제공하는
getBuyIntentExtraParams()를
사용하는 것이 좋습니다.
이 메서드는 Google Play 결제 AIDL 버전 5와 함께 추가되었습니다. 메서드가 보고되었는지 확인하려면 isBillingSupported AIDL 요청을 보내세요.
참고: 구독 구매에만 이 메서드를
사용할 수 있습니다. 전달된 type 매개변수가 "subs"가 아니라면 BILLING_RESPONSE_RESULT_DEVELOPER_ERROR를 반환합니다.
또한 전달된 SKU에는 시즌 정기 결제의 SKU가 포함되어 있지 않을 수 있습니다.
이 메서드는 RESPONSE_CODE 키에 매핑된 응답 코드 정수 및 BUY_INTENT 키에 매핑된 인앱 정기 결제의 구매 흐름을 시작하는 PendingIntent를 반환합니다. 이 메서드에서 PendingIntent를 수신하면 Google Play가 관련 구매주문서에 관한 데이터를 포함한 응답 Intent를 보냅니다.
응답 Intent에 반환되는 데이터는 표 9에 요약되어 있습니다.
표 9. Google Play 결제 AIDL 버전 5 구매 요청의 응답 데이터
| 키 | 설명 |
|---|---|
RESPONSE_CODE |
구매에 성공하면 값은 0입니다. 구매에 실패할 경우에는 오류 코드를
포함합니다. |
INAPP_PURCHASE_DATA |
구매주문서의 세부정보가 포함된 JSON 형식의 문자열입니다. JSON 필드에 관한 설명은 표 6을 참조하세요. |
INAPP_DATA_SIGNATURE |
개발자의 개인 키로 서명된 구매 데이터의 서명이 포함된 문자열입니다. 데이터 서명에는 RSASSA-PKCS1-v1_5 스키마가 사용됩니다. |
getBuyIntentExtraParams() 메서드
이 메서드는 구매 요청을 시작합니다. 이 메서드는 getBuyIntent() 메서드의 변형이며, 추가 extraParams 매개변수가 필요합니다. 이 매개변수는 표 10에 제시된 메서드의 실행에 영향을 주는 선택적 키 및 값의 Bundle입니다.
표 10. getBuyIntentExtraParams() 추가
매개변수.
| 키 | 유형 | 설명 |
|---|---|---|
skusToReplace
|
List<String>
|
사용자가 업그레이드 또는 다운그레이드하는 SKU가 정확히 1개 포함된 선택적 목록입니다. 구매가 기존 정기 결제를 업그레이드 또는 다운그레이드하는 경우 이 필드를 전달합니다. 지정된 SKU는 사용자가 구매 중인 SKU로 대체됩니다. Google Play는 다음 결제 주기가 시작될 때 지정된 SKU를 대체합니다. |
replaceSkusProration
|
boolean
|
사용자가 업그레이드 또는 다운그레이드하는 SKU에서 사용하지 않은 구독 기간과 관련하여 사용자에게 크레딧을 제공할지 여부를 지정합니다. 이 필드를 true로 설정하면 Google Play는 이전의 SKU를 교환하고, 비례 계산을 통해 사용하지 않은 정기 결제 시간만큼의 금액을 사용자에게 크레딧으로 돌려줍니다. Google Play는 이 크레딧을 신규 정기 결제에 적용하고, 크레딧이 소진될 때까지 사용자에게 신규 정기 결제 금액을 청구하지 않습니다. 이 필드를 false로 설정하면 사용자가 사용하지 않은 정기 결제 기간에 대해 크레딧을 받지 못하며, 갱신 날짜도 변경되지 않습니다.
기본값은 true입니다. |
accountId
|
String
|
앱에서 사용자 계정과 고유하게 연결된 선택적 난독화 문자열입니다. 값을 전달하면 Google Play에서 이 값을 사용하여 짧은 기간 내에 여러 기기에서 같은 계정으로 구매하는 등의 비정상적인 활동을 감지할 수 있습니다. 이 필드는 단일 사용자를 나타낸다는 점에서 이 필드에 Google Play Console 개발자 ID 또는 사용자의 Google ID를 사용하면 안 됩니다. 또한 이 필드에는 사용자의 ID를 일반 텍스트로 포함해서는 안 됩니다. 사용자의 ID에서 문자열을 생성할 때는 단방향 해시를 사용하고, 이 필드에 해시된 문자열을 저장하는 것이 좋습니다. |
developerId
|
String
|
모든 앱에서 사용자 계정과 고유하게 연결된 선택적인 난독화 문자열입니다. 이 필드는 단일 사용자를 나타낸다는 점에서 이 필드에 Google Play Console 개발자 ID 또는 사용자의 Google ID를 사용하면 안 됩니다. 또한 이 필드에는 사용자의 ID를 일반 텍스트로 포함해서는 안 됩니다. 사용자의 ID에서 문자열을 생성할 때는 단방향 해시를 사용하고 이 필드에는 해시된 문자열을 저장하는 것이 좋습니다. |
vr
|
boolean
|
제공된 인텐트가 가상 현실(VR) 구매 흐름의 시작을 나타내는지 지정합니다. 참고: 이 추가 매개변수가 앱에 영향을 미치도록 하려면 Google Play 결제 AIDL 버전 7 이상 또는 최신 API를 사용해야 합니다. |
이 메서드는 Google Play 결제 AIDL 버전 6 이상에서 사용할 수 있습니다.
getPurchases() 메서드
이 메서드는 구매 항목과 프로모션 코드를 사용해 획득한 항목을 모두 포함하여
사용자가 소유하고 있지만 현재 사용되지 않은 제품을 반환합니다.
표 11에는 Bundle에 반환되는 응답 데이터가 표시되어 있습니다.
표 11. getPurchases 요청의 응답 데이터
| 키 | 설명 |
|---|---|
RESPONSE_CODE |
요청에 성공하면 값은 0이고, 성공하지 못하면 오류입니다. |
INAPP_PURCHASE_ITEM_LIST |
이 앱에서 구매한 항목의 productid 목록이 포함된 StringArrayList입니다. |
INAPP_PURCHASE_DATA_LIST |
이 앱에서 구매한 세부정보가 포함된 StringArrayList입니다. 목록의 각 항목에 저장되는 자세한 정보의 목록은 표 13을 참조하세요. |
INAPP_DATA_SIGNATURE_LIST |
이 앱에서 구매한 항목의 서명이 포함된 StringArrayList입니다. |
INAPP_CONTINUATION_TOKEN |
사용자가 소유한 다음 인앱 상품 집합을 가져오기 위한 연속 토큰이 포함된 문자열입니다. 이 문자열은 사용자가 소유한 제품
개수가 매우 많을 경우 Google Play 서비스에 의해서만 설정됩니다. 응답에
연속 토큰이 있을 때는 getPurchases를
따로 호출해서 수신한 연속 토큰을 전달해야
합니다. 후속 getPurchases 호출은 더 많은 구매 항목을 반환하고 다른 연속 토큰도 반환할 수 있습니다. |
getPurchaseHistory() 메서드
이 메서드는 각 SKU와 관련하여 사용자가 가장 최근에 완료한 구매를 반환합니다.
구매 항목이 만료, 취소, 사용된 경우에도 마찬가지입니다. 표 12에는 Bundle에 반환되는 응답 데이터가 표시되어 있습니다.
표 12. getPurchaseHistory 요청의 응답 데이터
| 키 | 설명 |
|---|---|
RESPONSE_CODE |
요청에 성공하면 값은 0이고, 성공하지 못하면 오류입니다.
|
INAPP_PURCHASE_ITEM_LIST |
이 앱에서 구매한 항목의 productid 목록이 포함된 StringArrayList입니다. |
INAPP_PURCHASE_DATA_LIST |
이 앱에서 구매한 세부정보가 포함된 StringArrayList입니다. 목록의 각 INAPP_PURCHASE_DATA 항목에 저장되는 자세한 정보의 목록은 표 6을 참조하세요.
|
INAPP_DATA_SIGNATURE_LIST |
이 앱에서 구매한 항목의 서명이 포함된 StringArrayList입니다. |
INAPP_CONTINUATION_TOKEN |
사용자가 소유한 다음 인앱 상품 집합을 가져오기 위한 연속 토큰이 포함된 문자열입니다. 이 문자열은 사용자가 소유한 제품
개수가 매우 많을 경우 Google Play 서비스에 의해서만 설정됩니다. 응답에
연속 토큰이 있을 때는 getPurchases를
따로 호출해서 수신한 연속 토큰을 전달해야
합니다. 후속 getPurchases 호출은 더 많은 구매 항목을 반환하고 다른 연속 토큰도 반환할 수 있습니다. |
표 13. getPurchaseHistory()에서 반환된 구매 내역의 JSON 필드에 관한 설명
| 필드 | 설명 |
|---|---|
productId |
항목의 제품 식별자입니다. 항목마다 제품 ID가 있는데, Google Play Console의 애플리케이션 제품 목록에서 이 ID를 지정해야 합니다. |
purchaseTime |
제품이 구매된 시간을 Epoch 기준 시간(1970년 1월 1일) 이후 밀리초 단위로 나타낸 것입니다. |
developerPayload |
주문의 추가 정보가 포함된 개발자 지정 문자열입니다. getBuyIntent 요청을 할 때 이 필드의 값을 지정할 수 있습니다. |
purchaseToken |
특정 항목 및 사용자 쌍에 관해 구매를 고유하게 식별하는 토큰입니다. |
참고: getPurchaseHistory() 메서드는 Google Play 서버를 호출해야 하므로 getPurchases()보다 오버헤드가 큽니다. 사용자의 구매 내역이 실제로 필요하지 않은 경우에는 getPurchases()를 사용해야 합니다.
이 메서드는 Google Play 결제 AIDL 버전 6 이상에서 사용할 수 있습니다.