Skip to main content
تغطي هذه الصفحة iOS checkout SDK الرسمي من Dodo Payments والمكتوب بلغة Swift. يفتح SDK صفحة الدفع المستضافة من Dodo Payments في عرض متصفح أصلي ويعيد نتيجة مكتوبة النوع.

Checkout Sessions API

أنشئ checkout_url الذي يفتحه SDK هذا، من الواجهة الخلفية لديك.

Mobile Integration Guide

تعرّف على كيفية ملاءمة SDK هذا مع تدفق الدفع الكامل على الهاتف المحمول.
يفتح iOS SDK صفحة الدفع المستضافة من Dodo Payments في SFSafariViewController ويعيد CheckoutResult مكتوبة النوع عند إكمال العميل للدفع أو مغادرته. لا يحتوي SDK على مفتاح API ولا على أي كود للشبكات، لذلك لا يستدعي API الخاص بـ Dodo Payments مطلقًا. تُنفذ عملية الدفع في عرض المتصفح. يعرض SDK هذا العرض ويغلقه ويقرأ النتيجة من عنوان URL للعودة. المتطلبات: iOS 16 أو أحدث، وSwift 6.2 أو أحدث (تعلن الحزمة عن swift-tools-version: 6.2). لا يعتمد SDK على أي تبعيات من جهات خارجية.

التثبيت

1

Add the Package

في Xcode، انتقل إلى File → Add Package Dependencies وأدخل عنوان URL للحزمة:
حدد الإصدار 1.1.0 أو أحدث. يتطلب تخصيص المظهر الإصدار 1.1.0.لإضافة الحزمة في Package.swift بدلًا من ذلك، أضف هذه التبعية:
Package.swift
اسم منتج المكتبة هو DodoCheckout.
2

Register a Callback URL Scheme

سجّل مخطط URL لكي يوجّه iOS عنوان URL للعودة الخاص بالدفع إلى تطبيقك. أضف نوع URL إلى Info.plist:
Info.plist
يمكنك أيضًا إضافة نوع URL في Xcode ضمن Info → URL Types.استخدم هذا المخطط في returnUrl الذي تمرره إلى SDK، مثل myapp://checkout/return، واضبط عنوان URL نفسه باعتباره return_url لجلسة الدفع عندما تنشئ الواجهة الخلفية الجلسة. يطابق SDK عنوان URL للعودة استنادًا إلى المخطط والمضيف والمسار. ليس من الضروري أن يحمّل عنوان URL صفحة حقيقية.

الاستخدام

DodoCheckout.start هي دالة async تُشغّل على main actor. مرّر checkoutUrl باعتباره URL منشأً من checkout_url الذي تعيده الواجهة الخلفية لديك:
يتلقى onEvent أحداث .opened و.returnReceived و.closed. وتكون قيم name الخاصة بها هي checkout.opened وcheckout.return_received وcheckout.closed. استخدم الأحداث للتسجيل فقط، ولا تستخدمها مطلقًا لتحديد النتيجة.

إعادة توجيه عنوان URL للعودة

لا يمكن لـ SFSafariViewController اعتراض عنوان URL للعودة الخاص به، لذلك يفتح iOS عنوان URL في تطبيقك بدلًا من ذلك. أعد توجيه كل عنوان URL وارد إلى DodoCheckout.handleOpenURL(_:). في تطبيق لا يستخدم scenes، استدعِه من application(_:open:options:) الخاص بـ app delegate.
يمكنك إعادة توجيه كل عنوان URL. يعمل handleOpenURL فقط على عنوان URL يطابق returnUrl الخاص بعملية الدفع الجارية، ويعيد true له. وبالنسبة إلى أي عنوان URL آخر، فإنه يعيد false، لذا عليك معالجة عنوان URL بنفسك.

معنى النتيجة

ينشئ SDK قيمة CheckoutResult من معلمات الاستعلام الموجودة في عنوان URL للعودة.
result.status هو تلميح لواجهة المستخدم، وليس دليلًا على الدفع. أكّد كل عملية دفع من الواجهة الخلفية لديك، باستخدام webhook payment.succeeded أو subscription.active.
CheckoutStatus
مطلوب
إحدى خمس قيم:
  • succeeded: يحتوي عنوان URL للعودة على status=succeeded (دفعة لمرة واحدة) أو status=active (اشتراك).
  • failed: تم رفض الدفع (status=failed).
  • cancelled: أغلق العميل sheet قبل وصول عنوان URL للعودة. لا يعرف SDK النتيجة، وربما نجحت عملية الدفع، لذا لا تعرض شاشة فشل. سوِّ الجلسة المتروكة بدلًا من ذلك.
  • pending: تتم تسوية الدفع لاحقًا (status=processing أو أي قيمة requires_*)، أو كانت معلمة status مفقودة أو غير معروفة. سوِّها كما تفعل مع cancelled.
  • expired: انتهت صلاحية جلسة الدفع (status=expired).
String?
معلمة الاستعلام payment_id، عند تضمينها في عنوان URL للعودة. اعرضها في واجهة المستخدم، لكن لا تستخدمها لمنح صلاحية الوصول. راجع التحقق من الدفع.
String?
معلمة الاستعلام subscription_id. تُضبط لعمليات دفع الاشتراكات.
[String]?
معلمة الاستعلام license_key. تُضبط عندما تتضمن عملية الدفع منتجات بمفاتيح ترخيص.
String?
معلمة الاستعلام email. تُضبط عندما تجمع عملية الدفع عنوان بريد إلكتروني.
[String: String]
كل معلمة استعلام من عنوان URL للعودة، حرفيًا.

التحقق من الدفع

Webhooks

يستدعي Dodo Payments الواجهة الخلفية لديك عند نجاح عملية الدفع أو تفعيل اشتراك.

Get Payment Detail

ابحث عن paymentId باستخدام مفتاحك السري للتحقق من حالته.
لا تمنح صلاحية الوصول إلا بعد أن يؤكد أحد هذين الخيارين الدفع. لا تعتمد على result.status وحده.

تخصيص المظهر

لتغيير زر إغلاق sheet ونمط العرض ونظام الألوان، مرّر BrowserCustomization باعتباره customization إلى start(...). كل حقل اختياري. بالنسبة إلى حقل nil، لا يضبط SDK ذلك الخيار ويطبّق iOS الإعداد الافتراضي الخاص به. الاستثناء هو presentationStyle، حيث تعني nil القيمة pageSheet.
DismissButtonStyle?
نمط زر الإغلاق: done أو close أو cancel. يحدد iOS ما إذا كان سيعرضه كتسمية أو كأيقونة.
PresentationStyle?
يعرض pageSheet (الافتراضي) بطاقة يمكن للعميل سحبها إلى الأسفل لإغلاقها. يغطي fullScreen الشاشة بأكملها ولا يتضمن إيماءة إغلاق.
Bool?
يتيح لشريط الأدوات الانطواء أثناء تمرير الصفحة. يظهر تأثيره فقط عندما تكون قيمة presentationStyle هي fullScreen. ومع pageSheet، تظل الأشرطة مثبتة بغض النظر عن هذا الإعداد.
ColorScheme?
يفرض light أو dark ذلك المظهر بغض النظر عن إعداد النظام على الجهاز. يتبع system إعداد النظام. يطبّق هذا الخيار مظهرًا على عناصر التحكم الأصلية المحيطة بالصفحة فقط. ويأتي الوضع الفاتح أو الداكن لصفحة الدفع نفسها من customization.theme في جلسة الدفع، بينما تأتي ألوانها من customization.theme_config.
لا يتضمن iOS خيارًا للون شريط الأدوات. أُهملت خصائص tint الأساسية في SFSafariViewController اعتبارًا من iOS 26.

الأخطاء

يطرح start قيمة CheckoutError فقط عند إساءة الاستخدام أو حدوث فشل في المنصة. اقرأ السبب من error.code. يُعد إلغاء العميل أو رفض الدفع نتيجة دائمًا، وليس خطأً مطروحًا.
  • invalidCheckoutUrl (INVALID_CHECKOUT_URL): ليست قيمة checkoutUrl عنوان URL لجلسة دفع https (مساره يبدأ بـ /session/) على checkout.dodopayments.com أو test.checkout.dodopayments.com.
  • invalidReturnUrl (INVALID_RETURN_URL): ليست قيمة returnUrl عنوان URL مطلقًا يتضمن مخططًا ومضيفًا.
  • alreadyInProgress (ALREADY_IN_PROGRESS): توجد عملية دفع أخرى قيد التشغيل. لا يمكن تشغيل سوى عملية دفع واحدة في كل مرة.
  • platformError (PLATFORM_ERROR): فشل غير متوقع في المنصة، مثل عدم وجود view controller يمكن العرض منه.
بعد طرح خطأ، تحقّق أيضًا من وجود جلسة متروكة. إذا لم يؤكد sheet ظهوره، يحتفظ SDK بسجل الجلسة لأن صفحة الدفع قد تظل مفتوحة. الاستثناء هو alreadyInProgress: السجل الذي تعثر عليه حينها يعود إلى عملية الدفع التي لا تزال قيد التشغيل.

الجلسات المتروكة

يسجل SDK جلسة الدفع عند عرض صفحة الدفع، ويمسح السجل فقط عندما تنتهي عملية الدفع بقيمة succeeded أو failed أو expired. يظل السجل موجودًا عند إغلاق التطبيق بالقوة أثناء الدفع، وبعد نتيجة cancelled أو pending. تحقّق من وجوده عند التشغيل التالي وبعد كل نتيجة cancelled أو pending.
abandoned.sessionId هو معرّف جلسة الدفع، ويبدأ بـ cks_. وabandoned.createdAt هو Date الذي بدأت فيه عملية الدفع. يمكن للواجهة الخلفية لديك البحث عن الجلسة باستخدام الحصول على جلسة الدفع، الذي يعيد payment_id وpayment_status الخاصين بها. إلى أن يصل الدفع إلى حالة نهائية، تعامل معه على أنه قيد الانتظار، وليس فاشلًا.

ذات صلة

Mobile Integration Guide

العقد نفسه لنظام Android وReact Native وFlutter.

React Native SDK

يغلف نواة Swift نفسها على iOS.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦