시작하기

이 가이드는 Aghanim과 모바일 게임을 통합하는 단계별 지침을 제공합니다. 이 통합의 유일한 요구 사항은 앱 스토어에 게임을 등록하고 개발자 자원을 일부 할당하는 것입니다.

하나의 통합으로 Aghanim 제품군 전체에 연결하여 Game Hub를 배포하고 라이브 운영 캠페인을 시작하며 전 세계적으로 결제를 수락하는 등 다양한 기능을 사용할 수 있습니다.

1단계: Aghanim에 등록하고 게임 연결하기

게임은 Apple App Store 또는 Google Play Store에 등록되어 있어야 합니다.

2단계: Aghanim의 이벤트 처리하기

Aghanim은 Game Hub에서 플레이어 상호작용 시 백엔드로 다양한 이벤트를 보냅니다. 귀하의 시스템은 플레이어를 데이터베이스에서 확인하고 구매한 아이템으로 플레이어 계정을 업데이트하는 등의 작업으로 이러한 이벤트에 대응해야 합니다.

성공적인 통합을 위한 필수적인 Aghanim 이벤트는 다음과 같습니다:

플레이어 검증 (player.verify): 플레이어 로그인을 게임에 알리고, Game Hub 액세스를 허용하거나 거부하기 위해 웹훅 서버의 확인이 필요합니다.
아이템 추가 (item.add): Game Hub 내 활동을 바탕으로 플레이어 계정에 아이템을 지급하도록 알립니다.
아이템 제거 (item.remove): 결제 취소나 환불 등으로 인해 플레이어 계정에서 아이템을 제거하도록 알립니다.

player.verify
item.add
item.remove

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

{
  "event_type": "item.add",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "items": [
      {
        "id": "itm_exTBZQmIlDz",
        "name": "Crystals",
        "description": "라이벌들을 항복하게 하는 거대한 수정 보물.",
        "sku": "crystals",
        "quantity": 480000,
        "price": 9499,
        "price_decimal": 94.99,
        "currency": "USD", 
        "type": "item",
        "nested_items": null
      }
    ],
    "reason": "쿠폰 WELCOME 사용됨"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "sandbox": false, 
  "game_id": "gm_exTAyxPsVwh",
  "trigger": "order.paid",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "transaction_id": "whtx_eCacGbJVbvToOgzjXUgOCitkQE",
  "context": {
    "order": {
      "id": "ord_eCacAulggpY",
      "amount": 9499,
      "country": "US",
      "currency": "USD",
      "revenue_usd": 9499,
      "fees": {
        "payment_system_fee_usd": 2.85,
        "aghanim_fee_usd": 14.25,
        "taxes_usd": 7.65
      },
      "receipt_number": "AGH-123456",
      "status": "paid",
      "created_at": 1725548450,
      "paid_at": 1725548460
    }
  }
}

{
  "event_type": "item.remove",
  "event_data": {
    "player_id": "2D2R-OP3C",
    "items": [
      {
        "id": "itm_exTBZQmIlDz",
        "name": "Crystals",
        "description": "라이벌들을 항복하게 하는 거대한 수정 보물.",
        "sku": "crystals",
        "quantity": 480000,
        "price": 9499,
        "price_decimal": 94.99,
        "currency": "USD",
        "type": "item",
        "nested_items": null
      }
    ],
    "reason": "쿠폰 WELCOME 사용됨"
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "sandbox": false, 
  "game_id": "gm_exTAyxPsVwh",
  "trigger": "order.refunded",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "transaction_id": "whtx_eCacGbJVbvToOgzjXUgOCitkQE",
  "context": {
    "order": {
      "id": "ord_eCacAulggpY",
      "amount": 9499,
      "country": "US",
      "currency": "USD",
      "revenue_usd": 9499,
      "fees": {
        "payment_system_fee_usd": 2.85,
        "aghanim_fee_usd": 14.25,
        "taxes_usd": 7.65
      },
      "receipt_number": "AGH-123456", 
      "status": "canceled",
      "created_at": 1725548450,
      "paid_at": 1725548460
    }
  }
}

웹훅 엔드포인트 함수 개발하기

Aghanim의 이벤트를 관리하려면 하나 이상의 함수를 개발해야 합니다. 이러한 선택은 모든 이벤트를 단일 엔드포인트를 통해 처리할지, 아니면 각각 특정 이벤트나 다른 논리에 전념하는 여러 엔드포인트를 사용할지에 따라 달라집니다.

귀하의 함수는 다음 요구 사항 및 로직를 따라야 합니다:

POST 웹훅 요청을 수락하는 HTTPS 엔드포인트.
Aghanim이 생성하고 서명한 이벤트를 수신합니다.
웹훅 페이로드에 포함된 idempotency_key를 처리하여 중복 웹훅 처리를 방지합니다.
Player ID를 기준으로 게임 허브 접근 권한을 결정하기 위해 데이터베이스에서 플레이어를 확인하거나, 구매한 아이템을 플레이어 계정에 지급하거나, 환불된 아이템을 계정에서 제거하는 등, 수신된 요청을 적절하게 처리해야 합니다.
성공적으로 처리된 이벤트에는 2xx 상태 코드를, 거부 또는 오류에는 4xx 또는 5xx를 응답합니다. player.verify 이벤트의 경우, 플레이어 검증에 성공했다면 서버는 또한 플레이어 데이터가 포함된 JSON 페이로드도 반환해야 합니다.

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

Python
Ruby
Node.js
Go

# 통합에서 웹훅 이벤트를 처리하기 위해 이 샘플 코드를 사용하세요.
#
# 1. 이 코드를 `server.py`라는 새 파일에 붙여 넣으세요.
#
# 2. 의존성 설치:
#    python -m pip install fastapi[all]
#
# 3. http://localhost:8000에서 서버를 실행합니다
#    python server.py

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)

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

# 통합에서 웹훅 이벤트를 처리하기 위해 이 샘플 코드를 사용하세요.
#
# 1. 이 코드를 `server.rb`라는 새 파일에 붙여 넣으세요.
#
# 2. 의존성 설치:
#    gem install sinatra json hmac
#
# 3. http://localhost:8000에서 서버를 실행합니다
#    ruby server.rb

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

if __FILE__ == $0
  require 'sinatra'
  set :bind, '0.0.0.0'
  set :port, 8000
end

// 통합에서 웹훅 이벤트를 처리하기 위해 이 샘플 코드를 사용하세요.
//
// 1. 이 코드를 새로운 파일 `server.js`에 붙여 넣으세요.
//
// 2. 의존성 설치:
//    npm install express
//
// 3. http://localhost:8000에서 서버를 실행합니다
//    node server.js

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));
}

app.listen(8000, () => {
  console.log('Server is running on http://localhost:8000');
});

// 통합에서 웹훅 이벤트를 처리하기 위한 샘플 코드입니다.
//
// 1. 이 코드를 새로운 파일 `server.go`에 붙여넣으세요.
//
// 2. http://localhost:8000에서 서버를 실행하세요
//    go run server.go

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))
}

func main() {
  http.HandleFunc("/webhook", webhookHandler)
  fmt.Println("Server is running on http://localhost:8000")
  http.ListenAndServe(":8000", nil)
}

로컬에서 다음 요청을 실행하여 웹훅 엔드포인트 기능을 테스트할 수 있습니다:

cURL
Python

curl -X POST "https://your-webhook-endpoint.com/your/webhook/uri" \
  -H 'x-aghanim-signature-timestamp: <EVENT_TIMESTAMP>' \
  -H 'x-aghanim-signature: <HMAC-SHA256_SIGNATURE>' \
  -H 'user-agent: Aghanim/0.1.0' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  -H 'host: your-webhook-endpoint.com' \
  -d '{
      "event_id": "whevt_eAeXhOxLwxy",
      "event_type": "player.verify",
      "idempotency_key": null,
      "event_data": {
          "player_id": "testplayer"
      },
      "context": null
  }'

import requests

# Endpoint URL
url = "https://your-webhook-endpoint.com/your/webhook/uri"

# Headers
headers = {
    'x-aghanim-signature-timestamp': '<EVENT_TIMESTAMP>',
    'x-aghanim-signature': '<HMAC-SHA256_SIGNATURE>',
    'user-agent': 'Aghanim/0.1.0',
    'content-type': 'application/json',
    'accept': '*/*',
    'host': 'your-webhook-endpoint.com'
}

# JSON payload
data = {
    "event_id": "whevt_eAeXhOxLwxy",
    "event_type": "player.verify",
    "idempotency_key": null,
    "event_data": {
        "player_id": "testplayer"
    },
    "context": null
}

# Make the POST request
response = requests.post(url, headers=headers, json=data)

# Print the response from the server
print(response.text)

엔드포인트를 Aghanim에 등록하기

엔드포인트를 사용 가능하게 설정하세요.
Aghanim 계정 → Game → Webhooks → New Webhook 내에서 다음 이벤트를 선택하여 엔드포인트를 등록하세요:
- 플레이어 검증
- 아이템 추가
- 아이템 제거
생성된 비밀 키를 복사하여 요청 서명 검증을 위해 웹훅 함수에 지정하세요.

3단계: Player ID 인증 설정

플레이어는 Player ID를 사용하여 Game Hub에 로그인할 수 있습니다. Player ID는 게임에서 사용되는 고유 식별자이어야 합니다.

게임 허브에서 플레이어를 인증하는 데 사용할 게임 내 매개변수를 결정합니다. 게임에서 이미 사용 중인 고유 식별자여야 합니다.
Aghanim은 로그인 시도를 포함하여 플레이어가 게임 허브와 상호 작용할 때마다 서버에 알림을 보냅니다. 서버는 Player ID를 기반으로 액세스를 허용하거나 거부해야 합니다. 아래에 설명된 대로 이 검증 프로세스를 구현합니다.
게임 → 설정 → 게임 허브 로그인 스타일의 Aghanim 대시보드에 자세한 지침을 추가하여 게임 허브 사용자가 인증 데이터를 찾는 방법을 안내하세요. 플레이어가 게임 내에서 자신의 Player ID를 찾을 수 있는 위치를 자세히 설명하고, 명확성을 위해 예시 이미지를 포함하는 것을 고려하세요.

4단계: 생성된 Game Hub 검토

모바일 게임을 연결하면 Aghanim이 즉시 해당 게임 데이터에 맞춰 Game Hub를 생성합니다. 이 허브는 게임 스토어, 뉴스, 이벤트, 리더보드, 업적, 일일 보상, 특별 할인, 코드 교환 기능 등을 갖춘 direct-to-consumer 웹사이트로, 완전한 커스터마이징과 브랜드 적용이 가능한 형태로 준비되었습니다.

게임 허브를 구성하기 위해 앱 스토어에서 모든 필요한 데이터를 직접 소싱하여 게임 허브를 자동으로 다음과 같이 채웁니다:

게임의 로고
게임 내 아이템 및 가격
뉴스와 업데이트
예정된 이벤트 및 진행 중인 이벤트
리더보드

앱 스토어에 부족한 정보가 있으면 Aghanim은 AI 기반 허브 설정 프로세스를 통해 아이템 이미지, 뉴스 이미지 등 누락된 요소를 추가하여 보완합니다.

Aghanim Dashboard에서 Game Hub Builder → View your Game Hub로 이동하여 Game Hub에 접근하세요.

5단계: 모바일 플레이어 참여를 위한 캠페인 실행하기

게임 허브가 준비되었습니다! 모바일 플레이어를 웹 경험으로 끌어들이고, 라이브 운영 캠페인을 통해 참여를 유도할 때입니다.

계속하려면 다음 캠페인 중 적어도 하나를 선택하세요:

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