مرجع واجهة برمجة التطبيقات (API)

يُوفّر خادم Lobah بعض واجهات برمجة التطبيقات (APIs) المفيدة، ممّا يسمح للعبة بالتفاعل بشكل أعمق مع اللاعبين.

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

تتضمن واجهة برمجة تطبيقات الخادم (Server API) واجهة برمجة التطبيقات (API) من جانب الخادم لعمليات شراء اللاعبين، والمكافآت، وإرسال الرسائل، وغيرها من العمليات، والتي تُقدَّم إلى خادم اللعبة لتحقيق تكامل عميق بين اللعبة واللاعبين.

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

عنوان واجهة برمجة تطبيقات الخادم (Server API)

عنوان واجهة برمجة تطبيقات الخادم (Server API) للعبة Lobah هو:

https://game-gateway.lobah.net

التحقق من الهوية

تستخدم واجهات برمجة التطبيقات (APIs) التي يوفرها خادم 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 مؤشرًا على صحة معلومات المصادقة.

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

تتيح واجهة برمجة التطبيقات (API) هذه للعبة الحصول على معلومات اللاعب، بما في ذلك تفاصيل ملفه الشخصي كالصورة الرمزية واسم المستخدم والعمر ورصيد العملات المعدنية. يمكن استخدام هذه المعلومات لتخصيص تجربة اللعب، وعرض البيانات ذات الصلة في واجهة مستخدم اللعبة.

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

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

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

محتوى الطلب:

json

{
    "app_id": "appId", 
    "token": "The `access_token` field passed from the client to the game.", 
    "uid": "User ID" 
}

محتوى الاستجابة:

json

{
    "verify_status":"Verification result.",
    "user_id": "User ID",
    "avatar":"Avatar URL",
    "user_name":"User name",
    "user_coins": "User's Coins balance.",
    "level":"User's level",
    "gender":"User's 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
}

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

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

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

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

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId",
    "rewards": [ 
        { 
            "amount": "Reward amount", 
            "reference_id": "The ID generated by the game server, used to distinguish each reward record.", 
            "type": "coins", 
            "uid": "User ID"
        }
    ], 
    "session_id": "The live room ID"
}

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

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

محتوى الاستجابة:

json

{
"result":[
    {
        "reward_id":"Reward ID",
        "reference_id":"The ID generated by the game server, used to distinguish each reward record.",
        "status": "Resule status",
        "availableCoinsCredit": "The total amount of coins that can be used for game rewards"
    }]
}

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

القيم المحتملة لـ status هي:

0: نجاح
11: مرفوض
12: مبلغ المكافأة 0، لم يتم اتخاذ أي إجراء
13: رصيد العملات غير كافٍ في اللعبة
14: Invalid reward type
20: Other error

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

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
        }
    ]
}

Player payment

Games can offer players paid features, such as purchasing items or additional attempts.

Before using the purchase function, it is necessary to pre-arrange with the Lobah gaming platform the products to be purchased and their prices. Players will use Lobah Coins for the purchase settlement. The balance of Coins that a player owns can be checked through the Get User Prifile API.

Request path: /1.0/open-gateway/game/purchase

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId",
    "product_id": "specified product ID",
    "reference_id": "an ID generated by the game server to identify this transaction record, this ID must be unique across all transactions",
    "session_id": "The live room ID",
    "uid": "User ID"
}

Important note: Because the amount parameter is easily confused with other API, and considering the habit of using the purchase API, The amount parameter is DEPRECATED in the purchase API and it can be ignored. When the purchase API is used, the coins amount paid by the player is determined by the product ID.

The product_id is agreed upon by Lobah and the developer.

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

محتوى الاستجابة:

json

{
    "purchase_result_code": "result code",
    "balance": "the balance held by the game",
    "user_coins": "the user's Coins balance",
    "order_id": "transaction ID, used for refunds"
}

The results for purchase_result_code are as follows:

0: Purchase successful
10: Incorrect appId
11: Incorrect product_id
12: Insufficient user Coins
13: Duplicate or invalid reference_id
20: Other errors

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

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"
}

Refunds

After a purchase operation, a refund operation can be performed on the transaction. After the refund, the Coins spent on the purchase will be returned to the player's account.

Request path: /1.0/open-gateway/game/refund

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId",
    "order_id": "the transaction ID returned at the time of purchase"
}

محتوى الاستجابة:

json

{
    "result": "result code"
}

The results for result are as follows:

0: Refund successful
10: Incorrect order_id
11: مرفوض
20: Other errors

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

json

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

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

json

{
    "result":0
}

Top Players

The game server can provide the Top Players data, displaying players from the Lobah platform on the game's leaderboard.

Request path: /1.0/open-gateway/game/top-players

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId", 
    "rankings": [
       { "uid": "user ID", "score": "user score" }
    ] 
}

User scores are ranked in descending order.

محتوى الاستجابة:

json

{
    "ok": "boolean"
}

When ok is true, the data has been successfully written; when false, it indicates an error occurred.

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

json

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

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

json

{
    "ok":true
}

Mark Playing Status

This API can display the game player information on the currently playing tab in the room.

Request path: /1.0/open-gateway/game/mark-players

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId", 
    "rankings": [
       { 
         "uid": "user ID",
         "score": "user score",
         "session_id": "room id"
       }
    ] 
}

Each call to this interface will overwrite the previous data for easy updating.

The session id is the player's current room ID. If the room ID is set, players with the same room ID will be displayed in the same room. If it is not set, all players will be displayed.

محتوى الاستجابة:

json

{
    "ok": "boolean"
}

When ok is true, the data has been successfully written; when false, it indicates an error occurred.

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

json

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

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

json

{
    "ok":true
}

Get Product List

This API can obtain available Product information.

Request path: /1.0/open-gateway/game/product-list

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId"
}

محتوى الاستجابة:

json

{
    "products":
        [
            {
                "product_id": "Product ID",
                "coins": "Product price",
                "description": "Product description"
            }
        ]
}

All available product information will be listed here, and the product_id is used for the purchase API.

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

json

{
    "app_id": 92
}

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

json

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

Transactions

The Transaction API is a set of APIs used to perform multiple payment and reward operations for different users during a game session or phase, followed by a one-time settlement.

1. Start a Transaction

Request path: /1.0/open-gateway/game/transaction/start

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId",
    "reference_id": "A unique ID generated by the game server to distinguish this request."
}

Note: The reference_id must be unique; duplicate reference_id values will cause the call to fail.

محتوى الاستجابة:

json

{ 
    "app_id": "appId",
    "reference_id": "Passed reference_id",
    "transaction_id": "This transaction's ID",
    "result_code": "Result Code"
}

Values for result_code:

0: Transaction started successfully.
10: Invalid app_id.
13: Invalid or duplicated reference_id.
20: Other errors.

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

json

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

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

json

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

2. Check the Transaction Status

Request path: /1.0/open-gateway/game/transaction/status

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID"
}

محتوى الاستجابة:

json

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "total_added_amount": "Total amount sent to users",
    "total_deducted_amount": "Total amount debited from users",
    "result_code": "Result Code"
}

Values for result_code:

0: Transaction in progress.
2: Transaction already closed.
10: Invalid app_id.
15: Non-existent transaction_id.
20: Other errors.

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

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. Send Coins to User in a Transaction

Request path: /1.0/open-gateway/game/transaction/add

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "reference_id": "A unique ID generated by the game server to distinguish this request.",
    "amount": "Number of coins to send",
    "uid": "User ID",
    "session_id": "Current room ID where the user is located"
}

محتوى الاستجابة:

json

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "reference_id": "Passed reference_id",
    "total_added_amount": "Total amount sent to users",
    "total_deducted_amount": "Total amount debited from users",
    "user_coins": "User's current coin balance",
    "uid": "User ID",
    "result_code": "Result Code"
}

Values for result_code:

0: Operation successful.
2: Transaction already closed; this call is invalid.
10: Invalid app_id.
13: Invalid or duplicated reference_id.
15: Non-existent transaction_id.
16: Total sent amount exceeds total debited amount; this call is invalid.
20: Other errors.

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

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. Deduct Coins from User in a Transaction

Request path: /1.0/open-gateway/game/transaction/deduct

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "reference_id": "A unique ID generated by the game server to distinguish this request.",
    "amount": "Number of coins to deduct",
    "uid": "User ID",
    "session_id": "Current room ID where the user is located"
}

محتوى الاستجابة:

json

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "reference_id": "Passed reference_id",
    "total_added_amount": "Total amount sent to users",
    "total_deducted_amount": "Total amount debited from users",
    "user_coins": "User's current coin balance",
    "uid": "User ID",
    "result_code": "Result Code"
}

Values for result_code:

0: Operation successful.
2: Transaction already closed; this call is invalid.
10: Invalid app_id.
12: Insufficient user balance; this call is invalid.
13: Invalid or duplicated reference_id.
15: Non-existent transaction_id.
20: Other errors.

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

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. Close a Transaction

Request path: /1.0/open-gateway/game/transaction/close

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

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

محتوى الطلب:

json

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID"
}

محتوى الاستجابة:

json

{ 
    "app_id": "appId",
    "transaction_id": "This transaction's ID",
    "total_added_amount": "Total amount sent to users",
    "total_deducted_amount": "Total amount debited from users",
    "result_code": "Result Code"
}

Values for result_code:

0: Operation successful.
2: Transaction already closed.
10: Invalid app_id.
20: Other errors.

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

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) ​

اختبار التحقق ​

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

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

Player payment ​

Refunds ​

Top Players ​

Mark Playing Status ​

Get Product List ​

Transactions ​

1. Start a Transaction ​

2. Check the Transaction Status ​

3. Send Coins to User in a Transaction ​

4. Deduct Coins from User in a Transaction ​

5. Close a Transaction ​

مرجع واجهة برمجة التطبيقات (API)

عنوان واجهة برمجة تطبيقات الخادم (Server API)

التحقق من الهوية

وصف واجهة برمجة التطبيقات (API)

اختبار التحقق

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

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

Player payment

Refunds

Top Players

Mark Playing Status

Get Product List

Transactions

1. Start a Transaction

2. Check the Transaction Status

3. Send Coins to User in a Transaction

4. Deduct Coins from User in a Transaction

5. Close a Transaction