플레이어 검증 웹훅

Aghanim은 플레이어 검증 웹훅을 활용하여 플레이어 로그인에 대한 정보를 게임에 알리고, 게임 허브에 대한 액세스를 허용하거나 거부하기 위해 웹훅 서버에서 확인을 요구합니다. 이 문서는 이러한 웹훅의 운영에 대한 정보를 제공합니다.

웹훅은 게임에서 플레이어의 등록을 확인하고 Game Hub와의 플레이어 상호작용 중 여러 번 호출될 수 있습니다.

요구 사항

Aghanim에서 플레이어 검증 웹훅을 사용하려면 다음과 같이 웹훅 서버를 구성해야 합니다:

• POST 웹훅 요청을 수락하는 HTTPS 엔드포인트.
• Aghanim이 생성하고 서명한 이벤트를 수신합니다.
• 플레이어 ID를 기준으로 게임 허브에 대한 액세스를 확인하려면 데이터베이스에서 플레이어를 검증합니다.
• 승인을 위해 2xx 상태 코드 및 해당 JSON 페이로드를, 거부하거나 오류가 발생할 경우 4xx 또는 5xx를 응답합니다.

구성

다음은 Aghanim에서 생성한 플레이어 검증 이벤트를 처리하는 엔드포인트용 함수 템플릿입니다:

• Python
• Ruby
• Node.js
• Go

import fastapi, hashlib, hmac, json, typing 

app = fastapi.FastAPI()

@app.post("/webhook")
async def webhook(request: fastapi.Request) -> dict[str, typing.Any]:
    secret_key = "<YOUR_S2S_KEY>"  # 실제 웹훅 비밀 키로 교체하세요

    raw_payload = await request.body()
    payload = raw_payload.decode()
    timestamp = request.headers["x-aghanim-signature-timestamp"]
    received_signature = request.headers["x-aghanim-signature"]

    if not verify_signature(secret_key, payload, timestamp, received_signature):
        raise fastapi.HTTPException(status_code=403, detail="Invalid signature")

    data = json.loads(payload)
    event_type = data["event_type"]
    event_data = data["event_data"]

    raise fastapi.HTTPException(status_code=400, detail="Unknown event type")

def verify_signature(secret_key: str, payload: str, timestamp: str, received_signature: str) -> bool:
    signature_data = f"{timestamp}.{payload}"
    computed_hash = hmac.new(secret_key.encode(), signature_data.encode(), hashlib.sha256)
    computed_signature = computed_hash.hexdigest()
    return hmac.compare_digest(computed_signature, received_signature)

require 'sinatra'
require 'json'
require 'openssl'

post '/webhook' do
  secret_key = "<YOUR_S2S_KEY>"  # 실제 웹훅 비밀 키로 교체하세요

  payload = request.body.read
  timestamp = request.env["HTTP_X_AGHANIM_SIGNATURE_TIMESTAMP"]
  received_signature = request.env["HTTP_X_AGHANIM_SIGNATURE"]

  unless verify_signature(secret_key, payload, timestamp, received_signature)
    halt 403, "Invalid signature"
  end

  data = JSON.parse(payload)
  event_type = data["event_type"]
  event_data = data["event_data"]

  halt 400, "Unknown event type"
end

def verify_signature(secret_key, payload, timestamp, received_signature)
  signature_data = "#{timestamp}.#{payload}"
  computed_signature = OpenSSL::HMAC.hexdigest('sha256', secret_key, signature_data)
  OpenSSL.secure_compare(computed_signature, received_signature)
end

const express = require('express');
const crypto = require('crypto');

const app = express();

app.post('/webhook', express.raw({ type: "*/*" }), async (req, res) => {
  const secretKey = '<YOUR_S2S_KEY>'; // 실제 웹훅 비밀 키로 교체하세요

  const rawPayload = req.body;
  const timestamp = req.headers['x-aghanim-signature-timestamp'];
  const receivedSignature = req.headers['x-aghanim-signature'];

  if (!verifySignature(secretKey, rawPayload, timestamp, receivedSignature)) {
    return res.status(403).send('Invalid signature');
  }

  const payload = JSON.parse(req.body);
  const { event_type, event_data } = payload;

  return res.status(400).send('Unknown event type');
});

function verifySignature(secretKey, payload, timestamp, receivedSignature) {
  const signatureData = `${timestamp}.${payload}`;
  const computedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(signatureData)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(receivedSignature));
}

package main

import (
  "crypto/hmac"
  "crypto/sha256"
  "encoding/hex"
  "encoding/json"
  "fmt"
  "io/ioutil"
  "net/http"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
  secretKey := "<YOUR_S2S_KEY>"  // 실제 웹훅 비밀 키로 교체하세요

  rawPayload, _ := ioutil.ReadAll(r.Body)
  payload := string(rawPayload)
  timestamp := r.Header.Get("X-Aghanim-Signature-Timestamp")
  receivedSignature := r.Header.Get("X-Aghanim-Signature")

  if !verifySignature(secretKey, payload, timestamp, receivedSignature) {
    http.Error(w, "Invalid signature", http.StatusForbidden)
    return
  }

  var data map[string]interface{}
  if err := json.Unmarshal(rawPayload, &data); err != nil {
    http.Error(w, "Invalid payload", http.StatusBadRequest)
    return
  }

  eventType := data["event_type"].(string)
  eventData := data["event_data"].(map[string]interface{})

  http.Error(w, "Unknown event type", http.StatusBadRequest)
}

func verifySignature(secretKey, payload, timestamp, receivedSignature string) bool {
  signatureData := fmt.Sprintf("%s.%s", timestamp, payload)
  mac := hmac.New(sha256.New, []byte(secretKey))
  mac.Write([]byte(signatureData))
  computedSignature := hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(computedSignature), []byte(receivedSignature))
}

함수가 준비되면:

1. 엔드포인트를 사용 가능하게 설정하세요.
2. Aghanim 계정 내에서 엔드포인트를 등록하세요 → 게임 → 웹훅 → 새로운 웹훅에서 플레이어 검증 이벤트 유형을 선택하여 등록하세요.

대안으로, 웹후크 생성 API 방법을 사용하여 Aghanim 내에서 엔드포인트를 등록할 수 있습니다.

요청 스키마

아래는 예시입니다 player.verify 웹훅 요청:

HTTP

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "player.verify",
  "event_data": {
    "player_id": "2D2R-OP3C"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "trigger": "hub.login",
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}
            

cURL

curl "https://your-webhook-endpoint.com/your/webhook/uri" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "User-Agent: Aghanim/0.1.0" \
    -H "X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812" \
    -H "X-Aghanim-Signature-Timestamp: 1725548450" \
    -d '{
      "event_type": "player.verify",
      "event_data": {
        "player_id": "2D2R-OP3C"
      },
      "event_time": 1725548450,
      "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
      "idempotency_key": null,
      "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
      "sandbox": false,
      "trigger": "hub.login",
      "transaction_id": "whtx_eCacGbJVbvT",
      "context": null,
      "game_id": "gm_exTAyxPsVwh"
    }'
            

이벤트 스키마

Key	유형	설명
event_id	string	Aghanim에 의해 생성된 고유 이벤트 ID.
game_id	string	Aghanim 시스템에서의 귀하의 게임 ID.
event_type	string	이벤트의 유형, player.verify 이럴 경우.
event_time	number	유닉스 에포크 시간으로 된 이벤트 날짜.
event_data	EventData	이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_key	string|null	웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다. 일 수 있습니다 null 이벤트 유형에 따라 달라집니다.
request_id	string|null	이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandbox	boolean	이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
trigger	string|null	The trigger that caused the event to be sent.
transaction_id	string	Aghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
context	object|null	이벤트에 대한 컨텍스트 정보.

EventData 스키마

Key	유형	설명
player_id	string	플레이어 인증을 위해 선택된 고유한 플레이어 ID.

응답 스키마

플레이어 검증이 성공적으로 완료되면 서버는 2xx 범위의 상태 코드와 플레이어 데이터가 포함된 다음 JSON 페이로드를 반환해야 합니다:

Key	유형	설명	필수 여부
player_id	string	플레이어 인증을 위해 선택된 고유한 플레이어 ID.	예
name	string	플레이어의 닉네임.	예
attributes	Attributes	Aghanim이 기대하는 기본 플레이어 속성.	예
avatar_url	string	플레이어의 아바타 URL.	아니오
email	string	플레이어의 이메일 주소.	아니오
banned	boolean	플레이어가 게임에서 금지되었는지 여부를 나타냅니다.	아니오
segments	string[]	플레이어가 속한 세그먼트.	아니오
country	string	ISO 3166‑1에 따른 두 자리 국가 코드.	아니오
custom_attributes	CustomAttributes	사용자 정의 플레이어 속성.	아니오
balances	Balance[]	플레이어의 재화 잔액.	아니오

Balance 객체

Balance 객체는 다음 필드를 포함합니다:

Key	유형	설명	필수 여부
sku	string	재화와 연동된 아이템 SKU가 게임 측과 Aghanim 측 모두에서 일치해야 합니다.	예
quantity	number	플레이어의 화폐 잔액입니다.	예

Attributes 객체

Attributes 객체는 다음 필드를 포함합니다:

Key	유형	설명	필수 여부
level	number	게임에서 플레이어의 레벨.	예
platform	string	플레이어가 게임 허브를 사용하는 플랫폼입니다. 가능한 값: ios, android.	아니오
marketplace	string	플레이어 유입 경로로 사용된 마켓플레이스. 가능한 값: app_store, google_play, other.	아니오
soft_currency_amount	number	플레이어의 소프트 재화 잔액.	아니오
hard_currency_amount	number	플레이어의 하드 재화 잔액.	아니오

CustomAttributes 객체

CustomAttributes 객체에는 키-값 쌍이 포함되어 있습니다. 예:

{
  "is_premium": true,
  "age": 25,
  "favorite_color": "blue",
  "install_date": 1704070800
}

이러한 속성은 나중에 특정 플레이어 세그먼트를 타겟으로 하기 위해 LiveOps 또는 세분화 에서 로직 조건을 구성할 때 사용될 수 있습니다.

경고

중요: 사용자 정의 속성은 게임 → 플레이어 속성에서 선언해야 합니다.

성공적인 응답 예시:

{
  "player_id": "2D2R-OP3C",
  "name": "비비에이트",
  "avatar_url": "https://static-platform.aghanim.com/images/bb8.jpg",
  "attributes": {"level": 2},
  "country": "US"
}

도움이 필요하세요?
통합팀에 문의하십시오 integration@aghanim.com