الدفع عبر الويب

في البناء الذي لا متجر هاتف فيه (Windows وmacOS وLinux وWebGL)، يُدفع ثمن العنصر بالمال الحقيقي عبر بوابة الدفع الخاصة بك: Stripe أو Tap أو Moyasar. يدفع اللاعب في صفحة البوابة داخل المتصفح، ويذهب المال مباشرة إلى حسابك لدى البوابة. وتستدعي لعبتك الدالة نفسها التي تستدعيها لأي عنصر: Shop.PurchaseAsync(item.Id).

Player taps Buy ──▶ checkout opens ──▶ player pays on the gateway's page ──▶ gateway tells Flock ──▶ item delivered

لا يُسلَّم شيء حتى تؤكد البوابة الدفع. وتُغلَق عملية الدفع التي لم تُدفع بعد ساعة، ولا يُحتسب شيء.

يحتاج الدفع عبر صفحة ويب إلى حزمة تطوير Flock لـ Unity بالإصدار 1.98.0 أو أحدث، ولا يحتاج إلى أي حزمة أخرى. وعلى Android وiOS تدفع الاستدعاءات نفسها عبر متجر الهاتف بدلًا منه: راجع الشراء داخل التطبيق.

اربط بوابتك بـ Flock

افتح Monetization > Payments في لوحة تحكم Flock واربط البوابة التي تبيع عبرها بمفاتيحك الخاصة. تبقى المفاتيح على خادم Flock ولا تصل إلى جهاز اللاعب أبدًا. استخدم مفاتيح الاختبار في البوابة أثناء التطوير: تُعلَّم مشترياتها على أنها اختبار وتُستبعد من إيراداتك.

Stripe
Tap Payments
Moyasar

الحقل	ما تُدخله
Secret key	المفتاح السري لحسابك في Stripe (`sk_test_…` أثناء الاختبار)
Webhook secret	سرّ التوقيع للـ webhook أدناه (`whsec_…`)

في Stripe، تحت Developers > Webhooks، أضف عنوانًا هو https://api-flock.qwacks.com/v1/shop/webhook/<your game id>/stripe مع هذه الأحداث: checkout.session.completed وcheckout.session.expired وpayment_intent.payment_failed وcharge.refunded وcharge.dispute.closed، ثم الصق سرّ توقيعه في Flock. ومن دونه يُسلَّم الدفع رغم ذلك، خلال نحو 15 دقيقة بدل أن يُسلَّم فورًا.يحتسب Stripe الدفع بعملة العنصر، ويرفض سعرًا أقل من أدنى مبلغ يحتسبه بعملة حسابك (لحساب يسوّي بالدرهم: 2.00 درهم).

الحقل	ما تُدخله
Secret key	المفتاح السري لحسابك في Tap (`sk_test_…` أثناء الاختبار)
Publishable key	المفتاح المنشور لحسابك في Tap

يعطي Flock بوابة Tap عنوان الإشعار لكل دفعة، فلا شيء عليك تسجيله. ويحتسب Tap الدفع بعملة العنصر نفسها.

الحقل	ما تُدخله
Secret key	المفتاح السري لحسابك في Moyasar (`sk_test_…` أثناء الاختبار)
Publishable key	المفتاح المنشور لحسابك في Moyasar
Webhook secret	الرمز السري للـ webhook أدناه

في لوحة تحكم Moyasar، أضف webhook على العنوان https://api-flock.qwacks.com/v1/shop/webhook/<your game id>/moyasar، واختر رمزًا سريًا، والصق الرمز نفسه في Flock. وإن رُفضت بطاقة اللاعب فله أن يجرّب أخرى في الصفحة نفسها: يبقى الشراء مفتوحًا حتى يُدفع أو تنتهي ساعته.لا يحتسب Moyasar إلا بالريال السعودي: يُحوَّل السعر بالدولار الأمريكي بسعر صرف Flock، وتُرفض أي عملة أخرى.

الاسترداد أو النزاع الذي يُجرى في لوحة تحكم Stripe أو Moyasar نفسها لا يصل إلى Flock بعد: يبقى الشراء مدفوعًا، ويحتفظ اللاعب بما منحه.

اربط بوابة واحدة، أو سمِّ البوابة المستخدمة في اللعبة حين تكون أكثر من بوابة مفعّلة (أدناه).

سعّر العناصر بالمال الحقيقي

سعّر العنصر بإحدى Real Currencies في إعداد العملات، كما تفعل لعنصر المتجر. والسعر هو ما تحتسبه البوابة: 799 بالريال تعني 7.99 ريال. ولا يحتاج العنصر إلى معرّف منتج في متجر للدفع عبر صفحة ويب.

اربطه في لعبتك

اربطه مرة واحدة بعد بدء حزمة التطوير. وفي بناءات Windows وmacOS وLinux وWebGL يربط FlockStore الدفع عبر صفحة ويب تلقائيًا:

FlockStore store;

async void Start()
{
    store = await FlockStore.ConnectAsync(new FlockStoreOptions
    {
        // Your own pages, where the player's browser lands after paying or giving up.
        ReturnUrl = "https://yourgame.example/paid",
        CancelUrl = "https://yourgame.example/cancelled"
    });

    // Every paid checkout, the ones PurchaseAsync answers included: refresh what the screen shows here.
    store.PurchaseCompleted += (item, result) => RefreshTheShop();
}

الخيار	ما يفعله
`PaymentProvider`	البوابة المستخدمة حين تكون أكثر من بوابة مفعّلة: `PaymentProviders.Stripe` أو `Tap` أو `Moyasar`. وإن تُرك فارغًا استُخدمت البوابة المفعّلة الوحيدة للعبة. ويضع بناء Mac App Store هنا `PaymentProviders.AppleAppStore` ليبيع عبر App Store بدلًا من ذلك
`ReturnUrl` و`CancelUrl`	حيث يصل المتصفح بعد الدفع وبعد التراجع
`OpenPaymentPage`	تفتح أنت صفحة الدفع بدلًا من فتحها في علامة تبويب جديدة (راجع WebGL أدناه)
`CheckEvery`	كم مرة تُقرأ عملية الدفع المنتظرة؛ كل 3 ثوانٍ افتراضيًا

تكون قيمة store.IsWebCheckout صحيحة في هذه البناءات، ويعطي store.GetPrice(item.Id).Text سعر العنصر نفسه لتعرضه؛ ولا تكون قيمة GetPrice هي null أبدًا في الدفع عبر صفحة ويب. ويُكتب الرقم بتنسيق جهاز اللاعب، فما SAR 7.99 إلا مثال على شكله.

الشراء

try
{
    PurchaseResult bought = await FlockClient.Instance.Shop.PurchaseAsync(item.Id);
    // Paid: bought.Granted lists what it delivered. Read the wallet and inventory again.
}
catch (FlockStoreException e) when (e.Reason == FlockStoreFailureReasons.Expired)
{
    // Left unpaid for the hour a checkout stays open: nothing was charged.
}
catch (FlockStoreException e)
{
    // PaymentDeclined: the gateway declined the payment or the player gave up. Nothing was charged.
}

يفتح PurchaseAsync عملية دفع، ثم صفحتها، وينتظر حتى تُدفع أو تُرفض أو تنتهي مهلتها. ولا تُفتح عملية دفع مرتين أبدًا: إن لم يصل رد، فشل الاستدعاء بدل أن يحاول مجددًا.

إذا غادر اللاعب اللعبة قبل الدفع: تبقى عملية الدفع مفتوحة على الخادم. ويُعثر عليها مجددًا عند تسجيل دخول اللاعب التالي، ويُبلغ عنها PurchaseCompleted حين تُدفع.
إذا دُفعت واللعبة مغلقة: يسلّمها Flock رغم ذلك، وتظهر في المحفظة والمخزون، لكن لا يُطلق PurchaseCompleted لها.
إلغاء الاستدعاء (برمز الإلغاء الخاص به) يوقف الانتظار لا عملية الدفع: فحين تُدفع يُبلغ عنها PurchaseCompleted.
تسجيل الخروج ينهي الانتظار، ويُعثر على عملية الدفع مجددًا عند تسجيل دخول ذلك اللاعب التالي.

WebGL

لا يفتح المتصفح علامة تبويب جديدة إلا لوقت قصير بعد نقرة اللاعب. وتُفتح صفحة الدفع حالما تجهز عملية الدفع، بعد نحو ثانية ونصف من النقرة في اختباراتنا، وقد فتحها متصفح مبني على Chromium (Chrome وEdge). ويسمح Firefox بوقت مماثل، أما Safari فيسمح بنحو ثانية واحدة، فقد يحجب علامة التبويب. ولـ Safari، اعرض زر ادفع الآن خاصًا بك يفتح الصفحة فور النقر عليه:

string paymentPage;

store = await FlockStore.ConnectAsync(new FlockStoreOptions
{
    OpenPaymentPage = url => { paymentPage = url; ShowPayNowButton(); }
});

// The Pay now button's click:
void OnPayNow() => Application.OpenURL(paymentPage);

اختبر قبل الإطلاق

اربط مفاتيح الاختبار في البوابة، ثم اشترِ بإحدى بطاقات الاختبار لديها (بطاقة Stripe 4242 4242 4242 4242 مع أي تاريخ مستقبلي وأي رمز تحقق؛ وبطاقات Tap وMoyasar في وثائقهما). تُسلَّم عملية الشراء التجريبية كأي عملية أخرى، وتُعلَّم على أنها اختبار، وتُستبعد من إيراداتك. واترك عملية دفع دون دفع لترى أنها تُغلق بحالة Expired بعد الساعة.

حين يفشل شيء

تقول Message لكل فشل ما الذي حدث، وكيف تصلحه في سطر Fix:.

الرمز	ما حدث	ما تفعله
`ShopRealCurrencySettlementUnavailable`	لا بوابة ويب مربوطة أو مفعّلة للعبة	اربط واحدة تحت Monetization > Payments، أو فعّل Active من جديد
`ShopWebhookProviderUnknown`	أكثر من بوابة مفعّلة ولم تسمِّ اللعبة أيًّا منها، أو سمّت متجرًا	اضبط `FlockStoreOptions.PaymentProvider`، أو أوقف البقية مؤقتًا
`PaymentProviderProviderNotFound`	البوابة التي سمّيتها غير مربوطة أو موقوفة مؤقتًا	اربطها، أو فعّل Active من جديد
`PaymentProviderCheckoutFailed`	لم تفتح البوابة عملية الدفع	اقرأ سبب البوابة: مفاتيح ترفضها، أو عملة لا تقبلها، أو سعر أقل من أدنى مبلغ تحتسبه
`ShopNotARealCurrencyItem`	العنصر مسعّر بعملة اللعبة	يُشترى من المحفظة؛ ويفعل `PurchaseAsync` ذلك تلقائيًا
`ShopItemNotForSale`	العنصر أو متجره متوقف	اقرأ المتجر مجددًا: لم يعد مدرجًا

بدء الاستخدام

المفاهيم

الميزات

المرجع

الدفع عبر الويب

الشراء

WebGL

اختبر قبل الإطلاق

حين يفشل شيء

​الشراء

​WebGL

​اختبر قبل الإطلاق

​حين يفشل شيء

الشراء

WebGL

اختبر قبل الإطلاق

حين يفشل شيء