تغطي هذه الصفحة iOS checkout SDK الرسمي من Dodo Payments والمكتوب بلغة Swift. يفتح SDK صفحة الدفع المستضافة من Dodo Payments في عرض متصفح أصلي ويعيد نتيجة مكتوبة النوع.
Checkout Sessions API
أنشئ
checkout_url الذي يفتحه SDK هذا، من الواجهة الخلفية لديك.Mobile Integration Guide
تعرّف على كيفية ملاءمة SDK هذا مع تدفق الدفع الكامل على الهاتف المحمول.
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 إلى يمكنك أيضًا إضافة نوع URL في Xcode ضمن Info → URL Types.استخدم هذا المخطط في
Info.plist:Info.plist
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.
- SwiftUI
- SceneDelegate
يمكنك إعادة توجيه كل عنوان URL. يعمل
handleOpenURL فقط على عنوان URL يطابق returnUrl الخاص بعملية الدفع الجارية، ويعيد true له. وبالنسبة إلى أي عنوان URL آخر، فإنه يعيد false، لذا عليك معالجة عنوان URL بنفسك.معنى النتيجة
ينشئ SDK قيمةCheckoutResult من معلمات الاستعلام الموجودة في عنوان URL للعودة.
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.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 يمكن العرض منه.
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.