コンテンツにスキップ

アイテムと同期

アイテムは、ゲーム内のゲームマネーとアイテムの配信および取得機能を統合し管理するシステムです。アイテムを使用することで、クーポンシステム、イベント、オファーウォール、CPIなどの多様なシステムと接続し、アイテムを送信または取得することができます。また、管理者用のバックオフィスがあり、アイテムの送信および取得の履歴を手動で検索することができます。

Note
  • **アイテムの配信/取得のためのAPIリクエスト**は非同期であり、リクエスト情報の登録の成功または失敗に応じてAPIリクエストに応答します。
  • 実際のプロセスへの応答を確認することができます。これは、**配信/取得アイテムリクエストまたは配信/取得アイテム成功ログ**ページの検索結果から**ステータス**アイコンをクリックすると表示される詳細ページから、ゲームサーバーAPIを呼び出すことによって行われます。コンソール > 請求 > アイテム > 配信/取得アイテムリクエストまたは配信/取得アイテム成功ログに移動してください。

接続の準備

ゲームサーバーのURLとアイテムをアイテム管理メニューに登録して、同期することを確認してください。

アイテムを配信/取得するためのAPI

アイテムの配信/取得のためのリクエストAPIの基本を確認する

API通信方法

  • リクエスト API はアイテムの配信/取得のために、HTTP タイプとJSON 文字列タイプの2種類の通信を提供します。
  • アイテムはゲームサーバーにJSON 文字列を送信して、アイテムの送信または取得をリクエストします。
  • ゲームサーバーは アイテムに対して、JSON 文字列で結果を返します。
  • レスポンスの結果にはプロセスコードとメッセージが含まれます。
  • JSON 文字列はUTF8 にエンコードされるべきです。

ゲームの適用方法

  • サービス開始前に、テストサーバーで接続をテストしてください。サービスを開始した後、共通サーバーに配信します。
  • サービス中はテストサーバーに接続しておく必要があります。
  • アイテムは基本的にギフトボックスを通じて送信されます。
  • ユーザーがギフトボックスで見るためのアイテム送信説明のテキストが必要な場合は、リクエストボディ > 理由を参照してください。ゲームサーバーは言語ごとに説明テキストを処理する必要があります。
  • アイテムリクエストはユーザーによって一つずつ送信されます。一度に複数のアイテムの配信/取得を送信することができますが、一つのトランザクション内で一つのリクエストを処理することを確認してください。配信/取得アイテムの一つが失敗した場合は、全体のリクエストをロールバックし、失敗に応じて応答するように実装してください。

ゲームサーバーファイアウォールを無効にする

    ゲームサーバーとの通信のために、以下のIPの受信ファイアウォールルールを無効にする必要があります。
    • 52.79.76.25
    • 3.37.22.75
    • 43.202.181.123 (サンドボックスサーバー)

ゲームサーバーの健康状態の監視

アイテムは、Request Body に以下のフィールドを送信します( アイテムからゲームサーバーへ)Request API で、アイテムを5分ごとに2回配信/取得します。これにより、 アイテムはゲームサーバーの健康状態を監視できます。

{"transactionId":"","idCategory":"","id":"","detail":[{"action":"","assetCode":"","amount":0}],"reason":""}

リクエストボディフィールドを受け取った後、ゲームサーバーで検証エラーが発生する可能性があります。この場合、エラーデータでレスポンス値のコードとメッセージフィールドを埋め、アイテムに応答します。アイテムは、コードとメッセージフィールドが存在する場合、ゲームサーバーが正常であることを認識します。レスポンスに2つのフィールドがない場合、ゲームサーバーは異常と見なされます。

apihash 値の検証

あなたのゲームのサーバーは、アイテムサーバーが送信したデータをApihash値のHeaderを使用して検証することができます。ハッシュ値を検証する前に、リクエストボディデータをJSON エンコードまたはユニコードに変換する必要があります。(以下のサンプルコードを参照してください)リクエスト仕様のプレフィックスを変換されたJSON文字列値に追加して、SHA1形式のハッシュ値を作成します。それから、作成されたSHA1ハッシュと比較することで、Apihash値を検証することができます。

  • サンプル コード
    // 読みやすさのために行とスペースを追加した変換されたJSON文字列の例
    {
    "transactionId": "123456789",
    "idCategory": "vid",
    "id": "1004",
    "detail": [
        {
            "action": "p",
            "assetCode": "gem",
            "amount": 1,
            "method": ""
        }
    ],
    "reason": "td",
    "subReason": "",
    "userMessage": "",
    "templateMessage": {
        "ko": {
            "title": "アイテム \uc9c0\uae09 \uba54\uc138\uc9c0 QA \ud55c\uad6d",
            "body": "アイテム \uc9c0\uae09 \uba54\uc138\uc9c0 QA \ud55c\uad6d\uc5b4 \ub178\ucd9c"
        }
    },
    "serverId": "kr",
    "additionalinfo": "",
    "gameIndex": 539
    }
    

Request API によるアイテムの配信/取得方法としてのHTTP通信

補助金/取り消しリクエストAPIは、HTTPプロトコルを使用して、Hive コンソール > 請求 > アイテム > アイテム登録メニューに設定されたゲームサーバー(URL)と通信し、リクエストデータの送信方法はPOSTです。

リクエスト仕様 (アイテムからゲームサーバーへ)

HTTP Header: Apihash

  • データ検証のために、ハッシュ値をキー値と共に送信してください、Apihash
  • ハッシュ値にはsha1を使用してください(!@#COM2US!@#JSON Stringの本文に追加します)。
  • リクエストボディ
フィールド名 説明 タイプ 必須 (必須: M, オプション: O)
transactionId 各リクエストを区別するための識別子(重複リクエストの確認用) 詳細はこちら 文字列 M
idCategory ID
* シングルモジュール: hiveuid
* Auth v1: vid
* Auth v4: playerid
文字列 M
id idCategoryに対応するID値 文字列 M
detail 以下の3つのアイテム(オブジェクト)の配列 配列 M
action 送信するか取得するか
* sまたはp: 送信
* wまたはr: 取得
文字列 M
assetCode 送信するアイテムコード 文字列 M
amount 送信するアイテムの数量 整数 M
reason リクエストの理由 詳細はこちら 文字列 M
subReason リクエストの理由 詳細はこちら 文字列 O
serverId 対象ユーザーがアクセスしたサーバー(サーバーID) 文字列 M
additionalinfo クライアントからゲームサーバーに送信される追加情報(すべて小文字) 文字列 O
duration ギフトボックスにアイテムを保存する期間(オプション) 詳細はこちら 1-9999: アイテムを保存する期間 -1: ゲームサーバーで設定可能な最大値 整数 O
userMessage アイテムが変更不可能で、templateMessageを使用していない古いゲームと交換可能なメッセージデータ 文字列 O
templateMessage アイテム配信メッセージキー用に設定されたメッセージデータ、言語コード、タイトルと本文の値(データが存在する場合、デフォルト形式はオブジェクトですが、空の場合は値が文字列型として返されます。) オブジェクト O
gameIndex AppCenter内の各ゲームのシリアル番号 整数 M


transactionId

  • 各リクエストのtransactionIdを特定することで、リクエストがすでに処理されたかどうかを区別します。(重複送信/取得を避ける)
  • 重複リクエストの場合は、レスポンス値にそれを指定します。(レスポンス仕様を参照)

理由

Note

理由フィールドの詳細は追加または変更可能ですので、発生理由を参照してください。

フィールド名説明<

pe 支払いエラー
rge 報酬ゲームエラー
rcd 報酬消費者不満
rce 報酬クーポンエラー
ro 報酬海外
ae 資産交換
e イベント
ea イベント自動
mc 大量クーポン
uc ユニーククーポン
b IAP v2によるゲーム内課金
lb Lebi課金
co CPIオファーウォール
p プロモーション クロスバナー、オファーウォール、UAに均等に使用
sr ストリーミング報酬
tcs テストCS
tgm テストGM
tpm テストPM
tqa テストQA
td テスト開発者
tg テストゲスト
tmb テスト市場、ビジネス
to テスト海外(テスト開発者)
re 取得(その他)
rr 返金取得
mr 大量リクエスト
etc その他


subReason

理由 サブ理由 説明
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


プロモーションタイプ

  • クロスプロモーション: ユーザーが現在プレイしているゲームで、バナーおよびオファーウォール(無料ゲームキャッシュ)形式で他のゲームを宣伝することができます。クロスプロモーションは、通常のバナーとインタースティシャルバナーに分かれています。
  • オファーウォール: ユーザーのデバイスにインストールされたことのないゲームのバナー形式のリストを表示します。ユーザーがバナーをタッチして新しいゲームをインストールすると、報酬が送信されます。オファーウォールには、オファーウォールとオファーウォールスペシャルの2種類があります。
  • UA/UC: ソーシャルメディアやQRコードを通じた招待機能があります。招待したユーザーと招待されたユーザーはUAに存在しますが、招待されたユーザーはUCにのみ存在します。事前登録にはUCを使用してください。

報酬の与え方

  • CPI: ユーザーがインストール後に初めてゲームをプレイしたときに報酬が送信されます。
  • CPA: ユーザーがゲーム内の特定の成果を達成したときに報酬が送信されます。詳細については、プロモーション運営ガイドを参照してください。

duration

  • アイテムをギフトボックスに保存する期間です。アイテムごとにバックオフィスで個別に設定できます。
  • ゲームサーバーは以下のケースに従って処理します。
    • キーの不在: ゲームサーバーが提供するデフォルト値を使用します。(例:アイテムを最大7日間保存)
    • 1~9999: 保存日数のいずれかの数字を使用します。(例:値14はアイテムを14日間保存することを意味します)
    • -1: ゲームサーバーで設定可能な最大値を使用します。(例:アイテムを永久に保存)

レスポンス仕様 (ゲームサーバーからアイテムへ)

レスポンス (ゲームサーバーからアイテムへ)

フィールド名 説明 タイプ 必須 (必須: M, オプション: O)
コード 処理結果コード 詳細を見る 整数 M
メッセージ 処理結果メッセージ 文字列 M
  • エラーコード
    コード 説明
    2xxxx クリア。処理成功
    20000 クリア。処理成功
    20001 クリア 成功ケースはすでに存在します(重複リクエストの場合) 通常処理されたtransactionIdはすでに存在します
    4xxxx リクエストパラメータエラー
    40001 リクエストJSONエラー
    40002 ハッシュエラー
    40003 必須パラメータキーが省略されました
    40004 必須パラメータキータイプエラー
    40005 必須パラメータがnull
    40006 必須パラメータが間違っています(例:負の数)
    5xxxx サーバー処理エラー
    50001 無効なユーザー
    50004 DB登録エラー
    50005 パラメータエラー(例:無効なアイテムコード)
  • Call Sample<
    
    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":"\ud55c\uae00 \uba54\uc138\uc9c0","body":"\ud55c\uae00 \ub0b4\uc6a9"},"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
    
  • Response Sample<
    < 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":"このリクエストはすでに処理されています"}
    

Request ample(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 &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);

Response Sample(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' =&gt; 50001,
    'message' =&gt; '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リクエスト

TCP/IPリクエスト API は、ソケットを使用してアイテムを配信/取得するためのパケットデータ通信です。API はプロトコルを使用し、そのポートは 20080 です。 データは基本的に JSON 形式で、HTTP 通信と同じ形式であり、バイトオーダー形式は ネットワーク バイトオーダー(ビッグ-エンディアン)です。

リクエストパケット仕様 (アイテムからゲームサーバーへ)

パケットサイズ 4バイト 4バイト 可変 4バイト 可変
説明 パケットの全長 ヘッダーの長さ ヘッダーの内容 ボディの長さ ボディの内容
  • 最初の4バイトでは、4バイトを含むパケット全体の長さを指定します。 e.g., ヘッダーが46バイトでボディが100バイトの場合、パケットの長さは4+4+46+4+100=158バイトです。
  • 次の4バイトでは、その後に続くHeaderの長さを指定します。
  • HeaderJSON String形式で、HTTP通信のハッシュ値と同じです。 e.g.,{"Apihash":"912ec803b2ce49e4a541068d495ab570"}
  • 次の4バイトでは、その後に続くBodyの長さを指定します。
  • BodyJSON String形式で、HTTP通信のリクエスト値と同じです。

レスポンスパケット仕様 (ゲームサーバーからアイテムへ)

パケットサイズ 4バイト 可変
内容 パケットの全長 ボディ
  • 最初の4バイトには、4バイトを含むパケット全体の長さを指定します。
  • BodyJSON String形式で、HTTP通信の応答値と同じです。