حزمة Unity SDK (الألعاب)

تتيح حزمة Unity SDK من SOAMTAR (الإصدار 1.0.1، مساحة الأسماء Soamtar) للاعبين الدفع عبر Orange Money Sierra Leone بالليون (SLE) من داخل لعبتك أو تطبيقك المبني على Unity. وهي تفتح صفحة الدفع المستضافة من SOAMTAR في متصفح النظام.

آلية العمل

لا تنشئ اللعبة أي دفعة ولا تحتفظ أبدًا بمفتاح سرّي.

text

Unity game                     Your backend                         SOAMTAR API
    |-- 1. purchase intent ----->|                                       |
    |                            |-- 2. POST /v1/payments (sk_ key) ---->|
    |                            |<-- payment_url -----------------------|
    |<-- 3. payment_url ---------|                                       |
    |-- 4. Checkout(url): system browser, payer approves with PIN       |
    |-- 5. ask your backend for the final status                        |

تنشئ الواجهة الخلفية لديك الدفعة بمفتاح سرّي (sk_test_… / sk_live_…) عبر حزمة SDK للخادم، ثم تعيد payment_url إلى اللعبة.
تستدعي اللعبة Checkout(paymentUrl). في المتصفح، يُدخل الدافع رقم Orange Money الخاص به (+232 متبوعًا بـ 8 أرقام) ويؤكد الطلب على هاتفه برمز PIN الخاص بـ Orange Money.
لا تفتح العنصر إلا بعد أن تؤكد واجهتك الخلفية الدفع (webhook payment.success أو GET/v1/payments/{id}).

أمان بالغ الأهمية

لا تقبل حزمة Unity SDK إلا المفاتيح العامة (pk_test_… / pk_live_…): يُطلق المُنشئ ArgumentException لأي قيمة أخرى. لا تضمّن أبدًا مفتاحًا سرّيًا (sk_…) في لعبة: يمكن استخراجه من ملف APK/IPA أو من الذاكرة.

التثبيت

انسخ المجلد Assets/Soamtar من مستودع الحزمة إلى مجلد Assets في مشروعك:

text

YourProject/
  Assets/
    Soamtar/
      Scripts/
        SoamtarClient.cs

المتطلبات: Unity 2021.3 أو أحدث.

الاستخدام

csharp

using System.Collections;
using Soamtar;
using UnityEngine;
using UnityEngine.Networking;

public class PurchaseManager : MonoBehaviour
{
    private SoamtarClient soamtar;
    private string pendingOrderId;

    void Start()
    {
        soamtar = new SoamtarClient("pk_test_your_public_key");
    }

    public void OnBuyGoldPack()
    {
        StartCoroutine(CreatePayment());
    }

    IEnumerator CreatePayment()
    {
        // Your backend decides the price and creates the payment with its secret key.
        using var request = new UnityWebRequest("https://api.yourgame.example/purchases", "POST");
        request.uploadHandler = new UploadHandlerRaw(System.Text.Encoding.UTF8.GetBytes("{\"item\":\"gold_pack\"}"));
        request.downloadHandler = new DownloadHandlerBuffer();
        request.SetRequestHeader("Content-Type", "application/json");

        yield return request.SendWebRequest();

        if (request.result != UnityWebRequest.Result.Success)
        {
            Debug.LogError("Could not create the payment: " + request.error);
            yield break;
        }

        var purchase = JsonUtility.FromJson<PurchaseResponse>(request.downloadHandler.text);
        pendingOrderId = purchase.orderId;

        if (!soamtar.Checkout(purchase.paymentUrl))
        {
            Debug.LogError("Refused payment URL");
        }
    }

    void OnApplicationFocus(bool hasFocus)
    {
        // The player came back from the browser: ask YOUR backend whether the order is paid.
        if (hasFocus && pendingOrderId != null)
        {
            StartCoroutine(RefreshOrder(pendingOrderId));
        }
    }

    IEnumerator RefreshOrder(string orderId) { /* call your backend */ yield break; }
}

[System.Serializable]
public class PurchaseResponse
{
    public string orderId;
    public string paymentUrl; // payment_url returned by SOAMTAR to your backend
}

لإعادة اللاعب تلقائيًا، اجعل واجهتك الخلفية ترسل success_url وfailed_url عند إنشاء الدفعة، بحيث يشيران إلى صفحة أو رابط عميق تتعامل معه لعبتك: تعيد صفحة الدفع المستضافة التوجيه إليه عند انتهاء الدفع.

الواجهة البرمجية

العضو	الوصف
`new SoamtarClient(publicKey, baseUrl = "https://app.so-amtar.com/v1")`	يقبل مفاتيح `pk_test_` / `pk_live_` فقط. يحدّد `baseUrl` (HTTPS) المضيف المقبول لعناوين صفحة الدفع.
`bool Checkout(string paymentUrl)`	يفتح العنوان عبر `Application.OpenURL`. يعيد `false` ولا يفتح شيئًا إذا لم يكن العنوان HTTPS على مضيف SOAMTAR.
`bool IsTestMode`	`true` لمفاتيح `pk_test_`.
`SoamtarClient.Version`	`"1.0.1"`

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

يفتح Application.OpenURL المتصفح الافتراضي على Android وiOS وWindows وmacOS، وعلامة تبويب جديدة على WebGL.

قائمة التحقق الأمنية

العزل: يتم الدفع في متصفح النظام؛ ويؤكد اللاعب برمز PIN الخاص بـ Orange Money على هاتفه. لا ترى اللعبة رمز PIN أبدًا.
التحقق من جهة الخادم: تنشئ واجهتك الخلفية المعاملة وتؤكدها (webhook payment.success). لا تفتح عملية شراء أبدًا بناءً على كلام العميل وحده.
وضع الاختبار: مع مفاتيح pk_test_ وsk_test_ تُحاكى الدفعات على المضيف نفسه (https://app.so-amtar.com)؛ ولا تنتقل أي أموال حقيقية.

حزمة Unity SDK (الألعاب) ​

آلية العمل ​

التثبيت ​

الاستخدام ​

الواجهة البرمجية ​

المنصات المدعومة ​

قائمة التحقق الأمنية ​