Games I Know logoGames I Know
ألعاب Embedالوثائق

Embed API المستندات

تعلم embed من خلال تشغيله، ثم قم بتوصيل الأحداث.

ابدأ بالعرض التوضيحي المباشر، وشاهد أحداث الصفحة الرئيسية، ثم انسخ نمطَي iframe والمستمع إلى موقعك. ينطبق هذا التسلسل نفسه على جميع ألعاب Games I Know iframe.

احصل على مفتاح embed
1. تعلم أولاً

عرض تجريبي مباشر: العب وتحقق من الأحداث

قم بتحريك عنصر في Tic Tac Toe iframe. يُظهر سجل الأحداث GAME_STARTED وأحداث اللعب وبيانات الإكمال تمامًا كما تستقبلها الصفحة الرئيسية.

عقد فعالية على مستوى المنصة

يُرسل Games I Know أحداث embed لكل لعبة على المنصة: Tic Tac Toe، وFour in a Row، وBingo، وI Know اليوم، ولكل لعبة جديدة قابلة لـ embed نضيفها في المستقبل. لستَ بحاجة إلى تكامل منفصل لكل لعبة. أنشئ مُستمعًا واحدًا للصفحة الرئيسية بناءً على العقد القياسي (جاهز، بدء اللعبة، أحداث اللعب، الإكمال مع بيانات الفائز، والنتائج المُوقّعة) وأعد استخدامه في جميع ألعاب embed الحالية والقادمة.

2. البدء السريع

من الصفر إلى العمل embed

استخدم هذا المسار عندما تعرف بالفعل أين يجب أن تظهر اللعبة على موقعك الإلكتروني.

  1. 1

    إنشاء حساب شريك

    أضف نطاق الموقع الإلكتروني الذي سيستضيف iframe.

    انتقل إلى الخطوة
  2. 2

    قم بتثبيت مسار الإطار

    استخدم /embed/{gameSlug}/frame/ مع معرّف المستأجر الخاص بك. لا تقم بـ iframe لصفحة الهبوط الخاصة بتحسين محركات البحث.

    انتقل إلى الخطوة
  3. 3

    استمع إلى رسائل الوالدين

    قم بتصفية البيانات بناءً على مصدر البيانات === "gamesiknow"، ثم قم بمعالجة أحداث بدء اللعبة، وإكمال اللعبة، وأحداث اللعب من الإصدار 1.

    انتقل إلى الخطوة
  4. 4

    تحقق من النتائج المكتملة

    أرسل resultId و signedToken إلى الواجهة الخلفية الخاصة بك قبل منح الاعتمادات أو المكافآت أو عمليات الفتح.

    انتقل إلى الخطوة
المُشغِّل iframe

استخدم معرف المستأجر الحقيقي الخاص بك من لوحة تحكم الشريك.

html
<iframe
  src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=YOUR_TENANT_ID"
  title="Tic Tac Toe by Games I Know"
  width="100%"
  height="640"
  style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
  loading="lazy"
  allow="fullscreen"
  referrerpolicy="no-referrer-when-downgrade"
  allowfullscreen
></iframe>
3. الهندسة المعمارية

كيف يعمل embed

يُعدّ Games I Know embed نسخة معزولة من iframe على نطاقك. يقوم هذا العنصر بالتحقق من صحة بيانات المستأجر والنطاق الخاص بك مقابل API، ثم يتواصل مع صفحتك الرئيسية عبر window.postMessage.

الخطوة 1

يتم تحميل الصفحة الرئيسية iframe

يقوم موقعك بعرض iframe يشير إلى /embed/{gameSlug}/frame/ مع tenantId ومعلمات الاستعلام الاختيارية mode أو campaignId.

الخطوة 2

Embed يتحقق من صحة المستأجر والنطاق

يستدعي iframe طلب GET إلى /embed/config (أو /api/embed/config). يتحقق Games I Know من حساب شريكك، والنطاق المسموح به، وإمكانية الوصول إلى اللعبة، وحصة AI. يتم تسجيل حدث تحليلات embed_ المُحمّل على الخادم.

الخطوة 3

Embed يصبح جاهزًا

يقوم iframe بإرسال حدث جاهزية إلى الصفحة الرئيسية حتى تتمكن من عرض حالة التحميل أو تغيير حجم الإطار باستخدام payload.embedHeight.

الخطوة 4

يبدأ اللاعب المباراة

عند بدء اللعب، تقوم كل لعبة قابلة للتنزيل (embeddable) بنشر حدث GAME_STARTED على الصفحة الرئيسية وتسجيله تلقائيًا على الخادم. لا تستخدم أي أدوات تحليل (__GIK_TERM_1_) من موقعك الإلكتروني.

الخطوة 5

بث مباشر لأحداث اللعب

أثناء المباراة، تقوم أحداث اللعب في الإصدار 1 مثل الحركة وتغيير الوضع بتحديث واجهة المستخدم أو التحليلات الداخلية.

الخطوة 6

انتهت المباراة ببيانات الفائز

عند اكتمال اللعبة، تُرسل كل لعبة قابلة للتنزيل (embeddable) رسالة GAME_COMPLETED إلى الخادم الرئيسي مع النتيجة والفائز واللاعبين، ليتمكن موقعك من عرض النتائج فورًا. كما يقوم الخادم (iframe) بتوقيع النتيجة عبر طلب POST إلى /embed/results، ويُضمّن resultId وsignedToken في رسالة GAME_COMPLETED عند نجاح التوقيع. يمكن لخادمك التحقق من هذه الرموز باستخدام مفتاح خادم الشريك قبل منح المكافآت.

صيغتان لرسائل ما بعد النشر

أحداث دورة الحياة استخدم جسمًا مسطحًا مع event: "GAME_STARTED" or event: "GAME_COMPLETED". أحداث اللعب قم بتغليف البيانات في version: 1 مع التداخل payload. قم دائمًا بتفعيل التصفية data.source === "gamesiknow".

4. التثبيت

إعداد الشريك ومقتطفات iframe

معظم عمليات التكامل تتكون من أربعة قرارات: تسجيل النطاق، وإنشاء رمز مميز، وتثبيت iframe، ثم الاستماع إلى أحداث البدء والإكمال.

قم بتسجيل كل موقع ويب

أضف كل نطاق سيستضيف Games I Know embed. يتم توحيد النطاقات بحيث يتم التعامل مع example.com و www.example.com بشكل متسق.

إنشاء رمز نطاق

أنشئ رمزًا مميزًا منفصلاً من نوع embed لكل موقع ويب. هذا يحافظ على دقة التحليلات ويُهيئ الحساب لتسعير النطاقات في المستقبل.

قم بتثبيت iframe

انسخ iframe أو الغلاف المتجاوب إلى كتلة HTML المخصصة لنظام إدارة المحتوى الخاص بك، أو منطقة embed الخاصة بمنشئ مواقع الويب، أو قالب الواجهة الأمامية المخصص.

استمع للأحداث وتحقق من النتائج

تعامل مع أحداث postMessage الخاصة بـ GAME_STARTED و GAME_COMPLETED على صفحتك الرئيسية لعرض حالة المباراة وتفاصيل الفائز. تحقق من صحة النتائج الموقعة من خادمك الخلفي باستخدام مفتاح خادم الشريك قبل منح المكافآت.

الإعدادات الموصى بها لـ iframe

عرض

استخدم 100% حتى يملأ embed عمود المحتوى المتاح.

ارتفاع

640 بكسل لمعظم الألعاب. يعمل Tic Tac Toe أيضًا عند 600 بكسل. استخدم payload.embedHeight من أحداث الجاهزية لتغيير الحجم تلقائيًا.

ألعاب

استخدم /embed/tic-tac-toe/frame/، أو /embed/four-in-a-row/frame/، أو /embed/bingo/frame/، أو /embed/i-know/frame/.

وضع

قم بحذف الوضع لاختيار اللاعب، أو مرر الوضع = الذكاء الاصطناعي عندما تريد أن يطلب embed من AI أولاً.

عادي iframe

يختار اللاعب نوع المباراة داخل اللعبة عندما تكون حصة AI متاحة.

html
<iframe
  src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=TENANT_ID"
  width="100%"
  height="640"
  style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
  allow="fullscreen"
  loading="lazy"
  title="Tic Tac Toe by Games I Know"
></iframe>
قسري AI iframe

يطلب AI أولاً. ثم يعود إلى PvP بصمت عند استنفاد الحصة.

html
<iframe
  src="https://gamesiknow.com/embed/tic-tac-toe/frame/?tenantId=TENANT_ID&mode=ai&campaignId=homepage-widget"
  width="100%"
  height="640"
  style="border:0;border-radius:16px;max-width:420px;display:block;margin:0 auto;"
  allow="fullscreen"
  loading="lazy"
  title="Tic Tac Toe vs AI by Games I Know"
></iframe>
5. التكوين

معلمات عنوان URL iframe

تستخدم عناوين URL للإطارات /embed/{gameSlug}/frame/. الصفحات المقصودة لتحسين محركات البحث بدون اللعب مباشرة على /embed/{gameSlug}/.

المعلمةمطلوبوصف
معرف المستأجرنعممعرّف المستأجر الشريك الخاص بك من لوحة تحكم الشركاء Games I Know. يُقبل أيضًا كمعرّف شريك لعمليات التكامل القديمة.
وضعلايُفعّل وضع الذكاء الاصطناعي لطلب وضع AI الإجباري. تبقى قواعد الحصص والنطاق الخاصة بالخادم سارية. يتم اللجوء إلى وضع لاعب ضد لاعب في حال عدم توفر AI.
معرف الحملةلايتم عرض تسمية الحملة الاختيارية في أحداث postMessage وتخزينها في تحليلات الشركاء لإجراء اختبارات A/B أو تقسيم الصفحات على مستوى الصفحة.
6. الأحداث

مرجع حدث postMessage

ينطبق العقد نفسه على Tic Tac Toe، Four in a Row، Bingo، I Know، وإصدارات embed القادمة.

القاعدة 1

مصدر التصفية

تجاهل الرسائل ما لم يكن مصدر البيانات هو gamesiknow.

القاعدة 2

إدارة دورة الحياة

استخدم GAME_STARTED و GAME_COMPLETED لحالة المباراة واسم الفائز والنتيجة.

القاعدة 3

تحقق من المكافآت

قم بإرسال resultId و signedToken إلى الواجهة الخلفية الخاصة بك قبل منح المكافآت.

أحداث دورة الحياة

حدثعندما يطلق النارشكلالحقول الرئيسية
مستعدتم تهيئة Embed وتحميل الإعدادات.أسلوب اللعب (الإصدار 1) لجميع الألعاب، أو مسطح لبعض أغلفة دورة الحياة.معرف التطابق، الوضع، embedالارتفاع
بدأت اللعبةكل لعبة قابلة للتغيير (الحالية والمستقبلية). يتم تشغيلها عند بدء المباراة (على سبيل المثال، الحركة الأولى أو بداية الجولة).دورة حياة مسطحةاللعبة، معرف الشريك، معرف الحملة، الوضع، معرف المباراة (ضمني عبر بث اللعب)
اكتملت اللعبةكل مباراة قابلة للتغيير (embeddable) عند انتهائها. يتضمن ذلك النتيجة، والفائز، واسم اللاعب الفائز، واللاعبين، حتى تتمكن الصفحة الرئيسية من عرض النتائج فورًا. كما يتضمن أيضًا معرف النتيجة والرمز المميز المُوقّع عند نجاح التوقيع من جانب الخادم.دورة حياة مسطحةالنتيجة، الفائز، اسم اللاعب الفائز، معرف اللاعب الفائز، اللاعبون، النتيجة، المدة بالثواني، معرف النتيجة، الرمز المميز المُوقّع
EMBED_FULLSCREEN_CHANGEيقوم المشغل بالتبديل بين وضع ملء الشاشة (embed).دورة حياة مسطحةpayload.active boolean

أحداث اللعب

شكل: { source, game, version: 1, event, payload }

  • مستعد - نفس الشيء بالنسبة لدورة الحياة الجاهزة مع الإصدار 1 من الغلاف.
  • تغيير الوضع - يختار اللاعب PvP أو AI أو يعود إلى اختيار الوضع.
  • يتحرك - حدث تحرك أو إجراء (خلية اللوحة، إسقاط القرص، نداء البنغو، إجابة سؤال تافه).
  • إعادة ضبط - إعادة ضبط اللوحة أو الجولة.
  • التراجع - آخر خطوة تم التراجع عنها (Tic Tac Toe فقط).
  • ولاية - الاستجابة لأمر get_state الأصل (Tic Tac Toe, Four in a Row).

كل منشورات الألعاب القابلة للنشر embeddable GAME_COMPLETED إلى الوالد مع outcome, winner, و players عند انتهاء المباراة. عند نجاح عملية التوقيع، GAME_COMPLETED يشمل أيضًا resultId و signedToken للتحقق من صحة البيانات الخلفية.

مثال بدء اللعبة
json
{
  "source": "gamesiknow",
  "event": "GAME_STARTED",
  "game": "tic-tac-toe",
  "partnerId": "partner_your_tenant",
  "campaignId": "homepage-widget",
  "mode": "ai"
}
مثال GAME_COMPLETED
json
{
  "source": "gamesiknow",
  "event": "GAME_COMPLETED",
  "game": "tic-tac-toe",
  "resultId": "res_abc123xyz",
  "partnerId": "partner_your_tenant",
  "campaignId": "homepage-widget",
  "status": "completed",
  "outcome": "player_1",
  "score": 100,
  "durationSeconds": 24,
  "winnerPlayerId": "player_1",
  "winnerPlayerName": "Player X",
  "winner": {
    "playerId": "player_1",
    "participant": "player_1",
    "type": "human",
    "label": "Player 1",
    "name": "Player X",
    "score": 100
  },
  "players": [
    {
      "playerId": "player_1",
      "participant": "player_1",
      "type": "human",
      "label": "Player 1",
      "name": "Player X",
      "score": 100,
      "status": "winner"
    },
    {
      "playerId": "player_2",
      "participant": "ai_bot",
      "type": "ai",
      "label": "AI BOT",
      "name": "AI Bot",
      "score": 60,
      "status": "lost"
    }
  ],
  "signedToken": "eyJ..."
}

قيم النتائج

player_1

فاز أول لاعب بشري.

player_2

فاز اللاعب البشري الثاني.

ai_bot

فاز الخصم AI.

يرسم

لا يوجد فائز.

أوامر Parent-to-iframe

مدعوم على Tic Tac Toe و Four in a Row فقط. استهدف نافذة المحتوى iframe باستخدام اسم اللعبة والإجراء.

إعادة ضبط الحالة أو طلبها
js
// Parent page -> iframe (Tic Tac Toe or Four in a Row)
const iframe = document.querySelector("iframe");
iframe.contentWindow.postMessage(
  { game: "tic-tac-toe", action: "reset" },
  "https://gamesiknow.com"
);

iframe.contentWindow.postMessage(
  { game: "tic-tac-toe", action: "get_state" },
  "https://gamesiknow.com"
);
7. التنفيذ

مستمع تكامل العينة

انسخ هذا المستمع إلى الصفحة التي تستضيف iframe. وهو يتعامل مع حالة الجاهزية، وبدء اللعبة، وأحداث اللعب، والإكمال الموقّع، وتغييرات ملء الشاشة.

مستمع الصفحة الرئيسية الموحدة

قم بالتصفية حسب المصدر، وتعامل مع GAME_STARTED و GAME_COMPLETED لعرض واجهة المستخدم الخاصة بالفائز وأحداث اللعب أثناء المباراة.

js
/**
 * Games I Know embed listener (parent page)
 * Handles lifecycle events (GAME_STARTED, GAME_COMPLETED) and
 * version 1 gameplay events (move, mode_change, ...).
 */
const TRUSTED_ORIGIN = "https://gamesiknow.com"; // or your self-hosted origin

window.addEventListener("message", (event) => {
  if (TRUSTED_ORIGIN !== "*" && event.origin !== TRUSTED_ORIGIN) return;

  const data = event.data;
  if (!data || data.source !== "gamesiknow") return;

  // --- Lifecycle events (flat top-level event name) ---
  if (data.event === "GAME_STARTED") {
    console.log("Match started", {
      game: data.game,
      mode: data.mode,
      partnerId: data.partnerId,
      campaignId: data.campaignId,
    });
    return;
  }

  if (data.event === "GAME_COMPLETED") {
    const winnerLabel = data.winner?.name ?? data.winnerPlayerName ?? null;
    console.log("Match completed", {
      game: data.game,
      outcome: data.outcome, // player_1 | player_2 | ai_bot | draw
      winner: data.winner,
      winnerName: winnerLabel,
      players: data.players,
    });

    if (winnerLabel) {
      document.getElementById("game-winner")!.textContent = `${winnerLabel} won!`;
    } else if (data.outcome === "draw") {
      document.getElementById("game-winner")!.textContent = "Draw";
    }

    // For rewards: send resultId + signedToken to YOUR backend (never call verify from the browser)
    if (data.resultId && data.signedToken) {
      fetch("/api/reward-winner", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          resultId: data.resultId,
          signedToken: data.signedToken,
          userId: currentUserId,
        }),
      });
    }
    return;
  }

  if (data.event === "EMBED_FULLSCREEN_CHANGE") {
    document.body.classList.toggle("embed-fullscreen-active", Boolean(data.payload?.active));
    return;
  }

  // --- Gameplay events (version 1 envelope) ---
  if (data.version === 1 && typeof data.event === "string") {
    switch (data.event) {
      case "ready":
        resizeEmbed(data.payload?.embedHeight);
        break;
      case "mode_change":
        console.log("Mode changed", data.payload?.mode);
        break;
      case "move":
        console.log("Move", data.payload);
        break;
      default:
        console.log("Gameplay event", data.event, data.payload);
    }
  }
});

function resizeEmbed(height) {
  const iframe = document.querySelector('iframe[src*="/embed/"]');
  if (iframe && typeof height === "number") iframe.style.height = `${height}px`;
}

قائمة التحقق من التكامل

  • اعرض لافتة "اللعبة قيد التقدم" على GAME_STARTED.
  • اعرض اسم الفائز من GAME_COMPLETED.winner أو GAME_COMPLETED.winnerPlayerName.
  • قم بإرسال resultId و signedToken إلى الواجهة الخلفية الخاصة بك؛ تحقق من ذلك باستخدام مفتاح خادم الشريك قبل منح المكافآت.
  • يمكنك اختيارياً التحقق من صحة event.origin مقابل مضيفك Games I Know.
8. الأمن

نتائج اللعبة الموثقة API

استخدم GAME_COMPLETED في الصفحة الرئيسية لعرض الفائز. للحصول على المكافآت، تحقق من النتائج الموقعة من خادمك باستخدام مفتاح خادم الشريك - لا تستخدم أبدًا التحقق API من المتصفح JavaScript.

تحقق من النتيجة الموقعة

من جانب الخادم فقط. استخدم resultId و signedToken من GAME_COMPLETED مع Authorization: Bearer gik_psk_…

http
POST https://api.gamesiknow.com/embed/results/verify
Authorization: Bearer gik_psk_your_secret_key
Content-Type: application/json

{
  "resultId": "res_abc123xyz",
  "signedToken": "signed_token_from_game_completed"
}

Call from your backend server only. The partner server key must belong to the same tenant as the signed result. Browser requests are rejected.
تم التحقق من الاستجابة بنجاح
json
{
  "ok": true,
  "resultId": "res_abc123xyz",
  "partnerId": "partner_your_tenant",
  "gameSlug": "tic-tac-toe",
  "outcome": "player_1",
  "score": 100,
  "durationSeconds": 24
}
مثال على معالج مكافآت الواجهة الخلفية

يستقبل نظامك الخلفي الرموز المميزة من الصفحة الرئيسية، ويتحقق منها باستخدام Games I Know، ثم يمنح المكافأة.

js
// Example: Node.js / Express handler on YOUR server
app.post("/api/reward-winner", async (req, res) => {
  const { resultId, signedToken, userId } = req.body;

  const verify = await fetch("https://api.gamesiknow.com/embed/results/verify", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: `Bearer ${process.env.GAMESIKNOW_PARTNER_SERVER_KEY}`,
    },
    body: JSON.stringify({ resultId, signedToken }),
  });

  if (!verify.ok) return res.status(403).json({ error: "Invalid result" });

  const result = await verify.json();
  if (result.outcome !== "player_1") {
    return res.status(400).json({ error: "Player did not win" });
  }

  await grantReward(userId, result);
  return res.json({ ok: true });
});
9. التحليلات

أحداث التحليلات من جانب الخادم

يسجل Games I Know هذه الأحداث تلقائيًا عند تحميل iframe وتفاعل اللاعبين. تظهر هذه الأحداث في لوحة تحكم الشركاء. لجلب البيانات نفسها إلى قاعدة بياناتك الخاصة، أنشئ مفتاح خادم الشركاء في صفحة التثبيت، ثم استدعِ الأمر GET /partners/analytics من خادم الواجهة الخلفية فقط.

  • تم تحميل embed_ - كل لعبة قابلة للتشغيل embed عند التحقق من صحة التكوين أو السماح بتشغيل iframe.
  • بدأت اللعبة - كل لعبة قابلة للتنزيل embed عند بدء اللعب (يتم تسجيلها تلقائيًا بواسطة iframe).
  • اكتملت اللعبة - كل لعبة قابلة للتنفيذ باستخدام embed تنجح عند تنفيذ POST /embed/results.
  • بدأت مباراة الذكاء الاصطناعي - تم استهلاك حصة AI من خلال POST /embed/ai-matches/start.
  • embed_blocked - تم رفض الوصول إلى النطاق أو الشريك أو اللعبة.
تصدير التحليلات إلى نظامك الخلفي (يلزم مفتاح خادم الشريك)

أنشئ مفتاح خادم الشريك في لوحة تحكم الشركاء ← التثبيت. خزّنه كسرّ خادم. استخدم معلمات الاستعلام أدناه لتصفية البيانات المُصدّرة.

http
طلب GET إلى https://api.gamesiknow.com/partners/analytics
التفويض: Bearer gik_psk_your_secret_key

معاملات الاستعلام الاختيارية:
domain اسم مضيف الموقع الإلكتروني المسجل (example.com)
campaignId القيمة من معامل campaignId الخاص بك في iframe
gameSlug tic-tac-toe | four-in-a-row | bingo | i-know
from تاريخ البدء بتوقيت UTC (YYYY-MM-DD)
to تاريخ الانتهاء بتوقيت UTC (YYYY-MM-DD)

مثال:
/partners/analytics?domain=www.example.com&gameSlug=tic-tac-toe&from=2026-05-01&to=2026-05-31

يُرجى إجراء هذا الطلب من خادم الواجهة الخلفية فقط. لا تُفصح عن مفتاح خادم الشريك في المتصفح JavaScript.
10. الكتالوج

مصفوفة قدرات اللعبة

ترسل جميع الألعاب القابلة للتنزيل عبر embeddable نفس الأحداث الأساسية. قارن التوقيت والميزات الإضافية لكل لعبة أدناه.

لعبةبدأت اللعبةإشارة اكتمالالتوقيعAI إجباريHeightأوامر الوالدين
Tic Tac Toeالخطوة الأولى أو بداية AIاكتملت اللعبةنعمنعم640pxإعادة الضبط، الحصول على الحالة
Four in a Rowالخطوة الأولى أو بداية AIاكتملت اللعبةنعمنعم640pxإعادة الضبط، الحصول على الحالة
Bingoتبدأ المباراة (AI أو PvP)اكتملت اللعبةنعمنعم640pxلا يوجد حتى الآن
I Knowتبدأ المباراة (AI أو PvP)اكتملت اللعبةنعمنعم640pxلا يوجد حتى الآن
11. الأدلة

أدلة إعداد المنصة وحالات الاستخدام

هذه الصفحة هي المرجع التقني. استخدم هذه الأدلة عندما تحتاج إلى خطوات تثبيت خاصة بمنصة معينة أو نصائح حول التثبيت الرأسي. تستخدم جميع الأدلة نفس نموذج iframe ونموذج الأحداث الموثق أعلاه.

Developer frameworks

Framework-specific iframe placement, event listeners, and production notes.

Website builders and CMS

Copy-paste embed guides for no-code and low-code site builders.

Use-case guides

Placement and UX recommendations for common website types.

هل تبحث عن صفحات نظرة عامة مثل ألعاب iframe، أو أدوات HTML5، أو ألعاب embeddable المجانية؟ تصفح الكل embed أدلة على المحور.

12. الدعم

الأسئلة الشائعة

إجابات عن تفاصيل التكامل، ودعم اللعبة الحالي، والأوامر، والنتائج الموقعة، وتوافق اللعبة في المستقبل.

هل يمكنني embed Games I Know ألعاب في WordPress أو Webflow أو Wix أو Squarespace أو موقع ويب مخصص؟

نعم. تستخدم عناصر Games I Know و embed معيار iframe HTML، لذا فهي تعمل في كتل HTML المخصصة في ووردبريس، وعناصر embed في ويب فلو، ومساحات التعليمات البرمجية المخصصة في ويكس وسكوير سبيس، وHTML الثابت، ورياكت، و Next.js، وغيرها من المواقع المخصصة. سجّل نطاق الموقع الإلكتروني في لوحة تحكم الشركاء أولاً، ثم الصق مقتطف الإطار المُنشأ في الصفحة التي تريد ظهور اللعبة فيها.

ما الفرق بين /embed/{gameSlug}/ و /embed/{gameSlug}/frame/؟

/embed/{gameSlug}/ هي الصفحة الرئيسية للعبة embed. /embed/{gameSlug}/frame/ هو وقت تشغيل iframe الذي يجب لصقه في موقعك الإلكتروني. استخدم دائمًا عنوان URL /frame/ في كود iframe لأنه يقوم بتحميل اللعبة القابلة للعب، والتحقق من صحة اسم المستأجر والنطاق، وإرسال أحداث الصفحة الرئيسية.

هل تعمل ألعاب Games I Know iframe على الهاتف المحمول وسطح المكتب؟

نعم. تم تصميم ألعاب Games I Know و iframe لتتوافق مع متصفحات الهواتف المحمولة والأجهزة اللوحية وأجهزة الكمبيوتر المحمولة والمكتبية. استخدم العرض "100%" والارتفاع الموصى به حوالي 640 بكسل لمعظم embed. يمكنك أيضًا الاستماع إلى حدث الجاهزية واستخدام payload.embedHeight إذا كنت ترغب في أن تقوم صفحتك الرئيسية بتغيير حجم iframe تلقائيًا.

كم تبلغ تكلفة embed Games I Know الألعاب؟

تُعدّ Games I Know وiframe وembed مجانية خلال المرحلة التجريبية لـ embed. لا يُشترط وجود بطاقة ائتمان للبدء، كما أن النسخ التجريبية الحالية من embed لا تتضمن إعلانات. أنشئ حساب شريك مجاني، وسجّل نطاقك، ثم أنشئ مقتطف iframe من لوحة التحكم.

هل أحتاج إلى حساب شريك أو مفتاح embed؟

نعم. يمنحك حساب الشريك معرّف مستأجر ومقتطف iframe مقيد بالنطاق. يرسل iframe معرّف المستأجر مع عنوان URL للإطار حتى يتمكن Games I Know من التحقق من الشريك، والنطاق المسموح به، وإمكانية الوصول إلى اللعبة، وحصة AI، وحملة التحليلات، وآلية التحقق من النتائج.

هل يمكن لأحد نسخ كود iframe الخاص بي واستخدامه على موقع ويب آخر؟

يخضع embed لقيود النطاق. إذا قام شخص ما بنسخ مقتطف iframe الخاص بك إلى موقع ويب غير مصرح به، فإن Games I Know يتحقق من مصدر الطلب مقابل النطاقات المُكوّنة لحساب الشريك الخاص بك ويحظر الاستخدام غير المصرح به. استخدم معرّفات حملات منفصلة عندما تريد تحليلات أدق لكل موقع ويب أو حملة.

أي من ألعاب Games I Know يمكن embedded؟

تدعم Tic Tac Toe، وFour in a Row، وBingo، وI Know بروتوكولات iframe وembed حاليًا. ترسل كل لعبة عقد أحداث embed القياسي لحالة الجاهزية، وبدء اللعبة، واللعب، والإكمال، وبيانات الفائز، والتحليلات، والتحقق من النتيجة. من المتوقع أن تتبع الألعاب الجديدة القابلة للتطوير باستخدام embed نفس نمط الأحداث، حتى لا يحتاج الشركاء إلى إعادة بناء تكاملهم.

ما هي أحداث postMessage التي يرسلها Games I Know إلى الصفحة الرئيسية؟

تستخدم كل لعبة قابلة للتنزيل (embeddable) تنسيقين لرسائل postMessage. تستخدم أحداث دورة الحياة شكلاً بسيطاً مع المصدر: gamesiknow وقيم الأحداث مثل ready وGAME_STARTED وGAME_COMPLETED وEMBED_FULLSCREEN_CHANGE. أما أحداث اللعب فتستخدم الإصدار: 1 مع أسماء أحداث متداخلة مثل ready وmode_change وmove وreset وundo وstate. يجب دائماً تصفية البيانات بناءً على data.source === "gamesiknow".

هل يمكنني تتبع بدايات المباريات، وإكمالها، والفائزين، ونتائج اللاعبين من لعبة embedded؟

نعم. استمع إلى إشارة GAME_STARTED عند بدء المباراة، واستخدم أحداث اللعب مثل التحرك وتغيير الوضع أثناء اللعب، واستخدم إشارة GAME_COMPLETED عند انتهاء المباراة. تتضمن إشارة GAME_COMPLETED النتيجة، والفائز، واللاعبين، والنتيجة، والمدة، ومعرفات النتيجة حيثما كان التوقيع متاحًا. كما تسجل تحليلات جانب الخادم عمليات التحميل، والبدء، والإكمال، والمحاولات المحظورة، ونقرات أزرار الحث على اتخاذ إجراء.

ما هو حدث الإكمال الذي يجب أن أستخدمه في جميع الألعاب؟

استخدم حدث GAME_COMPLETED عند انتهاء المباراة. تُرسل كل لعبة قابلة للتغيير (embeddable) هذا الحدث مع النتيجة، والفائز، واسم اللاعب الفائز، واللاعبين. عندما يتضمن GAME_COMPLETED معرّف النتيجة (resultId) والرمز المميز المُوقّع (signedToken)، أرسلهما إلى خادمك الخلفي، ثم استدعِ طلب POST إلى /embed/results/verify باستخدام مفتاح خادم الشريك قبل منح المكافآت أو الرصيد.

كيف يمكنني الاستماع إلى أحداث embed من iframe على موقعي الإلكتروني؟

أضف window.addEventListener("message", handler) إلى الصفحة التي تستضيف iframe. في معالج الأحداث، تجاهل الرسائل إلا إذا كان event.data.source يساوي "gamesiknow". استخدم event.data.event للأحداث المتعلقة بدورة حياة التطبيق، أو event.data.event بالإضافة إلى event.data.version يساوي 1 لأحداث اللعب. يمكنك اختياريًا التحقق من صحة event.origin مقابل مصدر Games I Know المسموح به.

كيف يمكنني التحقق من نتائج اللعبة قبل منح النقاط أو الجوائز أو فتح العناصر؟

استخدم GAME_COMPLETED في الصفحة الرئيسية لعرض الفائز فورًا (النتيجة، الفائز، اسم اللاعب الفائز، اللاعبون). للحصول على المكافآت، أرسل resultId وsignedToken من GAME_COMPLETED إلى خادمك، ثم أرسل طلب POST إلى /embed/results/verify مع Authorization: Bearer gik_psk_… باستخدام مفتاح خادم الشريك من لوحة التحكم. نقطة التحقق تعمل على الخادم فقط - لا تستخدمها أبدًا من المتصفح JavaScript. امنح المكافآت فقط بعد نجاح التحقق.

ما هي معلمات عنوان URL iframe التي يدعمها Games I Know؟

مطلوب: معرّف المستأجر (معرّف مستأجر شريكك). اختياري: mode=ai لطلب وضع AI الإجباري عند السماح بالحصة، و campaignId لتقسيم التحليلات. عناوين URL للإطارات تتبع /embed/{gameSlug}/frame/?tenantId=YOUR_TENANT_ID.

هل يمكنني إجبار لعبة embedded على البدء في وضع AI؟

نعم. أضف mode=ai إلى عنوان URL الخاص بـ iframe لطلب وضع AI أولاً. لا تزال قواعد الحصص والنطاق الخاصة بالخادم سارية، لذا يمكن لـ embed اللجوء إلى اختيار اللاعب أو اللعب ضد لاعبين آخرين عندما يكون وضع AI غير متاح أو عند استنفاد الحصة.

هل يمكنني إرسال أوامر إلى Games I Know iframe؟

يقبل كل من Tic Tac Toe و Four in a Row رسائل من الجهاز الرئيسي مع تعيين اسم اللعبة إلى اسم اللعبة المختصر، وتعيين الإجراء إلى إعادة الضبط أو الحصول على الحالة. يستجيب iframe بحدث حالة اللعب. أما ألعاب embed الأخرى فلا تعرض أوامر الجهاز الرئيسي حتى الآن.

قائمة التحقق من الإنتاج

تأكد من أن نطاق الموقع الإلكتروني نشط قبل إنشاء رمز مميز.

استخدم رمزًا مميزًا أو معرف حملة منفصل لكل موقع ويب أو مجموعة حملات.

استمع إلى GAME_STARTED و GAME_COMPLETED في الصفحة الرئيسية.

حافظ على العلامة التجارية Games I Know مرئية داخل embed.

تحقق من النتائج الموقعة في نظامك الخلفي قبل منح الجوائز أو الاعتمادات.

تم فرض وضع AI في الاختبار والرجوع إلى PvP عند استنفاد حصة AI.

هل تحتاج إلى مساعدة في دمج الشركاء؟

شاركنا الموقع الإلكتروني، ونظام إدارة المحتوى، وموقع اللعبة المطلوب. يمكننا مراجعة إعدادات حدث embed معك.

تواصل مع الدعم