コンテンツにスキップ

アイテムと同期

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": "player_id",
    "id": "1004",
    "detail": [
        {
            "action": "p",
            "assetCode": "gem",
            "amount": 1
        }
    ],
    "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 Hiveユーザータイプ(固定値player_idを使用) 文字列 M
id HiveユーザーID(player_id) 文字列 M
detail 以下の3つの項目のオブジェクトの配列 配列 M
ㄴaction 与える/取り消すかどうか
  • sまたはp: 与える
  • wまたはr: 取り消す
文字列 M
ㄴassetCode 与えられるアイテムのコード 文字列 M
ㄴamount 与えられる数量 整数 M
reason リクエストの理由 詳細 文字列 M
subReason リクエストの理由 詳細 文字列 O
serverId 対象ユーザーが接続しているサーバー(サーバー識別子) 文字列 M
additionalinfo クライアントからゲームサーバーに送信される追加情報(すべて小文字)(JSON文字列形式) 文字列 O
duration メールボックスの保持期間(オプション) 詳細
  • 1-9999: 保持日数
  • -1: ゲームサーバーが設定できる最大値
整数 O
userMessage アイテム付与メッセージ(固定メッセージ)
テンプレートメッセージを使用しない古いゲームと互換性があります
文字列 O
templateMessage アイテム付与メッセージのために設定されたメッセージ
データキーは言語コード、値はメッセージ(タイトル)と本文から構成されます
(ただし、データが存在する場合、デフォルト形式はオブジェクトであり、空の場合は空の文字列として送信されます)
オブジェクト O
gameIndex 各Hiveアプリセンターゲームのシリアル番号 整数 M

取引ID

  • リクエストがすでにtransactionIdによって処理されたかどうかを識別します。(重複支払い/徴収の防止)
  • 重複リクエストの場合、レスポンス値は関連する詳細を指定します。(レスポンス仕様を参照)

理由

Note

この理由フィールドの詳細は後で追加または変更される可能性があるため、このリクエストの理由は参考目的のみに使用するべきです。

フィールド名 説明
pe 支払いエラー
rge 報酬ゲームエラー
rcd 報酬消費者不満
rce 報酬クーポンエラー
ro 報酬海外
ae 資産交換
e イベント
ea イベント自動
mc 大量クーポン
uc ユニーククーポン
b 請求 * HIVE IAP v2
lb Lebi 請求
co Cpi オファーウォール
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: ゲーム中に指定された目標を達成することで報酬が与えられます。詳細については、プロモーション運営ガイドを確認してください。

期間

  • リクエストされたアイテムが発行された後、メールボックスに保存される期間は、バックオフィスで各アイテムごとに個別に設定できます。
  • ゲームサーバーは、状況に応じて3つのケースで処理します。
    • キーが存在しない場合: ゲームサーバーによって設定されたデフォルト値が使用されます。(例: デフォルトは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":"player_id","id":"828292","detail":[{"action":"p","assetCode":"gold","amount":500},{"action":"p","assetCode":"gem","amount":200}],"reason":"td","subReason":"","userMessage":"","templateMessage":{"ko":{"title":"\ud55c\uae00 \uba54\uc138\uc9c0","body":"\ud55c\uae00 \ub0b4\uc6a9"},"en":{"title":"English Message","body":"English Contents"}},"serverId":"GLOBAL","additionalinfo":"{\"character\":1}","gameIndex":539}' 
-H "Content-Type: text/html" 
-H "Apihash: 54e7a0fc8abfdba398e30213496c2d85ec6e0e06" 
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: 54e7a0fc8abfdba398e30213496c2d85ec6e0e06
> 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'        => 'player_id',
    '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": "player_id",
    "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 &amp; 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文字列形式です。