GaaS
ثبت‌نام

مستندات API

سرور فروشگاهت را به بازی‌ها وصل کن: بازی سمت سرور، اعمال خودکار کد تخفیف و وب‌هوک‌های امضاشده.

دانلود OpenAPI

شروع سریع

  1. 1در پنل، از «تنظیمات ← API و وب‌هوک» یک کلید بساز.
  2. 2کلید را در هدر Authorization بفرست.
  3. 3بعد از خرید مشتری، یک بازی سمت سرور اجرا کن و کد جایزه را نمایش بده.
curl
curl -X POST https://your-domain/api/v1/campaigns/yalda-2026/plays \
  -H "Authorization: Bearer gk_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"player_identifier": "09121234567", "player_ip": "203.0.113.7"}'

# 201 Created
{
  "data": {
    "play_id": 1842,
    "result": "win",
    "prize": { "id": 3, "title": "20% off", "type": "discount_code" },
    "claim": { "claim_code": "WIN-AB12CD34EF", "discount_code": "YALDA20", "expires_at": "…" }
  }
}

احراز هویت

همه درخواست‌ها باید کلید API را در هدر Authorization (یا X-Api-Key) داشته باشند. محدودیت: ۱۲۰ درخواست در دقیقه برای هر کلید.

Authorization: Bearer gk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

خطاها

خطاها همیشه به شکل { "error": { "code", "message" } } برگردانده می‌شوند.

{ "error": { "code": "PLAYER_LIMIT_REACHED", "message": "You have used all your plays for this campaign." } }

Endpointها

مستندات در حال حاضر در دسترس نیست.

وب‌هوک‌ها

هر رویداد با HMAC-SHA256 امضا می‌شود. امضا = hex(HMAC(secret, "{timestamp}.{body}")). درخواست‌های قدیمی‌تر از ۵ دقیقه را رد کن. در صورت خطا، ارسال تا ۴ بار دیگر تکرار می‌شود.

بررسی امضا

Node.js
import crypto from 'node:crypto';

export function verify(req, rawBody, secret) {
  const ts = req.headers['x-webhook-timestamp'];
  const sig = req.headers['x-webhook-signature'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}
PHP
function verify(string $body, array $headers, string $secret): bool
{
    $ts  = $headers['X-Webhook-Timestamp'] ?? '';
    $sig = $headers['X-Webhook-Signature'] ?? '';
    if (abs(time() - (int) $ts) > 300) {
        return false;
    }
    $expected = hash_hmac('sha256', $ts . '.' . $body, $secret);
    return hash_equals($expected, $sig);
}

بازارچه بازی برای طراحان

بازی خودتان را بسازید تا کسب‌وکارها در کمپین‌هایشان از آن استفاده کنند.

  1. 1قالب شروع را دانلود کنید؛ بازی یک فایل HTML مستقل است (حداکثر ۵۱۲ کیلوبایت).
  2. 2از پنل «بازارچه بازی» ارسال کنید؛ ادمین آن را در همان محیط امن امتحان و تأیید می‌کند.
  3. 3پس از تأیید، بازی در کاتالوگ همه پذیرندگان قرار می‌گیرد. نسخه‌های بعدی هم پس از بررسی جایگزین می‌شوند.
کیت توسعه بازی (پیشنهادی)
// Paste /sdk/gaas-game-sdk.js into a <script> tag (games have no network access)
const ctx = await GaaS.ready();        // { locale, dir, colors: { primary, secondary }, settings }
button.onclick = async () => {
  try {
    const result = await GaaS.play();  // { won, prize: { title } | null } — decided on the server
    await revealAnimation(result);
    GaaS.done();                       // the platform shows the prize sheet
  } catch (err) {
    // e.g. no plays left: let the player try again
  }
};
// The frame height follows your content automatically.
پروتکل پیام زیربنایی (SDK آن را برای شما انجام می‌دهد)
// your game → platform
parent.postMessage({ type: 'gaas:ready' }, '*');            // page loaded
parent.postMessage({ type: 'gaas:play' }, '*');             // the player made their move
parent.postMessage({ type: 'gaas:done' }, '*');             // reveal finished, show the prize
parent.postMessage({ type: 'gaas:height', height: 480 }, '*');

// platform → your game
{ type: 'gaas:init', locale: 'fa', dir: 'rtl', colors: { primary, secondary }, settings: {} }
{ type: 'gaas:result', won: true, prize: { title: '20% off' } }   // decided on the server
{ type: 'gaas:error', message }                                  // e.g. no plays left: let them retry

بازی در محیط ایزوله اجرا می‌شود (sandbox با origin مات): بدون دسترسی به شبکه، کوکی، حافظه مرورگر، فرم یا پنجره جدید. برنده را سرور تعیین می‌کند و بازی شما فقط نتیجه را نمایش می‌دهد؛ اطلاعات بازیکن هرگز به آن داده نمی‌شود.

دانلود قالب شروع دانلود کیت توسعه بازی (SDK)