アイテムと同期

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

接続の準備¶

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

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

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

API通信方法¶

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

ゲームの適用方法¶

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

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

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

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

アイテムは、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の本文に追加します）。

• リクエストボディ

transactionId

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

理由

フィールド名説明<

subReason

プロモーションタイプ

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

報酬の与え方

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

duration

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

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

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

• エラーコード

  コード	説明
  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 & 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' => 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リクエスト¶

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

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

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

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

• 最初の4バイトには、4バイトを含むパケット全体の長さを指定します。
• BodyはJSON String形式で、HTTP通信の応答値と同じです。