SDK

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

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

القدرات المتاحة:

الإجراء	الوصف
GET_PROFILE	الحصول على ملف المستخدم الحالي
PURCHASE	إجراء عملية شراء (مثل الشراء داخل التطبيق)
STORAGE_SET	كتابة تخزين المفاتيح/القيم المحلي (لحفظ الإعدادات، التقدم، إلخ)
STORAGE_GET	قراءة تخزين المفاتيح/القيم المحلي (لاسترجاع البيانات المحفوظة سابقًا)
ADD_SCORE	رفع نتيجة (للوائح المتصدرين/المشاركة، إلخ)

أمثلة الدمج

توضح الأمثلة التالية كيفية إدراج الـ SDK في الصفحة واستدعاء قدراته.

1.1 إدراج الكود

الطريقة 1: تضمين الملف المُجمَّع مباشرة عبر وسم <script>

<script src="https://play.letskix.com/res/game/sdk-js/GameTokSDK.js"></script>
<script>
  // متاح على النطاق العام (Global)
  console.log('GameTokSDK version loaded:', !!window.GameTokSDK);
</script>

1.2 أمثلة الاستخدام

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

• الحصول على ملف المستخدم

// مثال الاستدعاء
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",
    "level": 0,
    "gender": 0,
    "testAccount": true,
    "guest": true
  }
}

• إجراء عملية شراء (مثل شراء عنصر)

// مثال الاستدعاء
GameTokSDK.purchase({ productId: 'HAB.WATER.10.COINS' })
  .then(({ data }) => {
    console.log('تمت عملية الشراء بنجاح:', data);
  })
  .catch((e) => {
    console.error('فشلت عملية الشراء:', e);
  });

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

{
  "action": "PURCHASE",
  "error": false,
  "data": {
    "purchase_result_code": 0, // رمز النتيجة
    "test_account": false,      // هل المستخدم حساب اختبار أو مُراجع المنصة
    "user_coins": 22514         // رصيد عملات المستخدم
  }
}

// قيم purchase_result_code:
// 0: تم الشراء بنجاح
// 11: product_id غير صحيح
// 12: رصيد العملات غير كافٍ للمستخدم
// 13: reference_id مكرر أو غير صالح
// 14: المستخدم ضيف؛ الضيوف لا يمكنهم إجراء عمليات شراء
// 20: أخطاء أخرى

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

// ملاحظة: يمكن أن تكون القيمة (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
}

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

// مثال الاستدعاء
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
    }
  }
}

• إضافة نتيجة

// المعاملات: score رقم؛ و scoreType فئة (تحددها أعمالك)
// مثال الاستدعاء
GameTokSDK.addScore({ score: 10, scoreType: 'daily' })
  .then(() => {
    console.log('تمت إضافة النتيجة بنجاح');
  })
  .catch((e) => {
    console.error('فشل إضافة النتيجة:', e);
  });

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

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

ملاحظة: يعرض هذا المستند أسلوبي then/catch و async/await؛ جميع الدوال تُعيد Promise.

المعاملات وبنية الاستجابة

• أمثلة المعاملات العامة (للاطلاع؛ المعاملات الدقيقة تعتمد على كل قدرة):

  • getProfile: لا شيء (غالبًا لا يحتاج إلى معاملات إضافية)
  • purchase: { productId: string }
  • storageSet: { key: string, value: any }
  • storageGet: { key: string }
  • addScore: { score: number, scoreType: string }

• بنية الاستجابة الموحدة عند النجاح:

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

• سلوك الفشل:
  • سيتم رفض Promise بكائن Error.
  • يُنصح بتسجيل الخطأ داخل .catch والمحاولة مرة أخرى أو إبلاغ المستخدم.

ملاحظات مهمة

لضمان عمل الـ SDK بشكل صحيح، يرجى عدم الكتابة فوق أو حذف الكائن العام التالي:

• window.GameTokSDK (واجهة الـ SDK الرئيسية)

مثال (استخدام خاطئ؛ لا تنسخه):

// خطر! سيتسبب في فشل التواصل مع iOS أو Android
window.GameTokSDK = {};
window.GameTokSDK = null;
delete window.GameTokSDK;

مثال سير كامل (then/catch)

// الحصول على ملف المستخدم
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: 'mission' })
  .then(() => {
    console.log('تمت إضافة النتيجة');
  })
  .catch((e) => {
    console.error('فشل إضافة النتيجة:', e);
  });

مثال سير كامل (async/await)

(async () => {
  // الحصول على ملف المستخدم
  try {
    const profileResp = await GameTokSDK.getProfile({});
    console.log('Profile:', profileResp.data);
  } catch (e) {
    console.error('فشل الحصول على الملف الشخصي:', e);
  }

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

  // قراءة بيانات
  try {
    const getResp = await GameTokSDK.storageGet({ key: 'config' });
    console.log('Config:', getResp.data.value);
  } catch (e) {
    console.error('فشلت القراءة:', e);
  }

  // مثال شراء
  try {
    const payResp = await GameTokSDK.purchase({ productId: 'HAB.WATER.10.COINS' });
    console.log('purchase:', payResp.data);
  } catch (e) {
    console.error('فشلت عملية الشراء:', e);
  }

  // مثال إضافة نتيجة
  try {
    await GameTokSDK.addScore({ score: 5, scoreType: 'mission' });
    console.log('تمت إضافة النتيجة');
  } catch (e) {
    console.error('فشل إضافة النتيجة:', e);
  }
})();