Sending consumption information

An API is provided to transmit user consumption information to the app store when an app user requests a refund.

The 'Consumption Information Transmission' API uses a Server-to-Server communication method between the Hive Server and the app server. When the Hive Server sends a consumption information transmission request to the app server, the app server returns the response value to the Hive Server.

V1 → V2 changes¶

This is a summary of the changes when integrating with the V2 API, compared to the existing Consumption Information Transmission V1.

Operation flow¶

The following summarizes the overall operation flow of the 'Consumption Information Transmission' API call and response.

1. App: Prepare the server URL by configuring the API endpoint
2. App: Select Enable Consumption Information Transmission in the Hive console, and register the server URL
3. App client: While the app is running, agree to transmit in-app product consumption information
4. App user: Request a refund in the app
5. Hive server: Send a POST API request to the server URL registered by the app, and receive consumption information data as the response value from the app server
6. Hive server: Transmit consumption information to the app store

Some of the consumption information to be transmitted to the app store exists only on the app server. In this case, for the Hive server to transmit the consumption information to the app store, the app server must first pass the data to the Hive server.

The app server URL is the API endpoint opened by the app server for the app server to pass data to the Hive server. After configuring the API endpoint and registering it as the app server URL, the Hive server sends a POST request to this API endpoint each time a user requests a refund, and receives the necessary data from the app server. The Hive server aggregates this data and completes the transmission of consumption information to the app store on behalf of the app.

API endpoint (server URL) configuration¶

When the app server receives a request at the API endpoint registered as the server URL, it must aggregate app user-specific data (consumption_status, play_time, refund_preference, sample_content_provided) and respond with the aggregated data that can be looked up using the user information (CS_CODE) in the request parameters.

Disable firewall rules¶

Disabling the firewall inbound rules allows API communication between the app server and the Hive server. You must disable the firewall inbound rules for the IP addresses below on the app server.

After disabling the firewall rules, refer to the information below to configure the API endpoint.

API request (Hive server → app server) configuration¶

This is the POST request information sent from the Hive server to the app server.

Request body¶

The request body information is as follows.

The following is an example of the request body.

{
    "gameindex": "539",
    "appid": "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal",
    "user_seq": "222333"
}

API response (app server → Hive server) configuration¶

This is the information returned from the app server to the Hive server.

Response body¶

This is the response value information that the app server must pass to the Hive server when the response is successful.

The following is an example of a successful response.

// success
{
    "code": 100,
    "message": "OK",
    "data": {
        "consumption_status": 0,
        "play_time": 1,
        "refund_preference": 2,
        "sample_content_provided": 0
    }
}

The following is an example of a failed response.

// Errors due to wrong parameters
{
    "code": 400,
    "message": "No parameter, or invalid parameter name."
}

// Errors due to invalid user information
{
    "code": 200,
    "message": "No data, or invalid cs_code."
}

Response codes¶