Flutter

هذه هي حزمة Flutter الرسمية من Dodo Payments (dodopayments_checkout على pub.dev). توجد أيضًا حزمة منفصلة طوّرها المجتمع، راجع مشاريع المجتمع.

Checkout Sessions API

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

Mobile Integration Guide

تعرّف على كيفية اندماج ذلك في تدفق الدفع الكامل على الأجهزة المحمولة.

تفتح dodopayments_checkout صفحة الدفع المستضافة من Dodo في SFSafariViewController على iOS وعلامة تبويب Chrome مخصصة على Android — وهي نفس النوى الأصلية المستخدمة في حزم iOS و Android المستقلة. توجد كل منطق الدفع في تلك النوى الأصلية؛ وتمرر طبقة Dart الاستدعاء عبر قناة مكتوبة النوع هي Pigeon. ولا تحتوي على مفتاح API، كما أنها لا تستدعي API الخاص بـ Dodo Payments مطلقًا. يتطلب Flutter 3.44+ / Dart 3.12+، وiOS 16+، وAndroid minSdk 23.

التثبيت

Add the Dependency

pubspec.yaml

dependencies:
  dodopayments_checkout: ^1.0.0

iOS
Android

أضف نوع URL لمخططك في ios/Runner/Info.plist:

ios/Runner/Info.plist

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>myapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

بعد ذلك مرّر عناوين URL الواردة (مثلًا عبر app_links) إلى الحزمة، لأن SFSafariViewController لا يمكنه التقاط عنوان URL الخاص بالعودة:

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

DodoCheckout.instance.handleOpenURL(url);

من الآمن تمرير كل عنوان URL هنا. لا يتصرف handleOpenURL إلا مع عناوين URL التي تطابق returnUrl المسجّل لديك، ويحلّ false لأي شيء آخر.

عيّن مخطط استدعاءك كعنصر نائب في بيان Gradle:

android/app/build.gradle

android {
    defaultConfig {
        manifestPlaceholders["dodoCallbackScheme"] = "myapp"
    }
}

إذا كان MainActivity يعيّن android:taskAffinity="" (الإعداد الافتراضي في flutter create)، فأزله أو امنح أنشطة الحزمة نفس الانتماء. وإلا فقد تفقد بعض إصدارات Android من الشركات المصنّعة مسار الدفع الجاري وتعيد PLATFORM_ERROR.

الاستخدام

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl), // from your backend's checkout session
    returnUrl: Uri.parse('myapp://checkout/return'), // scheme must be registered (see Setup)
    onEvent: (event) => print(event.type), // logging only
  ),
);

switch (result.status) {
  case CheckoutStatus.succeeded: showSuccess(result.paymentId);
  case CheckoutStatus.failed:    showFailure();
  case CheckoutStatus.cancelled: dismiss();
  case CheckoutStatus.pending:   showPending();
  case CheckoutStatus.expired:   showExpired();
}

معنى النتيجة

result.status هو تلميح لواجهة المستخدم، وليس دليلًا على الدفع. أكّد كل عملية دفع من الخادم الخلفي لديك، عبر payment.succeeded / subscription.active webhook.

CheckoutStatus

مطلوب

واحد من succeeded، failed، cancelled، pending، expired.

String?

يُعيَّن عند تضمين أحدها في عنوان URL للعودة. اعرضه في واجهة المستخدم، ولا تستخدمه لمنح صلاحية الوصول. راجع قسم التحقق من الدفع أدناه.

String?

يُعيَّن لعمليات دفع الاشتراكات.

List<String>?

يُعيَّن عند تضمين منتجات مفاتيح الترخيص في عملية الدفع.

String?

يُعيَّن عند جمع عنوان بريد إلكتروني في عملية الدفع.

Map<String, String>

كل مَعلمات الاستعلام الواردة من عنوان URL للعودة، حرفيًا.

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

Webhooks

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

Get Payment Detail

ابحث عن paymentId باستخدام مفتاحك السري للتحقق من حالته مباشرة.

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

تخصيص المظهر

يمكنك تخصيص شريط أدوات المتصفح وأزرار نظام الدفع ومخطط الألوان عبر customization على CheckoutParams. يتم تجميع الخيارات حسب المنصة لأن Custom Tab في Android وSFSafariViewController في iOS يعرضان عناصر تحكم أصلية مختلفة. جميع الحقول اختيارية؛ ويؤدي عدم تضمين customization إلى استخدام المظهر الافتراضي لكل منصة.

Android — Custom Tab

لون خلفية شريط الأدوات.

لون شريط التنقل.

لون الفاصل أعلى شريط التنقل.

CloseButtonStyle

يعرض standard أيقونة “X” الخاصة بالنظام؛ بينما يرسم back سهم رجوع بدلاً منها.

CloseButtonPosition

الجانب الذي يظهر عليه زر الإغلاق في شريط الأدوات.

يعرض أيقونة المشاركة في شريط الأدوات.

bool

يعرض عنوان الصفحة أسفل عنوان URL في شريط الأدوات.

bool

يتيح لشريط الأدوات الاختفاء تلقائيًا أثناء تمرير الصفحة.

bool

يعرض “إضافة الصفحة إلى الإشارات المرجعية” في قائمة الخيارات الإضافية.

bool

يعرض “تنزيل الصفحة” في قائمة الخيارات الإضافية.

BrowserColorScheme

يفرض المظهر الفاتح أو الداكن بغض النظر عن إعداد النظام في الجهاز.

iOS — SFSafariViewController

DismissButtonStyle

تسمية أو أيقونة لزر الإغلاق.

PresentationStyle

يظهر pageSheet على شكل بطاقة يمكن إغلاقها بالسحب؛ بينما يغطي fullScreen الشاشة بأكملها.

bool

يتيح طي شريط الأدوات أثناء التمرير. يظهر فقط عندما يكون presentationStyle هو fullScreen — ويحافظ pageSheet على تثبيت الأشرطة بغض النظر عن هذا الإعداد.

BrowserColorScheme

يفرض المظهر الفاتح أو الداكن بغض النظر عن إعداد النظام في الجهاز.

final result = await DodoCheckout.instance.start(
  CheckoutParams(
    checkoutUrl: Uri.parse(checkoutUrl),
    returnUrl: Uri.parse('myapp://checkout/return'),
    customization: BrowserCustomization(
      android: AndroidBrowserOptions(
        toolbarColor: Color(0xFF6366F1),
        closeButtonStyle: CloseButtonStyle.back,
      ),
      ios: IosBrowserOptions(
        presentationStyle: PresentationStyle.fullScreen,
        colorScheme: BrowserColorScheme.dark,
      ),
    ),
  ),
);

الأخطاء

يطرح start استثناء CheckoutException فقط عند إساءة الاستخدام أو حدوث عطل في المنصة. أما عملية الدفع الملغاة أو المرفوضة فهي دائمًا نتيجة وليست استثناءً.

invalidCheckoutUrl (INVALID_CHECKOUT_URL): ليس عنوان URL لجلسة checkout.dodopayments.com.
invalidReturnUrl (INVALID_RETURN_URL): ليس عنوان URL مطلقًا صالحًا.
alreadyInProgress (ALREADY_IN_PROGRESS): توجد عملية دفع قيد التشغيل بالفعل.
platformError (PLATFORM_ERROR): عطل غير متوقع في المنصة.

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

إذا أُغلِق التطبيق أثناء عملية الدفع، فاستعد الجلسة عند تشغيله مجددًا وطابِق حالتها مع الواجهة الخلفية لديك.

import 'package:dodopayments_checkout/dodopayments_checkout.dart';

final abandoned = await DodoCheckout.instance.getAbandonedSession();
if (abandoned != null) {
  // reconcile abandoned.sessionId with your backend, then:
  await DodoCheckout.instance.clearAbandonedSession();
}

Mobile Integration Guide

العقد نفسه لكل من Android وiOS وReact Native.

Community Projects

تتوفر أيضًا حزمة Flutter منفصلة أنشأها المجتمع.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

التثبيت

الاستخدام

معنى النتيجة

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

Webhooks

Get Payment Detail

تخصيص المظهر

الأخطاء

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

ذات صلة

Mobile Integration Guide

Community Projects

Checkout Sessions API

Mobile Integration Guide

​التثبيت

​الاستخدام

​معنى النتيجة

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

Webhooks

Get Payment Detail

​تخصيص المظهر

​الأخطاء

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

​ذات صلة

Mobile Integration Guide

Community Projects

التثبيت

الاستخدام

معنى النتيجة

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

تخصيص المظهر

الأخطاء

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

ذات صلة