SDK

يوفّر هذا الـ SDK قناة اتصال آمنة ثنائية الاتجاه بين اللعبة والعميل الأصلي (iOS وAndroid)، لتمكين مطوري الطرف الثالث من استدعاء القدرات الأصلية.

اسم واجهة الـ API العامة: window.GameTokSDK

القدرات المتوفرة:

الإجراء	الوصف
GET_PROFILE	جلب ملف المستخدم الحالي
PURCHASE	بدء عملية شراء (مثل الشراء داخل التطبيق)
STORAGE_SET	كتابة تخزين مفاتيح/قيم محلي (إعدادات، تقدّم، إلخ)
STORAGE_GET	قراءة تخزين مفاتيح/قيم محلي (البيانات المحفوظة سابقًا)
ADD_SCORE	إرسال نتيجة (لوائح المتصدرين، مشاركة، إلخ)
GET_PERMISSION_MIC	طلب إذن الميكروفون (أندرويد)
TOPUP	شحن الرصيد عند نقص العملات داخل اللعبة؛ يفتح تدفق الشحن في العميل
ROUND_START	إشعار بداية الجولة (مرة عند بدء كل جولة؛ مرتبط بسياسات المنصة للجولات/الطاقة)
ROUND_END	إشعار نهاية الجولة (عند انتهاء الجولة؛ يجب أن يطابق round_id إشعار ROUND_START لنفس الجولة)
onAudioSuspend	الاستماع لحدث تعليق الصوت (يُطلق عندما تطلب المنصة من اللعبة الكتم)
offAudioSuspend	إزالة مستمع حدث تعليق الصوت
onAudioResume	الاستماع لحدث استئناف الصوت (يُطلق عندما تسمح المنصة للعبة باستعادة الصوت)
offAudioResume	إزالة مستمع حدث استئناف الصوت

أمثلة الدمج

يوضّح ما يلي كيفية تضمين الـ SDK في الصفحة واستدعاء كل قدرة.

1.1 تضمين السكربت

الطريقة الأولى: تحميل الحزمة عبر <script>

<script src="https://play.letskix.com/res/game/sdk-js/GameTokSDK.js"></script>
<script>
  console.log('GameTokSDK version loaded:', !!window.GameTokSDK);
</script>

التطوير المحلي (الصفحة غير مضمّنة في التطبيق، التصحيح في المتصفح): بعد تحميل الـ SDK استدعِ GameTokSDK.enableMock()؛ واجهات الـ Promise ستستخدم بيانات محاكاة مدمجة دون الحاجة للعميل الأصلي. لا تستدعِها في الإنتاج أو نسخ المتجر، وإلا سيرى المستخدمون بيانات وهمية.

<script src="https://play.letskix.com/res/game/sdk-js/GameTokSDK.js"></script>
<script>
  GameTokSDK.enableMock();
</script>

الاختبار على جهاز حقيقي (WebView داخل التطبيق): عند الحاجة للسجلات، بعد تحميل الـ SDK استدعِ GameTokSDK.enableDebug() (تُعيد Promise؛ تُحمّل vConsole في الصفحة وتُسجّل تبادلات الجسر مع الأصل). لا تستخدمها مع enableMock في آن واحد.

<script src="https://play.letskix.com/res/game/sdk-js/GameTokSDK.js"></script>
<script>
  GameTokSDK.enableDebug();
</script>

1.2 أمثلة الاستدعاء

تستخدم الأمثلة أسلوب then / catch مع الـ Promise. عند النجاح يُعاد كائن استجابة موحّد؛ عند الفشل يُرفض الـ Promise.

1.2.1 جلب الملف الشخصي

// مثال استدعاء
GameTokSDK.getProfile()
  .then(({ action, error, data }) => {
    console.log('تم جلب الملف الشخصي:', data);
  })
  .catch((e) => {
    console.error('فشل جلب الملف الشخصي:', e);
  });

مثال الاستجابة (JSON):

{
  "action": "GET_PROFILE",
  "error": false,
  "data": {
    "uid": 1234567,
    "avatar": "https://profile-file-pre.lobah.net/files/2024/11/15/3/fd1c01ac6640466f92a59c0aaa6b0112_lp_profile_img_frame_male_17.png",
    "userName": "Tim tim",
    "userCoins": 0,
    "level": 0,
    "gender": 0,
    "testAccount": true,
    "guest": true
  }
}

1.2.2 الشراء داخل التطبيق (مثل شراء عنصر)

/**
 * شراء داخل التطبيق
 * @param productId معرّف المنتج؛ يجب تعريفه مسبقًا في لوحة المطور (https://developer.lobah.net/)
 */
GameTokSDK.purchase({ productId: 'HAB.WATER.10.COINS' })
  .then(({ data }) => {
    // يُحدَّد النجاح أو الفشل من الرمز المُعاد هنا
    console.log('اكتملت عملية الشراء:', data);
  })
  .catch((e) => {
    console.error('خطأ:', e);
  });

مثال الاستجابة (JSON):

{
  "action": "PURCHASE",
  "error": false,
  "data": {
    "purchaseResultCode": 0,
    "testAccount": false,
    "userBalance": 22514
  }
}

قيم purchaseResultCode:

• 0: نجاح الشراء
• 11: product_id غير صحيح
• 12: رصيد العملات غير كافٍ
• 13: reference_id مكرر أو غير صالح
• 14: المستخدم ضيف؛ الضيوف لا يمكنهم الشراء
• 16: product_id غير صحيح
• 20: خطأ آخر

1.2.3 تخزين مفتاح/قيمة

/**
 * تخزين مفتاح/قيمة
 * @param key   مفتاح مخصص
 * @param value قيمة؛ قد تكون نصًا أو كائنًا
 */
GameTokSDK.storageSet({ key: 'settings', value: { theme: 'dark', volume: 0.8 } })
  .then(() => {
    console.log('تم التخزين بنجاح');
  })
  .catch((e) => {
    console.error('فشل التخزين:', e);
  });

مثال الاستجابة (JSON):

{
  "action": "STORAGE_SET",
  "error": false,
  "data": null
}

1.2.4 قراءة مفتاح/قيمة

/**
 * قراءة مفتاح/قيمة
 * @param key المفتاح المعرّف مسبقًا
 */
GameTokSDK.storageGet({ key: 'settings' })
  .then((result) => {
    console.log('قراءة ناجحة:', result.data.value); // كائن أو نص
  })
  .catch((e) => {
    console.error('فشلت القراءة:', e);
  });

مثال الاستجابة (JSON):

{
  "action": "STORAGE_GET",
  "error": false,
  "data": {
    "value": {
        "theme": "dark",
        "volume": 0.8
    }
  }
}

1.2.5 إرسال النتيجة

/**
 * حسب اللعبة قد تُرسل نتيجة، مرحلة، أو مستوى.
 * للنتيجة: { score: 300, scoreType: 'score', remark: 'score' }
 * للمستوى: { score: 1, scoreType: 'level', remark: 'level' }
 * @param score     القيمة المطلوب إرسالها؛ عدد صحيح موجب
 * @param scoreType فئة البيانات (وصف يحدده العمل)
 * @param remark    ملاحظة اختيارية (قد تطابق scoreType)
 */

GameTokSDK.addScore({ score: 10, scoreType: 'score', remark: 'score' })
  .then(() => {
    console.log('تم إرسال النتيجة');
  })
  .catch((e) => {
    console.error('فشل الإرسال:', e);
  });

مثال الاستجابة (JSON):

{
  "action": "ADD_SCORE",
  "error": false,
  "data": null
}

1.2.6 إذن الميكروفون

/**
 * طلب إذن الميكروفون (أندرويد)
 * للاستخدام داخل اللعبة لطلب الإذن (مثل الميزات الصوتية).
 * بلا قيمة إرجاع؛ يُظهر فقط واجهة الأذونات الأصلية.
 */
GameTokSDK.getPermissionMic();

1.2.7 الشحن (TOPUP)

مهم: إلغاء المستخدم، فشل الدفع، وما شابه ما زالت تُحلّ عبر then. داخل then افحص data.code لمعرفة النجاح. catch مخصّص لأعطال الـ SDK، انتهاء المهلة، وما شابه.

/**
 * شحن الرصيد
 * @param amount المبلغ (الوحدات حسب الاتفاق مع العميل)
 */
GameTokSDK.topup({ amount: 100 })
  .then(({ action, error, data }) => {
    const code = data && data.code;
    if (code === 200) {
      console.log('نجح الشحن:', data);
    } else {
      console.warn('الشحن غير مكتمل أو فشل، الرمز:', code, data);
    }
  })
  .catch((e) => {
    console.error('خطأ في طلب الشحن (مثل عدم توفر الـ SDK):', e);
  });

مثال الاستجابة (JSON، نجاح):

{
  "action": "TOPUP",
  "error": false,
  "data": {
    "code": 200,
    "message": "ok"
  }
}

قيم code:
200 نجاح
401 فشل الشحن (خطأ)
402 فشل الشحن (إلغاء من المستخدم)

1.2.8 بداية الجولة (ROUND_START)

يُستدعى مرة واحدة بعد بدء الجولة فعليًا. round_id إلزامي (معرّف فريد للجولة من جهة اللعبة). اختياريًا timestamp (بالميلي ثانية؛ إن حُذف يُستخدم الوقت الحالي). بلا إرجاع Promise — إرسال دون انتظار.

/**
 * إشعار بداية الجولة
 * @param round_id معرّف فريد لهذه الجولة
 * @param timestamp اختياري، وقت البدء (ملي ثانية)
 */
GameTokSDK.roundStart({
  round_id: 'round-' + Date.now(),
  timestamp: Date.now(),
});

إن لم يُمرَّر round_id، يُحذّر الـ SDK في وحدة التحكم ولا يُرسل إلى الأصل.

1.2.9 نهاية الجولة (ROUND_END)

يُستدعى عند انتهاء الجولة. يجب أن يطابق round_id roundStart لنفس الجولة. اختياريًا timestamp. بلا إرجاع Promise.

/**
 * إشعار نهاية الجولة
 * @param round_id نفس قيمة roundStart لهذه الجولة
 * @param timestamp اختياري، وقت الانتهاء (ملي ثانية)
 */
const roundId = 'round-' + Date.now();
GameTokSDK.roundStart({ round_id: roundId });
// ... منطق الجولة ...
GameTokSDK.roundEnd({ round_id: roundId, timestamp: Date.now() });

1.2.10 مستمعو أحداث الصوت (onAudioSuspend / offAudioSuspend / onAudioResume / offAudioResume)

عندما تطلب المنصة من اللعبة الكتم (مثل دخول المستخدم غرفة بث مباشر، ورود مكالمة نظام، إلخ)، يُرسَل لها حدث تعليق الصوت؛ وعند السماح باستئناف الصوت، يُرسَل حدث الاستئناف. يجب على اللعبة إيقاف/استئناف جميع المؤثرات الصوتية والموسيقى الخلفية فور استقبال هذه الأحداث.

هذه واجهة مستمع أحداث، وليست واجهة Promise، ولا تُعيد أي قيمة.

// الاستماع لحدث تعليق الصوت
function handleAudioSuspend(payload) {
  console.log('تم استقبال إشعار الكتم:', payload);
  // كتم جميع المؤثرات الصوتية والموسيقى الخلفية في اللعبة
  myGame.muteAll();
}

GameTokSDK.onAudioSuspend(handleAudioSuspend);

// الاستماع لحدث استئناف الصوت
function handleAudioResume(payload) {
  console.log('تم استقبال إشعار استئناف الصوت:', payload);
  // استئناف جميع المؤثرات الصوتية والموسيقى الخلفية في اللعبة
  myGame.unmuteAll();
}

GameTokSDK.onAudioResume(handleAudioResume);

إزالة المستمعين:

// إزالة مستمع تعليق الصوت (مرّر نفس مرجع الدالة المستخدمة عند التسجيل)
GameTokSDK.offAudioSuspend(handleAudioSuspend);

// إزالة مستمع استئناف الصوت
GameTokSDK.offAudioResume(handleAudioResume);

معامل options.sync (مزامنة الحالة):

يدعم onAudioSuspend وonAudioResume معاملًا اختياريًا ثانيًا options، حيث يعالج sync (الافتراضي true) حالة تسجيل المستمع بعد انطلاق الحدث:

• sync: true (الافتراضي) — إذا كان الصوت في حالة تعليق/استئناف عند تسجيل المستمع، سيُستدعى رد الاتصال فوريًا مرة واحدة في المهمة الدقيقة التالية، لضمان عدم إغفال اللعبة لتغييرات الحالة السابقة.
• sync: false — يستمع فقط للأحداث الجديدة اللاحقة؛ بلا مزامنة للحالة عند التسجيل.

// الافتراضي sync: true — إذا كان الصوت معلقًا بالفعل، يُطلق رد الاتصال فورًا مرة واحدة
GameTokSDK.onAudioSuspend((payload) => {
  myGame.muteAll();
});

// تعطيل مزامنة الحالة، الاستماع للأحداث اللاحقة فقط
GameTokSDK.onAudioSuspend((payload) => {
  myGame.muteAll();
}, { sync: false });

الاستخدام الموصى به: سجّل المستمعين في أقرب وقت ممكن خلال مرحلة تهيئة اللعبة، مع إبقاء sync: true (الافتراضي)، بحيث تتمكن اللعبة من مزامنة الحالة بشكل صحيح حتى لو أرسلت المنصة تعليمات الكتم قبل التسجيل.

المعاملات وشكل الاستجابة

• أمثلة معاملات شائعة (مرجعية؛ التفاصيل لكل واجهة):
  • getProfile: `` (غالبًا بلا معاملات إضافية)
  • purchase: { productId: string }
  • storageSet: { key: string, value: any }
  • storageGet: { key: string }
  • addScore: { score: number, scoreType: string }
  • getPermissionMic: `` (غالبًا بلا معاملات إضافية)
  • topup: { amount: number, ... } (حقول أخرى حسب بروتوكول العميل)
  • roundStart / roundEnd: { round_id: string, timestamp?: number }
  • onAudioSuspend / onAudioResume: (handler: Function, options?: { sync?: boolean })
  • offAudioSuspend / offAudioResume: (handler: Function)
• عند النجاح، الاستجابة الموحّدة:

{
  action: string;      // اسم الإجراء (مثل 'GET_PROFILE')
  error: false;        // false عند النجاح (عند الفشل يُرفض الـ Promise)
  data: any;           // حمولة الأصل؛ الحقول حسب الإجراء
}

• سلوك الفشل:
  • topup: معظم نتائج العمل (نجاح/فشل/إلغاء) تُحلّ في then عبر data.code؛ catch مخصّص لأخطاء الـ SDK وانتهاء المهلة.
  • واجهات Promise الأخرى: عند الفشل يُرفض الـ Promise بكائن Error؛ يُفضّل التعامل في .catch (تسجيل، إعادة محاولة، أو تنبيه).

ملاحظات مهمة

لا تستبدل ولا تحذف الكائنات العامة التالية وإلا يتعطّل الـ SDK:

• window.GameTokSDK (نقطة الدخول الرئيسية)

مثال (لا تفعل هذا):

// خطر — يعطل الجسر مع iOS / Android
window.GameTokSDK = {};
window.GameTokSDK = null;
delete window.GameTokSDK;

مثال كامل

// الملف الشخصي
GameTokSDK.getProfile({})
        .then((resp) => {
          console.log('Profile:', resp.data);
        })
        .catch((e) => {
          console.error('فشل جلب الملف الشخصي:', e);
        });

// تخزين
GameTokSDK.storageSet({ key: 'config', value: { lang: 'zh-CN' } })
        .then(() => {
          console.log('تم التخزين بنجاح');
        })
        .catch((e) => {
          console.error('فشل التخزين:', e);
        });

// قراءة
GameTokSDK.storageGet({ key: 'config' })
        .then((resp) => {
          console.log('Config:', resp.data.value);
        })
        .catch((e) => {
          console.error('فشلت القراءة:', e);
        });

// شراء
GameTokSDK.purchase({ productId: 'HAB.WATER.10.COINS' })
        .then((resp) => {
          console.log('Purchase:', resp.data);
        })
        .catch((e) => {
          console.error('فشل الشراء:', e);
        });

// نتيجة
GameTokSDK.addScore({ score: 5, scoreType: 'score' })
        .then(() => {
          console.log('Score added');
        })
        .catch((e) => {
          console.error('فشل إرسال النتيجة:', e);
        });

// الميكروفون (أندرويد، بلا إرجاع)
GameTokSDK.getPermissionMic();

// الشحن: افحص data.code في then (200 = نجاح)
GameTokSDK.topup({ amount: 100 })
        .then(({ data }) => {
          if (data && data.code === 200) {
            console.log('نجح الشحن', data);
          } else {
            console.log('لم ينجح الشحن', data);
          }
        })
        .catch((e) => console.error('خطأ في الشحن', e));

// إشعارات الجولة (نفس round_id)
const rid = 'r-' + Date.now();
GameTokSDK.roundStart({ round_id: rid });
GameTokSDK.roundEnd({ round_id: rid });

// مستمعو أحداث الصوت (يُسجَّلان خلال تهيئة اللعبة)
GameTokSDK.onAudioSuspend((payload) => {
  console.log('كتم', payload);
  myGame.muteAll();
});

GameTokSDK.onAudioResume((payload) => {
  console.log('استئناف الصوت', payload);
  myGame.unmuteAll();
});