アイテムと同期
Hive アイテムは、ゲーム内通貨やアイテムの支払い/取得機能を管理するために提供されるシステムです。Hive アイテムの統合は、クーポンシステム、イベント、オファーウォール、CPIなどと連携してアイテムを与えたり取得したりする機能を提供します。管理者のバックオフィスでは、アイテムを手動で与えたり取得したりすることができ、履歴を検索することもできます。
Note
- アイテム付与/回復リクエストAPIは非同期方式で動作し、APIリクエスト時にリクエスト情報の登録の成功または失敗を判断することでのみ応答します。
- ゲームサーバーAPI呼び出しなどの_実際の処理アクション_への応答は、Hiveコンソールメニューの請求 > Hive アイテム > 付与/回復リクエストまたは付与/回復成功ログで関連コンテンツを検索し、検索結果ポップアップウィンドウのステータス項目をクリックすることで確認できます。
- Hive アイテムは大規模なトラフィックの処理が必要なため、開発者のアプリサーバーの平均応答時間が0.5秒を超える場合、メインキューではなく別のキューで動作する可能性があります。この場合、アイテム付与処理において重大な遅延が発生する可能性があります。スムーズなアイテム付与処理を確保するために、開発者のアプリサーバーの平均応答時間を0.5秒未満に保つことをお勧めします。
統合準備要件¶
Hive アイテムと統合するには、まずゲームサーバーのURLとアイテムをHiveアイテム管理メニューに登録する必要があります。
支払い/回復リクエストAPI¶
支払い/返金リクエストAPIの基本を確認する¶
API通信方法¶
- 補助金/回復リクエストAPIは、HTTP通信とソケットベースのJSON文字列通信の2種類の通信を提供します。
- ゲームサーバーからHiveアイテムに対して、JSON文字列形式で補助金または回復をリクエストします。
- ゲームサーバーは、Hiveアイテムに対してJSON文字列形式で結果を返します。
- 応答結果には処理コードとメッセージが含まれます。
- すべてのJSON文字列はUTF8でエンコードされている必要があります。
ゲームの適用方法¶
- サービスが開始される前は、テストサーバーを使用して統合テスト結果を送信し、サービスが開始された後は、本番サーバーを使用します。
- ゲームがすでにサービス中であっても、テストサーバーと統合する必要があります。
- すべてのアイテムはメールボックスを通じて提供されます。
- メールボックス内でユーザーに表示するメッセージが必要な場合は、リクエスト仕様 > リクエスト理由を参照してください。ゲームサーバーは各言語に応じて表示メッセージを処理する必要があります。
- アイテムリクエストはユーザーごとに1件送信されます。アイテムの付与/取得に関する複数のリクエストを同時に送信できますが、単一のリクエストは1つのトランザクション内で処理されなければなりません。1つのアイテムの付与/取得が失敗した場合は、完全なロールバックの後に失敗として応答するように実装してください。
ゲームサーバーファイアウォールリリース¶
サーバーと通信するには、ゲームサーバー上の以下のIPに対する受信ファイアウォールルールを無効にする必要があります。
- 52.79.76.25
- 3.37.22.75
- 43.133.238.219 (サンドボックスサーバー)
ゲームサーバーのヘルスチェック¶
Hive アイテムは、ゲームサーバーのステータスを確認するために、付与/取り消しリクエストAPIに次の詳細を送信します。Hive アイテムサーバーは、リクエストボディ内で5分間隔で2回ゲームサーバーにこれを送信します。
{"transactionId":"","idCategory":"","id":"","detail":[{"action":"","assetCode":"","amount":0}],"reason":""}
上記のコンテンツを受信するゲームサーバーは、検証エラーに遭遇する可能性があり、この場合、応答値のコードおよびメッセージフィールドにエラー情報を返す必要があります。Hive アイテムは、コード値を単独で決定するものではありません。コードおよびメッセージフィールドが存在する場合、ゲームサーバーは正常と見なされます; それらが存在しない場合、ゲームサーバーは異常状態にあると見なされます。
Apihash値の検証¶
ゲームサーバーは、ヘッダー内のApihash値を通じて、Hiveアイテムサーバーから受信したデータを検証できます。ハッシュ値を検証する前に、Hiveアイテムサーバーから受信したリクエストボディデータをJSONエンコードまたはユニコードに変換することが不可欠です。(例のコードを参照してください)
 リクエスト仕様のプレフィックスと変換されたJSON文字列値(プレフィックス + JSON文字列)を混ぜることによって、SHA1形式のハッシュ値が生成され、この値が検証のためにApihash値と比較されます。
- 例のコード
    // Example of a transformed JSON String (add a line and spaces for readability)
 {
    "transactionId": "123456789",
    "idCategory": "vid",
    "id": "1004",
    "detail": [
        {
            "action": "p",
            "assetCode": "gem",
            "amount": 1,
            "method": ""
        }
    ],
    "reason": "td",
    "subReason": "",
    "userMessage": "",
    "templateMessage": {
        "ko": {
            "title": "HIVE Item uc9c0uae09 uba54uc138uc9c0 QA ud55cuad6d",
            "body": "HIVE Item uc9c0uae09 uba54uc138uc9c0 QA ud55cuad6duc5b4 ub178ucd9c"
        }
    },
    "serverId": "kr",
    "additionalinfo": "",
    "gameIndex": 539
}
HTTP通信方法のための支払い/返金リクエストAPI¶
支払い/取得リクエストAPIは、Hive コンソール > 請求 > アイテム > アイテム登録メニューに設定されたゲームサーバー(URL)とHTTPプロトコルを介して通信し、リクエストデータの送信方法はPOSTです。
リクエスト仕様 (ハイブアイテム -> ゲームサーバー)¶
HTTP ヘッダー : Apihash
- データを検証するには、ハッシュ値をキーApihashと共に送信してください。
- ハッシュ値にはSHA1を使用します。(ボディJSON文字列にプレフィックス!@#COM2US!@#を追加してください)
リクエストボディ (Hive アイテム -> ゲームサーバー)
| フィールド名 | 説明 | タイプ | 必須 (必須: M, 任意: O) | 
|---|---|---|---|
| transactionId | 各リクエストを区別するための識別子(重複リクエストの検証用) 詳細 | 文字列 | M | 
| idCategory | ID 
 | 文字列 | M | 
| id__ITALICS_MD_0__ リクエストがすでにtransactionIdによって処理されたかどうかを識別します。(重複支払い/徴収の防止) | |||
| 重複リクエストの場合、レスポンス値は関連する詳細を指定します。(レスポンス仕様を参照) | 
理由¶
Note
このリクエストの理由は、後で詳細が追加または変更される可能性があるため、参照目的のみに使用するべきです。
| フィールド名 | 説明 | 
|---|---|
| pe__ITALICS_MD_1__ro__ITALICS_MD_2__ae__ITALICS_MD_3__e__ITALICS_MD_4__ea__ITALICS_MD_5__mc__ITALICS_MD_6__uc__ITALICS_MD_7__b | 請求 * HIVE IAP v2 | 
| lb__ITALICS_MD_8__co__ITALICS_MD_9__p | プロモーション * クロスバナー、オファーウォール、UAで同じものを使用 | 
| *sr | ストリーミングリワード | 
| tcs | テストCS | 
| tgm | テストGM | 
| tpm | テストPM | 
| tqa | テストQA | 
| td | テスト開発者 | 
| tg | テスト市場、ビジネス | 
| tmb | テスト海外(テスト開発者) | 
| re | 取得等 | 
| rr | 取得返金 | 
| mr | 大量リクエスト | 
| etc | その他 | 
サブ理由¶
| 理由 | サブ理由 | 説明 | 
|---|---|---|
| p | プロモーションのサブリクエストの詳細 | |
| 1 | クロス一般バナーCPI | |
| 2 | クロス一般バナーCPA | |
| 3 | クロスフロントバナーCPI | |
| 4 | クロスフロントバナーCPA | |
| 5 | オファーウォール一般CPI | |
| 6 | オファーウォール一般CPA | |
| 7 | オファーウォール特別CPI | |
| 8 | オファーウォール特別CPA | |
| 9 | UA CPI | |
| 10 | UA CPA | |
| 11 | UC CPI | 
プロモーション機能の分類
クロスプロモーション: ユーザーは、現在プレイ中のゲーム内でバナーやオファーウォール(無料充電ステーション)の形で他のゲームを宣伝できます。通常のバナーと全画面バナーに分かれています。 * オファーウォール: オファーウォールは、ユーザーのデバイスにインストールされていないゲームのリストをバナーの形で表示します。ユーザーはバナーをタッチして接続されたマーケットからゲームをインストールすると報酬を受け取ります。通常のオファーウォールと特別なオファーウォールに分かれています。 * UA/UC: ソーシャルメディアとQRコードを利用したゲーム招待機能です。UAは招待するユーザーと受け取るユーザーの両方を含み、UCは受け取るユーザーのみを含みます。UCは事前登録に利用できます。
報酬方法
- CPI: インストール後にゲームを起動した後に報酬が与えられます。
- CPA: ゲーム中に指定された目標を達成することで報酬が与えられます。詳細については、プロモーション運用ガイドをご確認ください。
期間¶
- 要求されたアイテムが発行された後、メールボックスに保存される期間は、バックオフィスで各アイテムごとに個別に設定できます。
- ゲームサーバーは、状況に応じて三つのケースで処理します。- キーが存在しない場合: ゲームサーバーによって設定されたデフォルト値が使用されます。 (例: デフォルトは7日間の保存)
- 1~9999: 指定された数値が日数として使用されます。 (例: 値が14の場合、14日間の保存を意味します)
- -1: ゲームサーバーによって設定できる最大値が使用されます。 (例: 永久保存)
 
応答仕様 (ゲームサーバー -> ハイブアイテム)¶
レスポンス (ゲームサーバー -> Hive アイテム)
| フィールド名 | 説明 | タイプ | 必須 (必須: M, オプション: O) | 
|---|---|---|---|
| code | 処理結果コード 詳細 | 整数 | M | 
| message | 処理結果メッセージ | 文字列 | M | 
- エラーコード
| コード値 | 説明 | 
|---|---|
| 2xxxx | リクエストに問題なし。処理成功 | 
| ㄴ 20000 | リクエストに問題なし。処理成功 | 
| ㄴ 20001 | リクエストに問題なし。 すでに正常に処理されました(重複リクエスト) 通常処理されたtransactionIdがすでに存在する場合 | 
| 4xxxx | リクエストパラメータエラー | 
| ㄴ 40001 | リクエストJSONエラー | 
| ㄴ 40002 | ハッシュエラー | 
| ㄴ 40003 | 必須パラメータキーが欠落しています | 
| ㄴ 40004 | 必須パラメータキーのタイプエラー | 
| ㄴ 40005 | 必須パラメータ値が空です | 
| ㄴ 40006 | 無効な必須パラメータ値(例:負の値) | 
| 5xxxx | サーバー処理エラー | 
| ㄴ 50001 | 存在しないユーザー | 
| ㄴ 50004 | DB登録エラー | 
| ㄴ 50005 | パラメータエラー(例:存在しないアイテムコード) | 
- リクエストサンプル
curl -L -v 
-d '{"transactionId":"27905","idCategory":"vid","id":"828292","detail":[{"action":"p","assetCode":"gold","amount":500,"method":""},{"action":"p","assetCode":"gem","amount":200,"method":""}],"reason":"td","subReason":"","userMessage":"","templateMessage":{"ko":{"title":"ud55cuae00 uba54uc138uc9c0","body":"ud55cuae00 ub0b4uc6a9"},"en":{"title":"English Message","body":"English Contents"}},"serverId":"kr","additionalinfo":"","gameIndex":539}' 
-H "Content-Type: text/html" 
-H "Apihash: e9d7307948ff0134fb59c5f96e68f5ae21e3e47f" 
https://sandbox-misample.com2us.net/hive/item
- リクエストサンプル
> POST /hive/item HTTP/2
> Host: sandbox-misample.com2us.net
> user-agent: curl/7.68.0
> accept: */*
> content-type: text/html
> apihash: e9d7307948ff0134fb59c5f96e68f5ae21e3e47f
> content-length: 447
- レスポンスサンプル
< HTTP/2 200
< server: nginx
< date: Tue, 12 Jul 2022 11:29:21 GMT
< content-type: application/json; charset=utf-8
<
* Connection #0 to host sandbox-misample.com2us.net left intact
{"status":"200","code":"20001","message":"this request has already been processed"}
リクエストサンプル(PHP)
    // data request
$data = array(
    'transactionId'     => '12321',
    'idCategory'        => 'vid',
    'id'                => '828292',
    'detail'            => array(
        array(
            'action'    => 's',
            'assetCode' => 'gold',
            'amount'    => 500,
        ),
        array(
            'action'    => 's',
            'assetCode' => 'gem',
            'amount'    => 200,
        ),
    ),
    'reason'            => 'p',
    'subReason'         => '3',
    'userMessage'       => '',
    'templateMessage'   => array(
        'ko' => array(
            'title' => '한글 메세지',
            'body'  => '한글 내용'
        ),
        'en' => array(
            'title' => 'English Message',
            'body'  => 'English Contents'
        ),
    ),
    'serverId'          => 'GLOBAL',
    'additionalinfo'    => '{"character":1}',
    'gameIndex'         => 539
);
$jsonData = json_encode($data); // convert to JSON
/******************************************************************** 
    Conversion result (add a line and spaces for readability) :
{
    "transactionId": "12321",
    "idCategory": "vid",
    "id": "828292",
    "detail": [
        {
            "action": "s",
            "assetCode": "gold",
            "amount": 500
        },
        {
            "action": "s",
            "assetCode": "gem",
            "amount": 200
        }
    ],
    "reason": "p",
    "subReason": "3",
    "userMessage": "",
    "templateMessage": {
        "ko": {
            "title": "한글 메세지",
            "body": "한글 내용"
        },
        "en": {
            "title": "English Message",
            "body": "English Contents"
        }
    },
    "serverId": "GLOBAL",
    "additionalinfo": "{"character":1}",
    "gameIndex": 539
}
********************************************************************/
// set header as application/json & set hash 
$hash = sha1('!@#COM2US!@#' . $jsonData); 
$header = array(
    'Content-type: application/json',
    'Apihash: ' . $hash
);
$url = 'http://game.com2us.com/gms.php'; // game server url
$curl = curl_init();
curl_setopt($curl, CURLOPT_HTTPHEADER, $header); 
curl_setopt($curl, CURLOPT_URL, $url); 
curl_setopt($curl, CURLOPT_POST, true); 
curl_setopt($curl, CURLOPT_POSTFIELDS, $jsonData); 
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); 
$result = curl_exec( $curl );
curl_close( $curl );
// process the result data
$response = json_decode($result);
レスポンスサンプル (PHP)
// php header declaration
header('Content-type: application/json');
// json Data
$rawData = file_get_contents('php://input');
//confirm Hash value
$hash = sha1('!@#COM2US!@#' . $rawData);
$requestHash = $_SERVER['Apihash'];
if ($requestHash != $hash) {
/*****************************************************************
Process if the hash value differs (optional to use hash)
*****************************************************************/
}
// Decode requested JSON data 
$requestData = json_decode($rawData, TRUE);
foreach ($requestData['detail'] as $item) {
/*****************************************************************
Process the asset as requested
*****************************************************************/
}
$returnData = array(
'code' => 50001,
'message' => 'user not exists',
);
//To avoid adding UTF-8BOM
ob_clean()
//Convert to JSON and send the response
echo json_encode($returnData);
/*****************************************************************
Conversion result (insert a line) :
{
"code" : 50001,
"message" : "user not exists"
}
*****************************************************************/
支払い/返金リクエストAPIのためのソケット通信方法¶
ソケットを使用した支払い/取得リクエストAPIは、パケットデータ通信のためのプロトコルであるTCP/IP上で動作し、デフォルトポートは20080です。データはHTTP通信中と同じJSON形式であり、バイトオーダーはネットワークバイトオーダー(ビッグエンディアン)です。
リクエストパケット仕様 (ハイブアイテム -> ゲームサーバー)¶
| パケットサイズ | 4 バイト | 4 バイト | 可変 | 4 バイト | 可変 | 
|---|---|---|---|---|---|
| 説明 | パケットの総長 | ヘッダーの長さ | ヘッダーの内容 | 本体の長さ | 本体の内容 | 
- 最初の4バイトは、これらの4バイトを含むパケットの総長を示します。 
 例えば、ヘッダーが46バイトでボディが100バイトの場合、4+4+46+4+100 = 158バイトになります。
- 次の4バイトは、その後に続くヘッダーの長さを示します。
- ヘッダーは、HTTP通信におけるハッシュ値と同じJSON文字列形式です。 
 例えば、{"Apihash":"912ec803b2ce49e4a541068d495ab570"}
- 最後の4バイトは、その後に続くボディの長さを示します。
- ボディは、HTTP通信におけるリクエスト値と同じJSON文字列形式です。
レスポンスパケット仕様 (ゲームサーバー -> ハイブアイテム)¶
| パケットサイズ | 4 バイト | 可変 | 
|---|---|---|
| 内容 | パケットの総長 | 本体 | 
- 最初の4バイトは、これらの4バイトを含むパケット全体の長さを指定します。
- ボディは、HTTP通信におけるレスポンス値と同じJSON文字列形式です。