IAP v4 실시간 구독 알림

실시간 구독 알림을 활용하면 게임 서버는 Hive IAP 서버로부터 유저 구독 상태 정보를 실시간으로 수신해 구독 유예, 보류, 일시 정지 기능을 구현할 수 있습니다. 실시간 구독 알림 API는 Hive IAP 서버가 게임 서버를 호출하는 형식이며 Request Body에 구독 상태 변경 정보를 담아 실시간으로 전달하는 API입니다. 따라서, 게임 서버는 이 정보를 수신할 API, 즉 API 엔드포인트(URL)를 Hive에 제공해야 합니다.

API URL은 Hive 콘솔 > 앱센터 > 게임 상세 > 게임서버 탭 > 게임서버 및 마켓 서버 알림 URL 등록에서 등록할 수 있습니다. 게임 서버가 지역별로 나뉘어 있고, 각 게임 서버에서 알림을 수신해야 한다면 게임 서버마다 URL을 제공해주세요. 이후 Hive IAP에서는 URL이 전달된 모든 게임 서버로 알림을 전송합니다.

Hive IAP는 Hive 서버에서 게임 서버로 실시간 구독 상태를 전송합니다. 따라서 알림을 받을 게임 서버는 아래 서버 IP의 인바운드 방화벽을 해제해야 합니다.

  • 43.202.181.138

  • 3.38.239.17

  • 요청 명세 (Hive IAP > 게임 서버)

필드명 설명 타입 필수여부
notification_type 알림 타입

  • Apple
  • Google: 구독 유예/보류/일시정지는 hiveiap_receipt_subscription_state값으로 판단하며, 본 필드 값은 참고 데이터로만 활용하기를 권장
String Y
sub_type 알림 서브 타입입니다. 애플 알림에만 있는 subtype 정보입니다. String N
hiveiap_market_id 결제한 마켓 구분 코드
1. Apple App Store
2. Google Play Store		 Integer Y
hiveiap_receipt_verify_result 마켓 검증 서버에서 전달한 영수증 검증 결과
Object Y
hiveiap_receipt_start_date_ms 구독 시작 시간 (Unix TimeStamp Milliseconds) String Y
hiveiap_receipt_expire_date_ms 구독 만료 시간 (Unix TimeStamp Milliseconds)입니다. 이 값이 변경되었다면, 알림 타입에 상관없이(모든 알림 타입에 대하여) 게임 내에서도 구독 만료 시간 변경을 반영해야 합니다. 예를 들어, 게임 내에서 유저가 보유한 구독형 게임 아이템의 사용 만료 기간을 변경해야 합니다. String Y
hiveiap_receipt_autoresume_date_ms
  • 구독 일시 정지 상태일 경우, 구독 재개 시간(Unix TimeStamp Milliseconds)
  • 일시 정지가 아닐 때는 ""로 전송
String N
hiveiap_receipt_subscription_state 구독 상태입니다.
0. 정상 구독
1. 결제 유예
2. 결제 보류
3. 일시 중지
4. 만료
Integer N
hiveiap_apple_info Apple 구독 영수증 검증 결과에서 구독 영수증을 식별할 수 있는 키 정보를 가진 객체입니다. App Store 구독 영수증일 경우만 해당됩니다. 응답코드가 0(검증 성공)일 때만 값을 전달합니다. Object N
ㄴ original_transaction_id 애플 구독 영수증을 식별 가능한 키입니다. 어떤 Apple Store 계정이 구입한 동일 상품이나 동일 그룹 내 상품을 업그레이드, 다운그레이드, 취소 또는 재구매했을 때에도 이 값은 항상 동일한 값을 반환합니다(16자이며 Apple 가이드에 String 길이에 대한 안내가 없어 변동 가능함). String N
hiveiap_google_info Google 구독 영수증 검증 결과에서 영수증을 식별할 수 있는 키 정보로 응답 Play Store 구독 영수증일 경우만 해당되며, 응답코드가 0(검증 성공)일 때만 값을 전달 Object N
ㄴ purchase_token 영수증의 구매 토큰 200자 이상이며 Google 가이드에 별도 설명이 없어 길이 변동이 가능 String N
ㄴ purchase_token_hash purchase_token 필드 값을 해싱하여 생성한 값 (sha1)
purchase_token 값이 길어 게임에서 DB 저장과 조회에 어려움이 예상되기 때문에 해싱 후 제공 (40자)		 String N
ㄴ linked_purchase_token 업그레이드, 다운그레이드, 구독 취소 또는 인앱에서 재활성화했을 때 구독 영수증이 신규 발행되면 이 필드 값으로 구 영수증의 구매 토큰 식별이 가능
값이 있을 경우 구 영수증을 강제 만료시키도록 권장
200자 이상이며 Google 가이드에 별도 설명이 없어 길이 변동이 가능
(단, Play Store에서 재활성화 했을 때는 신규 발행 없음)		 String N
ㄴ linked_purchase_token_hash linked_purchase_token 필드 값을 해싱하여 생성한 값 (sha1)
linked_purchase_token 값이 길어 게임에서 DB 저장과 조회에 어려움이 예상되기 때문에 해싱 후 제공 (40자)		 String N
hiveiap_iap_payload 게임사에서 정의한 구매 메타 정보입니다. 정의한 메타 정보가 없으면 null을 반환합니다. String Y
hiveiap_receipt_cancel_date_ms 구독 취소 시간(unix timestamp, ms)입니다. 기본값은 0입니다. Integer Y
hiveiap_receipt_refund_date_ms 결제 환불 시간(unix timestamp, ms)입니다. 기본값은 0입니다. Integer Y
Warning

hiveiap_receipt_subscription_states는 현재 Google 구독만 값을 전송합니다. 구독 결제 보류(Account holding) 안내 및 구독 복원 지원 기능이 2020년 11월 1일부터 필수 사항으로 Google 정책이 변경되기 때문에 구독 상태 확인을 목적으로 추가되었습니다.

  • 결제 유예(Grace period): 유저의 결제 상태가 정상화될 때까지 만료 시간 연장 (Google 마켓 콘솔에 설정한 유예 시간 동안 적용)
  • 결제 보류(Account holding): 유저의 결제 상태가 정상화되지 않은 상황에 만료 시간이 지나면서 컨텐츠 권한이 부여되지 않으나, 결제 상태가 정상화된 후 구독을 복원할 때 구독 만료 시간 연장 (최대 30일간 결제 보류 상태 유지)

  • 호출 (Hive IAP > 게임 서버)
curl -L -v
-d '{"notification_type":"SUBSCRIBED","sub_type":"RESUBSCRIBE","hiveiap_market_id":1,"hiveiap_market_pid":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.arshive001","hiveiap_receipt_verify_result":{"status":0,"receipt":{"transactionId":"2000000326618738","originalTransactionId":"2000000287618347","webOrderLineItemId":"2000000026848658","bundleId":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal","productId":"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal.arshive001","subscriptionGroupIdentifier":"20519034","purchaseDate":1683534980000,"originalPurchaseDate":1677492217000,"expiresDate":1683535160000,"quantity":1,"type":"Auto-Renewable Subscription","appAccountToken":"5e657cde-3651-34c0-93fa-1e9cfccfafa2","inAppOwnershipType":"PURCHASED","signedDate":1688470718581,"environment":"Sandbox","transactionReason":"RENEWAL","storefront":"KOR","storefrontId":"143466"}},"hiveiap_receipt_start_date_ms":"1683534980000","hiveiap_receipt_expire_date_ms":"1683535160000","hiveiap_apple_info":{"original_transaction_id":"2000000287618347"},"hiveiap_iap_payload":"{\"server\":\"1\",\"character\":\"1\"}","hiveiap_receipt_cancel_date_ms":0,"hiveiap_receipt_refund_date_ms":0}' \
-H "Content-Type: text/html" \
https://sandbox-misample.com2us.net/hive/Iap_subscription_notification // (게임 서버에서 제공한 API 엔드포인트 예시) 

curl -L -v
-d '{"notification_type":"13","hiveiap_market_id":2,"hiveiap_market_pid":"sub01","hiveiap_receipt_verify_result":{"kind":"androidpublisher#subscriptionPurchaseV2","startTime":"2023-07-25T08:00:19.285Z","regionCode":"KR","subscriptionState":"SUBSCRIPTION_STATE_EXPIRED","latestOrderId":"GPA.3319-2535-4331-99754..0","canceledStateContext":{"userInitiatedCancellation":{"cancelTime":"2023-07-25T08:07:21.881Z"}},"testPurchase":[],"acknowledgementState":"ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED","externalAccountIdentifiers":{"obfuscatedExternalAccountId":"84530982-c9c3-3114-b0dc-848dd7e8bf76"},"lineItems":[{"productId":"sub01","expiryTime":"2023-07-25T08:10:09.583Z","autoRenewingPlan":[],"offerDetails":{"basePlanId":"p1w"}}]},"hiveiap_receipt_start_date_ms":"1690272019000","hiveiap_receipt_expire_date_ms":"1690272609000","hiveiap_receipt_autoresume_date_ms":"","hiveiap_receipt_subscription_state":4,"hiveiap_google_info":{"purchase_token_hash":"5a109e5da69467a706a180fca423e09ab7671389","purchase_token":"eejgienjlbapbnojcnjipdib.AO-J1OxxtNGzvOT7-mSeeAORzZ0GZ90t33v7UQn-t4xPAPGLCQqQAPFmvDK3p3wO8ZwXfYCwmVk9pTI93P8k4IyZJn2XI7ES-EJEFPOLpmUzlXXsOndqbhu1oPRu7V4ddTIUCVB_cHjGKvRnZu1DUu2dEd603grO2Q","linked_purchase_token":"","linked_purchase_token_hash":""},"hiveiap_iap_payload":null,"hiveiap_receipt_cancel_date_ms":1690272441000,"hiveiap_receipt_refund_date_ms":0}' \
-H "Content-Type: text/html" \
https://sandbox-misample.com2us.net/hive/Iap_subscription_notification // (게임 서버에서 제공한 API 엔드포인트 예시)
  • 요청 (Hive IAP > 게임 서버)
> POST /hive/Iap_subscription_notification HTTP/2
> Host: misample.com2us.net // (게임 서버에서 제공한 API 엔드포인트 예시)
> user-agent: curl/7.68.0
> accept: /
> content-type: text/html
> content-length: 1211

> POST /hive/Iap_subscription_notification HTTP/2
> Host: misample.com2us.net // (게임 서버에서 제공한 API 엔드포인트 예시)
> user-agent: curl/7.68.0
> accept: /
> content-type: text/html
> content-length: 1369
  • 응답 명세 (게임 서버 > Hive IAP)
필드명 설명 타입 필수여부
result_code 응답 코드
  • 0: 적용 성공. 게임 서버 에러가 아니면 성공으로 응답
  • 그 외 코드: 적용 실패
Integer Y
result_msg 응답 메시지 String Y
  • 응답 (게임 서버 > Hive IAP)
< HTTP/2 200
 < server: nginx
 < date: Fri, 25 Mar 2022 06:56:17 GMT
 < content-type: application/json; charset=utf-8
 {"result_code":0,"result_msg":"OK"}