مرجع API

يوفر خادم Lobah بعض واجهات API المفيدة، مما يسمح للعبة بالتفاعل بشكل أعمق مع اللاعبين.

ملاحظة: عندما ينشئ المطورون لعبة على منصة Lobah، سيحصلون على معلومتين: appId و appKey. يجب الحفاظ على سرية appKey لأنه معلومة حساسة.

تتضمن واجهة خادم API واجهات الخادم لعمليات شراء اللاعبين، والمكافآت، وإرسال الرسائل وغيرها من العمليات، والتي يتم توفيرها لخادم اللعبة لتحقيق تكامل عميق بين اللعبة واللاعبين.

ملاحظة: لأسباب أمنية، يسمح Server API في بيئة الإنتاج فقط لخوادم الألعاب بالوصول باستخدام عناوين IP محددة. يرجى تكوين عنوان IP لخادم اللعبة في المنصة.

عنوان Server API

عنوان Server API للعبة Lobah هو:

https://game-gateway.lobah.net

المصادقة

تستخدم واجهات API التي يوفرها خادم Lobah خوارزمية HmacMD5 للمصادقة لضمان أمان البيانات. لذلك، يحتاج خادم اللعبة الخاص بالمطور إلى حساب سلسلة المصادقة باستخدام الخوارزمية التالية في كل مرة يتم فيها إرسال طلب:

java

macMD5 ( URLEncode ( "POST" + Request path + Request parameters + Request body ), appKey )

سيؤدي المثال أعلاه إلى إنشاء محتوى السلسلة التي سيتم تشفيرها كما يلي:

http

POST/1.0/open-gateway/game/send-messageaccess_token=4d0b364bcd2e9c6243b149e2e2a2c65a&app_id=92&nonce=89e8379b&ts=1730970702&uid=1005008&zone=SA{ "content": "hello world", "id_list": [ 1005008 ], "operator": "Test Game" }

بعد ترميز السلسلة بالتشفير URL، ستكون النتيجة كما يلي:

POST%2F1.0%2Fopen-gateway%2Fgame%2Fsend-messageaccess_token%3D4d0b364bcd2e9c6243b149e2e2a2c65a%26app_id%3D92%26nonce%3D89e8379b%26ts%3D1730970702%26uid%3D1005008%26zone%3DSA%7B+%22content%22%3A+%22hello+world%22%2C+%22id_list%22%3A+%5B+1005008+%5D%2C+%22operator%22%3A+%22Test+Game%22+%7D

سلسلة المصادقة المحسوبة باستخدام HmacMD5 هي:

114921f6dd2c59477f34c76647249e3d

عند إرسال طلب POST باستخدام سلسلة المصادقة المحسوبة بالخوارزمية أعلاه، من المهم جدًا إضافة &sig=authentication_string في نهاية معلمات الطلب. لذلك، سيكون عنوان URL النهائي للطلب كما يلي:

http

https://api-test.lobah.net/1.0/open-gateway/game/send-message?access_token=4d0b364bcd2e9c6243b149e2e2a2c65a&app_id=92&nonce=89e8379b&ts=1730970702&uid=1005008&zone=SA&sig=114921f6dd2c59477f34c76647249e3d

وصف API

اختبار المصادقة

يمكن لخادم اللعبة التحقق من معلومات المصادقة من خلال واجهة اختبار المصادقة للتحقق مما إذا كانت صحيحة.

مسار الطلب: /1.0/open-gateway/game/test

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{}

جسم الاستجابة:

ok

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

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

تسمح هذه الواجهة للعبة بالحصول على معلومات اللاعب، بما في ذلك تفاصيل الملف الشخصي مثل الصورة الرمزية واسم المستخدم والعمر ورصيد Coins. يمكن استخدام هذه المعلومات لتخصيص تجربة اللعبة، وعرض البيانات ذات الصلة داخل واجهة المستخدم للعبة.

مسار الطلب: /1.0/open-gateway/game/get-profile

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{
    "app_id": "appId", 
    "token": "حقل access_token المرسل من العميل إلى اللعبة.", 
    "uid": "معرف المستخدم" 
}

جسم الاستجابة:

json

{
    "verify_status":"نتيجة التحقق.",
    "user_id": "معرف المستخدم",
    "avatar":"رابط الصورة الرمزية",
    "user_name":"اسم المستخدم",
    "user_coins": "رصيد Coins للمستخدم.",
    "level":"مستوى المستخدم",
    "gender":"جنس المستخدم"
}

لـ verify_status ثلاث قيم محتملة:

EXPIRED: انتهت صلاحية access_token للمستخدم.
LEGAL: access_token للمستخدم صالح.
ILLEGAL: access_token للمستخدم غير صالح.

gender ستكون 1 أو 2، 1 تعني أن المستخدم ذكر، 2 تعني أنثى

إذا كان session_id سلسلة فارغة، فهذا يعني أن المستخدم ليس في غرفة البث المباشر.

مثال على الطلب:

json

{
    "app_id": 92, 
    "token": "4d0b364bcd2e9c6243b149e2e2a2c65a", 
    "uid": 1005008 
}

مثال على الاستجابة:

json

{
    "verify_status":"LEGAL",
    "user_id":1005008,
    "avatar":"https://d1d7fyvslid3cf.cloudfront.net/images/2021/3/12/12/e7c6634011b84f5e9e30607b653babaf",
    "user_name":"Grevfvv",
    "user_coins":22514, 
    "level":15,
    "gender": 1
}

ملاحظة: في الإصدارات السابقة من الوثيقة، كانت get-profile تعيد الحقل session_id، والذي تم إيقافه. يرجى الحصول على session id لغرفة البث الحالية من عنوان URL للعبة أو Game SDK.

إرسال Coins إلى المستخدم

يمكن للعبة مكافأة اللاعبين بعدد معين من Coins، ويتم دفع مبلغ المكافأة من Coins المتاحة في اللعبة.

يرجى ملاحظة أن Coins التي يمكن استخدامها للمكافآت في اللعبة ودخل اللعبة عند الشراء منفصلتان.

مسار الطلب: /1.0/open-gateway/game/reward

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId",
    "rewards": [ 
        { 
            "amount": "مبلغ المكافأة", 
            "reference_id": "المعرف الذي تم إنشاؤه بواسطة خادم اللعبة، لتمييز كل سجل مكافأة.", 
            "type": "coins", 
            "uid": "معرف المستخدم"
        }
    ], 
    "session_id": "معرف غرفة البث"
}

حقل rewards هو مصفوفة، مما يسمح بإصدار عدة مكافآت في نفس الوقت.

session id اختياري. يمكن أن يكون رقمًا أو سلسلة نصية. في النهاية يتم تخزينه كرقم.

جسم الاستجابة:

json

{
"result":[
    {
        "reward_id":"معرف المكافأة",
        "reference_id":"المعرف الذي تم إنشاؤه بواسطة خادم اللعبة، لتمييز كل سجل مكافأة.",
        "status": "حالة النتيجة",
        "availableCoinsCredit": "إجمالي Coins المتاحة للمكافآت في اللعبة"
    }]
}

مصفوفة result تتوافق مع نتائج المكافآت المتعددة المحددة في حقل rewards في الطلب. يمكن للمطورين استخدام reference_id لتصفية النتائج لكل مكافأة.

القيم الممكنة لـ status هي كما يلي:

0: نجاح
11: مرفوض
12: مبلغ المكافأة 0، لم يتم اتخاذ أي إجراء
13: لا يوجد Coins كافية في اللعبة
14: نوع المكافأة غير صالح
20: خطأ آخر

مثال على الطلب:

json

{ 
    "app_id": 92, "rewards": [ 
        { 
        "amount": 10, 
        "reference_id": "6a5aca7bfc66", 
        "type": "coins", 
        "uid": 1005008 }
     ], 
    "session_id": "1234567890"
 }

مثال على الاستجابة:

json

{
    "result":[
        {
        "reward_id":"G92-1-R17309707032943514",
        "reference_id":"6a5aca7bfc66",
        "status":0, 
        "availableCoinsCredit": 10233
        }
    ]
}

دفع اللاعب

يمكن للألعاب تقديم ميزات مدفوعة للاعبين، مثل شراء العناصر أو المحاولات الإضافية.

قبل استخدام وظيفة الشراء، من الضروري الاتفاق مسبقًا مع منصة ألعاب Lobah على المنتجات التي سيتم شراؤها وأسعارها. سيستخدم اللاعبون Coins Lobah لتسوية الشراء. يمكن التحقق من رصيد Coins الذي يمتلكه اللاعب من خلال واجهة Get User Prifile.

مسار الطلب: /1.0/open-gateway/game/purchase

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId",
    "product_id": "معرف المنتج المحدد",
    "reference_id": "معرف يتم إنشاؤه بواسطة خادم اللعبة لتحديد سجل المعاملة هذا، يجب أن يكون هذا المعرف فريدًا عبر جميع المعاملات",
    "session_id": "معرف غرفة البث",
    "uid": "معرف المستخدم"
}

ملاحظة هامة: نظرًا لأن معلمة amount يسهل الخلط بينها وبين واجهات API الأخرى، ونظرًا لعادات استخدام واجهة الشراء، تم إيقاف معلمة amount في واجهة الشراء ويمكن تجاهلها. عند استخدام واجهة الشراء، يتم تحديد مبلغ Coins المدفوع من قبل اللاعب بواسطة معرف المنتج فقط.

يتم الاتفاق على product_id بين Lobah والمطور.

session id اختياري. يمكن أن يكون رقمًا أو سلسلة نصية. في النهاية يتم تخزينه كرقم.

جسم الاستجابة:

json

{
    "purchase_result_code": "رمز النتيجة",
    "balance": "الرصيد الذي تحتفظ به اللعبة",
    "user_coins": "رصيد Coins للمستخدم",
    "order_id": "معرف المعاملة، يستخدم لاسترداد الأموال"
}

نتائج purchase_result_code كما يلي:

0: تم الشراء بنجاح
10: appId غير صحيح
11: product_id غير صحيح
12: لا يوجد Coins كافية لدى المستخدم
13: reference_id مكرر أو غير صالح
20: أخطاء أخرى

مثال على الطلب:

json

{ 
    "app_id": 92, 
    "product_id": "GAME.SHOP.TEST.10COIN",   
    "reference_id": "29135edafa9d", 
    "session_id": "1234567890", 
    "uid": 1005008 
}

مثال على الاستجابة:

json

{
    "purchase_result_code":0,
    "balance":290,
    "user_coins":22514,
    "order_id":"G92-P17309707027364314"
}

استرداد الأموال

بعد عملية الشراء، يمكن تنفيذ عملية استرداد الأموال على المعاملة. بعد الاسترداد، سيتم إعادة Coins التي تم إنفاقها على الشراء إلى حساب اللاعب.

مسار الطلب: /1.0/open-gateway/game/refund

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId",
    "order_id": "معرف المعاملة الذي تم إرجاعه عند الشراء"
}

جسم الاستجابة:

json

{
    "result": "رمز النتيجة"
}

نتائج result كما يلي:

0: تم الاسترداد بنجاح
10: order_id غير صحيح
11: مرفوض
20: أخطاء أخرى

مثال على الطلب:

json

{ 
    "app_id": 92, 
    "order_id": "G92-P17309707027364314" 
}

مثال على الاستجابة:

json

{
    "result":0
}

أفضل اللاعبين

يمكن لخادم اللعبة توفير بيانات أفضل اللاعبين، وعرض لاعبي منصة Lobah على لوحة المتصدرين في اللعبة.

مسار الطلب: /1.0/open-gateway/game/top-players

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId", 
    "rankings": [
       { "uid": "معرف المستخدم", "score": "نتيجة المستخدم" }
    ] 
}

يتم ترتيب نتائج المستخدمين تنازليًا.

جسم الاستجابة:

json

{
    "ok": "boolean"
}

عندما تكون ok صحيحة، فهذا يعني أن البيانات تم كتابتها بنجاح؛ وعندما تكون خاطئة، فهذا يشير إلى حدوث خطأ.

مثال على الطلب:

json

{
    "app_id": 92, 
    "rankings": [ 
        { "uid": 1000064, "score": 98 }, 
        { "uid": 1000063, "score": 101 } 
    ] 
}

مثال على الاستجابة:

json

{
    "ok":true
}

تحديد حالة اللعب

تسمح هذه الواجهة بعرض معلومات اللاعب في علامة التبويب الخاصة باللاعبين الحاليين في الغرفة.

مسار الطلب: /1.0/open-gateway/game/mark-players

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId", 
    "rankings": [
       { 
         "uid": "معرف المستخدم",
         "score": "نتيجة المستخدم",
         "session_id": "معرف الغرفة"
       }
    ] 
}

كل استدعاء لهذه الواجهة سيكتب فوق البيانات السابقة لتسهيل التحديث.

session id هو معرف الغرفة الحالية للاعب. إذا تم تعيين معرف الغرفة، سيتم عرض اللاعبين الذين لديهم نفس معرف الغرفة في نفس الغرفة. إذا لم يتم تعيينه، سيتم عرض جميع اللاعبين.

جسم الاستجابة:

json

{
    "ok": "boolean"
}

عندما تكون ok صحيحة، فهذا يعني أن البيانات تم كتابتها بنجاح؛ وعندما تكون خاطئة، فهذا يشير إلى حدوث خطأ.

مثال على الطلب:

json

{
    "app_id": 92, 
    "rankings": [ 
        { "uid": 1000064, "score": 98, "session_id": 1234456661 }, 
        { "uid": 1000063, "score": 101, "session_id": 1234456661 } 
    ] 
}

مثال على الاستجابة:

json

{
    "ok":true
}

الحصول على قائمة المنتجات

تسمح هذه الواجهة بالحصول على معلومات المنتجات المتاحة.

مسار الطلب: /1.0/open-gateway/game/product-list

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId"
}

جسم الاستجابة:

json

{
    "products":
        [
            {
                "product_id": "معرف المنتج",
                "coins": "سعر المنتج",
                "description": "وصف المنتج"
            }
        ]
}

سيتم سرد جميع معلومات المنتجات المتاحة هنا، ويتم استخدام product_id لواجهة الشراء.

مثال على الطلب:

json

{
    "app_id": 92
}

مثال على الاستجابة:

json

{
    "products":
    [
        {"product_id":"GAME.SHOP.TEST.COIN12","coins":12,"description": ""},
        {"product_id":"GAME.SHOP.TEST.COIN34","coins":34,"description": ""}
    ]
}

المعاملات

واجهة معاملات API هي مجموعة من الواجهات التي تُستخدم لتنفيذ عمليات دفع ومكافآت متعددة لمستخدمين مختلفين خلال جلسة أو مرحلة من اللعبة، تليها تسوية لمرة واحدة.

1. بدء معاملة

مسار الطلب: /1.0/open-gateway/game/transaction/start

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId",
    "reference_id": "معرف فريد يتم إنشاؤه بواسطة خادم اللعبة لتمييز هذا الطلب."
}

ملاحظة: يجب أن يكون reference_id فريدًا؛ ستؤدي القيم المكررة إلى فشل الاستدعاء.

جسم الاستجابة:

json

{ 
    "app_id": "appId",
    "reference_id": "reference_id المرسل",
    "transaction_id": "معرف هذه المعاملة",
    "result_code": "رمز النتيجة"
}

قيم result_code:

0: تم بدء المعاملة بنجاح.
10: app_id غير صالح.
13: reference_id غير صالح أو مكرر.
20: أخطاء أخرى.

مثال على الطلب:

json

{
    "app_id": 7,
    "reference_id": "a2a8ab8cbd2b"
}

مثال على الاستجابة:

json

{
    "app_id": 7,
    "reference_id": "a2a8ab8cbd2b",
    "transaction_id": "TRX7-17434811375622102",
    "result_code": 0
}

2. التحقق من حالة المعاملة

مسار الطلب: /1.0/open-gateway/game/transaction/status

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId",
    "transaction_id": "معرف هذه المعاملة"
}

جسم الاستجابة:

json

{ 
    "app_id": "appId",
    "transaction_id": "معرف هذه المعاملة",
    "total_added_amount": "إجمالي المبلغ المرسل للمستخدمين",
    "total_deducted_amount": "إجمالي المبلغ المخصوم من المستخدمين",
    "result_code": "رمز النتيجة"
}

قيم result_code:

0: المعاملة قيد التنفيذ.
2: تم إغلاق المعاملة بالفعل.
10: app_id غير صالح.
15: transaction_id غير موجود.
20: أخطاء أخرى.

مثال على الطلب:

json

{
    "app_id": 7,
    "reference_id": "a2a8ab8cbd2b"
}

مثال على الاستجابة:

json

{
    "app_id": 7,
    "transaction_id": "TRX7-17434811375622102",
    "total_added_amount": 0,
    "total_deducted_amount": 0,
    "result_code": 0
}

3. إرسال Coins إلى المستخدم في معاملة

مسار الطلب: /1.0/open-gateway/game/transaction/add

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId",
    "transaction_id": "معرف هذه المعاملة",
    "reference_id": "معرف فريد يتم إنشاؤه بواسطة خادم اللعبة لتمييز هذا الطلب.",
    "amount": "عدد Coins لإرسالها",
    "uid": "معرف المستخدم",
    "session_id": "معرف الغرفة الحالية التي يوجد بها المستخدم"
}

جسم الاستجابة:

json

{ 
    "app_id": "appId",
    "transaction_id": "معرف هذه المعاملة",
    "reference_id": "reference_id المرسل",
    "total_added_amount": "إجمالي المبلغ المرسل للمستخدمين",
    "total_deducted_amount": "إجمالي المبلغ المخصوم من المستخدمين",
    "user_coins": "الرصيد الحالي للمستخدم",
    "uid": "معرف المستخدم",
    "result_code": "رمز النتيجة"
}

قيم result_code:

0: العملية ناجحة.
2: تم إغلاق المعاملة بالفعل؛ هذا الاستدعاء غير صالح.
10: app_id غير صالح.
13: reference_id غير صالح أو مكرر.
15: transaction_id غير موجود.
16: إجمالي المبلغ المرسل يتجاوز إجمالي المبلغ المخصوم؛ هذا الاستدعاء غير صالح.
20: أخطاء أخرى.

مثال على الطلب:

json

{
    "amount": 5, 
    "app_id": 7,  
    "transaction_id": "TRX7-17434811375622102",   
    "reference_id": "66e0702321da", 
    "session_id": 1733800215637628, 
    "uid": 1000064
}

مثال على الاستجابة:

json

{
    "app_id": 7,
    "reference_id": "66e0702321da",
    "transaction_id": "TRX7-17434811375622102",
    "total_added_amount": 5,
    "total_deducted_amount": 15,
    "user_coins":6060,
    "uid": 1000064,
    "result_code": 0
}

4. خصم Coins من المستخدم في معاملة

مسار الطلب: /1.0/open-gateway/game/transaction/deduct

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId",
    "transaction_id": "معرف هذه المعاملة",
    "reference_id": "معرف فريد يتم إنشاؤه بواسطة خادم اللعبة لتمييز هذا الطلب.",
    "amount": "عدد Coins لخصمها",
    "uid": "معرف المستخدم",
    "session_id": "معرف الغرفة الحالية التي يوجد بها المستخدم"
}

جسم الاستجابة:

json

{ 
    "app_id": "appId",
    "transaction_id": "معرف هذه المعاملة",
    "reference_id": "reference_id المرسل",
    "total_added_amount": "إجمالي المبلغ المرسل للمستخدمين",
    "total_deducted_amount": "إجمالي المبلغ المخصوم من المستخدمين",
    "user_coins": "الرصيد الحالي للمستخدم",
    "uid": "معرف المستخدم",
    "result_code": "رمز النتيجة"
}

قيم result_code:

0: العملية ناجحة.
2: تم إغلاق المعاملة بالفعل؛ هذا الاستدعاء غير صالح.
10: app_id غير صالح.
12: رصيد المستخدم غير كافٍ؛ هذا الاستدعاء غير صالح.
13: reference_id غير صالح أو مكرر.
15: transaction_id غير موجود.
20: أخطاء أخرى.

مثال على الطلب:

json

{
    "amount": 15,
    "app_id": 7,  
    "transaction_id": "TRX7-17434811375622102",   
    "reference_id": "08ec79b4c0dc", 
    "session_id": 1733800215637628, 
    "uid": 1000064
}

مثال على الاستجابة:

json

{
    "app_id": 7,
    "reference_id": "08ec79b4c0dc",
    "transaction_id": "TRX7-17434811375622102",
    "total_added_amount": 0,
    "total_deducted_amount": 15,
    "user_coins":6060,
    "uid": 1000064,
    "result_code": 0
}

5. إغلاق معاملة

مسار الطلب: /1.0/open-gateway/game/transaction/close

طريقة الطلب: POST

تنسيق البيانات: JSON

جسم الطلب:

json

{ 
    "app_id": "appId",
    "transaction_id": "معرف هذه المعاملة"
}

جسم الاستجابة:

json

{ 
    "app_id": "appId",
    "transaction_id": "معرف هذه المعاملة",
    "total_added_amount": "إجمالي المبلغ المرسل للمستخدمين",
    "total_deducted_amount": "إجمالي المبلغ المخصوم من المستخدمين",
    "result_code": "رمز النتيجة"
}

قيم result_code:

0: العملية ناجحة.
2: تم إغلاق المعاملة بالفعل.
10: app_id غير صالح.
20: أخطاء أخرى.

مثال على الطلب:

json

{ 
    "app_id": 7,   
    "transaction_id": "TRX7-17434811375622102" 
}

مثال على الاستجابة:

json

{
  "app_id": 7,
  "transaction_id": "TRX7-17434811375622102",
  "total_added_amount": 5,
  "total_deducted_amount": 15,
  "result_code": 0
}

مرجع API ​

عنوان Server API ​

المصادقة ​

وصف API ​

اختبار المصادقة ​

الحصول على ملف تعريف المستخدم ​

إرسال Coins إلى المستخدم ​

دفع اللاعب ​

استرداد الأموال ​

أفضل اللاعبين ​

تحديد حالة اللعب ​

الحصول على قائمة المنتجات ​

المعاملات ​

1. بدء معاملة ​

2. التحقق من حالة المعاملة ​

3. إرسال Coins إلى المستخدم في معاملة ​

4. خصم Coins من المستخدم في معاملة ​

5. إغلاق معاملة ​

مرجع API

عنوان Server API

المصادقة

وصف API

اختبار المصادقة

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

إرسال Coins إلى المستخدم

دفع اللاعب

استرداد الأموال

أفضل اللاعبين

تحديد حالة اللعب

الحصول على قائمة المنتجات

المعاملات

1. بدء معاملة

2. التحقق من حالة المعاملة

3. إرسال Coins إلى المستخدم في معاملة

4. خصم Coins من المستخدم في معاملة

5. إغلاق معاملة