Send consumption information v2

アプリユーザーが返金をリクエストする際に、ユーザーの消費情報をアプリストアに送信するAPIを提供します。

「消費情報伝送」APIは、HiveサーバーとアプリサーバーとのServer-to-Server通信方式で、Hiveサーバーがアプリサーバーに消費情報伝送リクエストを送信すると、アプリサーバーが応答値をHiveサーバーに返します。

動作フロー¶

「消費情報伝送」APIの呼び出しおよび応答の全体的な動作フローをまとめると、以下の通りです。

1. アプリ: APIエンドポイントを構成してサーバーURLを準備
2. アプリ: Hive コンソールで消費情報伝送の使用を選択し、サーバーURLを登録
3. アプリクライアント: アプリを実行した状態でアプリ内商品の消費情報伝送に同意
4. アプリユーザー: アプリで返金をリクエスト
5. Apple: Hive サーバーに消費情報リクエスト(CONSUMPTION_REQUEST)を送信
6. Hive サーバー: アプリで登録したサーバーURLにPOST APIリクエストを送信し、アプリサーバーから応答値として消費情報データを受信
7. Hive サーバー: アプリストアに消費情報を送信(成功時、AppleがHTTP 202で応答)

アプリストアに送信する消費情報の中には、アプリサーバーにのみ存在するデータもあります。この場合、Hive サーバーが消費情報をアプリストアに送信するには、アプリサーバーが先にHive サーバーにデータを渡す必要があります。

アプリサーバーURLは、アプリサーバーがHive サーバーにデータを渡すために、アプリサーバー側で開放しているAPIエンドポイントです。APIエンドポイントを構成した後、アプリサーバーURLとして登録すると、ユーザーが返金をリクエストするたびにHive サーバーがこのAPIエンドポイントにPOSTリクエストを行い、必要なデータをアプリサーバーから受け取ります。Hive サーバーはこれらのデータを集約し、アプリに代わってアプリストアへの消費情報伝送を完了します。

APIエンドポイントの構成(サーバーURL)¶

アプリサーバーは、サーバーURLとして登録するAPIエンドポイントでリクエストを受信した際、リクエストパラメータのユーザー情報(player_id)と取引情報(transaction_id)を使用して消費情報を照会し、応答規約に沿ったデータを返す必要があります。

ファイアウォールルールの解除¶

Hive サーバーがアプリサーバーのAPIエンドポイントにリクエストを送信できるように、アプリサーバー側で以下のIPアドレスに対するファイアウォールのインバウンドルールを解除する必要があります。

ファイアウォールルールを解除した後、以下の内容を参考にAPIエンドポイントを構成します。

APIリクエスト(Hive サーバー → アプリサーバー)の構成¶

Hive サーバーからアプリサーバーに送信するPOSTリクエスト情報です。

Request body¶

リクエスト本文の情報は以下の通りです。

リクエスト本文の例は以下の通りです。

{
    "gameindex": 539,
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "server_id": "server_01",
    "player_id": "222333",
    "transaction_id": "2000000123456789"
}

API応答(アプリサーバー → Hive サーバー)の構成¶

アプリサーバーは、処理結果コード(code)、結果メッセージ(message)、消費情報(data)をHive サーバーに渡します。

Response body¶

Hive サーバーはcodeの値で成功可否を判定します。200の場合は成功と見なしてdataを使用し、それ以外のコードの場合は該当の件を送信せず、messageを理由として記録します。codeは必須であり、送信されない場合はエラーとして処理し、該当の件を送信しません。

応答成功の例は以下の通りです。

{
    "code": 200,
    "message": "OK",
    "data": {
        "delivery_status": "DELIVERED",
        "refund_preference": "GRANT_FULL",
        "consumption_percentage": 100000,
        "sample_content_provided": 0
    }
}

応答コード¶

配送状態(delivery_status)¶

消耗品の配送状態を表し、以下の5つの値のいずれかである必要があります(必須)。

返金の好み(refund_preference)¶

アプリが希望する返金処理の方向をAppleに伝えます(任意)。値を送信する場合は、以下の3つのいずれかである必要があります。