IAP v4 通知实时订阅

透過即時訂閱通知，遊戲伺服器能夠即時接收來自 Hive IAP 伺服器的用戶訂閱狀態信息。用戶可以利用這些信息實現訂閱暫停、保留和暫停功能。

Warning

要使用即時訂閱通知功能，您必須在市場控制台中設置通知 URL。

即時訂閱通知 API 的運作方式是由 Hive IAP 伺服器向遊戲伺服器發出呼叫，並在請求主體中包含訂閱狀態變更資訊，並實時傳輸。由於遊戲伺服器接收訂閱狀態變更資訊，因此必須向 Hive 提供 API 端點 (URL)。

API URL 可以在 the Hive 控制台 > App Center > Game List > Game details > Game server > Market 伺服器通知 URL 中註冊。如果遊戲伺服器按區域劃分，且每個區域都應接收通知，請逐一提供 URL。然後，IAP 會向所有遊戲伺服器發送通知。

IAP 將即時訂閱狀態從 Hive 伺服器發送到遊戲伺服器。因此，請確保遊戲伺服器開啟以下伺服器 IP 的入站防火牆以接收通知。

43.202.181.138
3.38.239.17

請求規範 ( IAP > 遊戲伺服器)

欄位名稱	描述	類型	必填
notification_type	通知類型 Apple Google: 訂閱在寬限期/暫停/掛起的狀態基於 `hiveiap_receipt_subscription_state` 的值。請使用此欄位作為參考數據。	字串	Y
sub_type	通知的子類型。僅適用於 Apple 通知子類型資訊。	字串	N
hiveiap_market_id	付費市場代碼 Apple App Store Google Play Store	整數	Y
hiveiap_receipt_verify_result	從市場驗證伺服器發送的收據的驗證結果 Apple 收據驗證結果指南 (Storekit 1, iOS 15 之前) Apple 收據驗證結果指南 (Storekit 2, iOS 15 或更高版本) Google 訂閱 V1 驗證結果指南 Google 訂閱 V2 驗證結果指南	物件	Y
hiveiap_receipt_start_date_ms	訂閱的開始時間 (Unix 時間戳毫秒)	字串	Y
hiveiap_receipt_expire_date_ms	訂閱的結束時間 (Unix 時間戳毫秒) 如果此值已更改，您需要在您的遊戲中應用此值以適用於所有通知類型。例如，您需要更改用戶遊戲項目的訂閱到期日期。	字串	Y
hiveiap_receipt_autoresume_date_ms	如果訂閱被暫停，則為訂閱恢復的時間 (Unix 時間戳毫秒) 如果訂閱未被暫停，則接收到“”	字串	N
hiveiap_receipt_subscription_state	訂閱狀態活動在寬限期內掛起暫停已過期目前僅可發送 Google 訂閱數據。根據修訂的 Google 政策，自 2020 年 11 月 1 日起，帳戶保留和恢復功能至關重要。此 API 檢查訂閱狀態。寬限期：它將到期時間延長，直到用戶的付款狀態恢復正常（僅適用於在 Google Play 控制台上設置的寬限期）。帳戶保留：由於付款存在問題以及到期時間結束，未授予使用內容的許可，但在付款狀態恢復正常後，延長訂閱到期時間（保持保留狀態最多 30 天）。	整數	N
hiveiap_apple_info	此物件具有識別 Apple 訂閱收據的金鑰值，僅用於 App Store 訂閱收據。僅在響應代碼為 0（驗證成功）時提供。	物件	N
ㄴ original_transaction_id	這是識別 Apple 訂閱收據的金鑰值。對於 App Store 帳戶，對於相同產品的購買，或在同一組內升級、降級、重新購買或取消購買的產品，此值保持不變（允許 16 個字符，但由於沒有具體的字符串長度指南，可能會有所不同）。	字符串	N
hiveiap_google_info	識別 Google 訂閱收據驗證結果中的收據的金鑰值僅限 Play Store 的訂閱收據。僅在響應代碼為 0（驗證成功）時發送該值。	物件	N
ㄴ purchase_token	收據中的購買令牌。令牌值需要 200 個字符及以上，並且由於 Google 指南沒有限制，長度可以變更。	字符串	N
ㄴ purchase_token_hash	它是通過對 `purchase_token` 字段的值進行哈希生成的（sha1）。由於 `purchase_token` 值的長度較長，它會處理哈希以便於從數據庫中搜索和保存（40 個字符）。	字符串	N
ㄴ linked_purchase_token	如果在升級、降級、取消或重新啟用後新發行訂閱收據，則此字段的值可以識別舊收據中的購買令牌。如果有值，建議強制過期。令牌值需要 200 個字符及以上，並且由於 Google 指南沒有限制，長度可以變更。（但是，在 Play Store 重新啟用的情況下不會有新的發行）	字符串	N
ㄴ linked_purchase_token_hash	它是通過對 `linked_purchase_token` 字段的值進行哈希生成的（sha1）。由於 `linked_purchase_token` 值的長度較長，它會處理哈希以便於從數據庫中搜索和保存（40 個字符）。	字符串	N
hiveiap_iap_payload	這是遊戲公司定義的購買元信息。如果沒有定義元信息，則返回 `null`。	字串	是
hiveiap_receipt_cancel_date_ms	這是訂閱被取消的時間（unix 時間戳，毫秒）。預設值為 0。	整數	是
hiveiap_receipt_refund_date_ms	這是購買退款發生的時間（unix 時間戳，毫秒）。默認值為 0。	整數	是

呼叫 ( IAP > 遊戲伺服器)

蘋果應用商店Google Play 商店

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 // (the API endpoint example provided from your game server)

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" \ (the API endpoint example provided from your game server)

請求 ( IAP > 遊戲伺服器)

蘋果應用程式商店Google Play 商店

> 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

回應規範 (遊戲伺服器 > IAP)

欄位名稱	描述	類型	是否必填
result_code	回應代碼 0: 應用成功。除非遊戲伺服器錯誤，否則回應為成功其他代碼: 應用失敗	整數	Y
result_msg	回應訊息	字串	Y

回應 (遊戲伺服器 > 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"}</pre>