コンテンツにスキップ

アイテムと同期

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 \uc9c0\uae09 \uba54\uc138\uc9c0 QA \ud55c\uad6d",
            "body": "HIVE Item \uc9c0\uae09 \uba54\uc138\uc9c0 QA \ud55c\uad6d\uc5b4 \ub178\ucd9c"
        }
    },
    "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
platformInfo アイテムの付与および回収時にアプリが参照する追加情報です。JSON文字列形式のため、以下の項目を使用するにはアプリサーバーでJSONとしてパースする必要があります。 文字列 O
ㄴcoupon_number アイテム付与時に使用されたクーポン番号(Hive コンソール > 請求 > クーポン > クーポン発行で確認) 文字列 O
ㄴcoupon_pno アイテム付与時に使用されたクーポンのプロモーション番号(Hive コンソール > 請求 > クーポン > クーポン発行で確認)
プロモーション番号:報酬、有効期限、利用方法など同一の運用ポリシーを共有するクーポンを1つにまとめて管理する単位
文字列 O

取引ID

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

理由

Note

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

フィールド名 説明
pe 支払いエラー
rge 報酬ゲームエラー
rcd 報酬消費者不満
rce 報酬クーポンエラー
ro 報酬海外
ae 資産交換
e イベント
ea イベント自動
mc 大量クーポン
uc ユニーククーポン
b 請求 * HIVE IAP v2
lb Lebi 請求
p プロモーション * UA
sr ストリーミング報酬
tcs テスト CS
tgm テスト GM
tpm テスト PM
tqa テスト QA
td テスト開発者
tg テスト市場、ビジネス
tmb テスト海外 (テスト開発者)
re 取得 その他
rr 取得 返金
mr 大量リクエスト
etc その他

サブ理由

理由 サブ理由 説明
p プロモーションサブリクエストの詳細
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, "platformInfo":"{\"coupon_number\":\"123D3EVA\",\"coupon_pno\":\"2030\"}"}' 
-H "Content-Type: text/html" 
-H "Apihash: 257fa2cdb6daa8a0a35583dd96fa90a4381280ff" 
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: 257fa2cdb6daa8a0a35583dd96fa90a4381280ff
> 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,
    'platformInfo'      => '{"coupon_number":"123D3EVA","coupon_pno":"2030"}'
);
$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文字列形式です。