React Native

هذا هو React Native checkout SDK الرسمي من Dodo Payments، @dodopayments/react-native-checkout. يفتح hosted checkout الخاص بـ Dodo في عرض متصفح أصلي ويُعيد نتيجة مكتوبة النوع. ملاحظة: توجد حزمة قديمة وغير مرتبطة باسم dodopayments-react-native-sdk (غير محددة النطاق) بواجهة API مختلفة تمامًا. توثّق هذه الصفحة الحزمة الرسمية الحالية المحددة النطاق فقط.

Checkout Sessions API

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

Mobile Integration Guide

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

إن React Native SDK عبارة عن غلاف Turbo Module رفيع فوق نواتَي Swift وKotlin الأصليتين نفسيهما. يفتح SFSafariViewController على iOS وعلامة تبويب Chrome Custom Tab على Android، ولا يحتفظ بأي مفتاح API، ولا يستدعي Dodo API مباشرةً. تُنفَّذ كل منطقية checkout في المتصفح؛ بينما يدير SDK دورة حياة العرض فقط ويلتقط return URL.

يتطلب هذا SDK New Architecture فقط، وReact Native 0.76 أو أحدث، وiOS 16 أو أحدث، وAndroid minSdk 24.

التثبيت

Install the Package

Android
iOS
Expo

تتم إضافة الحزمة تلقائيًا وتستجلب com.dodopayments.api:checkout-android من Maven.

npm i @dodopayments/react-native-checkout

لا حاجة إلى إعداد إضافي؛ إذ يتم حل التبعية الأصلية تلقائيًا.

npm i @dodopayments/react-native-checkout
cd ios && pod install

تأتي نواة Swift مضمنةً في الحزمة ويتم تثبيتها عبر CocoaPods.

لإصدارات التطوير فقط (وليس Expo Go).

npm i @dodopayments/react-native-checkout

بعد ذلك، اضبط app.json لديك (راجع تسجيل مخطط URL لاستدعاء callback أدناه).

يجب أن يسجّل تطبيقك مخطط URL لاستقبال return URL من checkout.

Android (Gradle)
iOS (Info.plist)
Expo (both platforms)

في android/app/build.gradle:

android/app/build.gradle

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

استبدل "myapp" بمخطط تطبيقك.

في ios/YourApp/Info.plist:

Info.plist

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

يمكنك أيضًا إضافة هذا عبر واجهة Info → URL Types في Xcode.

يسجّل plugin الخاص بالحزمة scheme لكلا النظامين الأساسيين في prebuild. مرّر إليه خيار scheme في app.json:

app.json

{
  "expo": {
    "scheme": "myapp",
    "plugins": [
      [
        "@dodopayments/react-native-checkout",
        { "scheme": "myappcheckout" }
      ]
    ]
  }
}

يجب أن يتطابق scheme مع ما تمرّره باعتباره returnUrl (مثلًا myappcheckout://return)، وأن يختلف عن expo.scheme. يسجّل Expo هذا الأخير بالفعل في MainActivity، وقد يؤدي استخدامه مجددًا إلى توجيه عودة checkout إلى الشاشة الخطأ.أعِد بناء المشروع الأصلي بعد تعديل app.json:

npx expo prebuild --clean

يعمل هذا مع development builds فقط، وليس مع Expo Go.إذا كان android/app/build.gradle تتم صيانته يدويًا ولا يحتوي على كتلة defaultConfig { } قياسية يمكن للـ plugin العثور عليها، فأضف العنصر النائب بنفسك بدلًا من ذلك. راجع علامة التبويب Android أعلاه.

الاستخدام

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

// Required for iOS's return-URL handling.
Linking.addEventListener('url', ({ url }) => DodoCheckout.handleOpenURL(url));

const result = await DodoCheckout.start({
  checkoutUrl,                          // from your backend's checkout session
  returnUrl: 'myapp://checkout/return', // scheme must be registered (see Installation)
  onEvent: (e) => console.log(e.type),  // logging only
});

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

إعادة توجيه Return URL

مستمع Linking مطلوب للتعامل مع Return URL في iOS. في Android، يكون handleOpenURL بلا تأثير، إذ يحلّ false لأن نواة Android تتعامل مع إعادة التوجيه أصليًا. من الآمن تسجيل المستمع دون شروط على كلا النظامين الأساسيين.

import { Linking } from 'react-native';
import { DodoCheckout } from '@dodopayments/react-native-checkout';

Linking.addEventListener('url', ({ url }) => {
  DodoCheckout.handleOpenURL(url);
});

معنى النتيجة

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

CheckoutStatus

مطلوب

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

string

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

string

يُحدَّد لعمليات checkout الخاصة بالاشتراكات.

string[]

يُحدَّد عند احتواء checkout على منتجات ذات license key.

string

يُحدَّد عند التقاط checkout لعنوان بريد إلكتروني.

Record<string, string>

كل query parameter من Return URL، كما هو تمامًا.

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

Webhooks

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

Get Payment Detail

ابحث عن paymentId باستخدام secret key الخاص بك للتحقق من حالته مباشرةً.

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

تخصيص المظهر

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

Android — Custom Tab

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

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

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

'default' | 'back'

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

'start' | 'end'

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

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

boolean

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

boolean

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

boolean

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

boolean

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

'system' | 'light' | 'dark'

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

iOS — SFSafariViewController

'done' | 'close' | 'cancel'

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

'pageSheet' | 'fullScreen'

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

boolean

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

'system' | 'light' | 'dark'

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

const result = await DodoCheckout.start({
  checkoutUrl,
  returnUrl: 'myapp://checkout/return',
  customization: {
    android: { toolbarColor: '#6366F1', closeButtonStyle: 'back' },
    ios: { presentationStyle: 'fullScreen', colorScheme: 'dark' },
  },
});

الأخطاء

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

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

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

إذا أُغلِق التطبيق أو حزمة JS أثناء checkout، يضيع الوعد، لكن الطبقة الأصلية تحتفظ بالجلسة. استعدها عند التركيب التالي وقارنها مع الواجهة الخلفية لديك.

import { DodoCheckout } from '@dodopayments/react-native-checkout';

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

Mobile Integration Guide

العقد نفسه لـ Android وiOS وFlutter.

Expo Boilerplate

مثال Expo متكامل مع تكامل checkout.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

التثبيت

الاستخدام

إعادة توجيه Return URL

معنى النتيجة

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

Webhooks

Get Payment Detail

تخصيص المظهر

الأخطاء

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

ذات صلة

Mobile Integration Guide

Expo Boilerplate

Checkout Sessions API

Mobile Integration Guide

​التثبيت

​الاستخدام

​إعادة توجيه Return URL

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

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

Webhooks

Get Payment Detail

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

​الأخطاء

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

​ذات صلة

Mobile Integration Guide

Expo Boilerplate

التثبيت

الاستخدام

إعادة توجيه Return URL

معنى النتيجة

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

تخصيص المظهر

الأخطاء

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

ذات صلة