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
npx expo install expo-build-properties

بعد ذلك، اضبط 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.

في app.json:

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "android": {
            "manifestPlaceholders": {
              "dodoCallbackScheme": "myapp"
            }
          }
        }
      ]
    ],
    "ios": {
      "infoPlist": {
        "CFBundleURLTypes": [
          {
            "CFBundleURLSchemes": ["myapp"]
          }
        ]
      }
    }
  }
}

تتضمن الحزمة أيضًا Expo config plugin باسم @dodopayments/react-native-checkout، لكنه لا يكتب حاليًا أي مخطط URL أو أي manifest placeholder. إن إضافته وحدها لن تسجّل مخطط callback لديك — استخدم إعداد expo-build-properties وinfoPlist أعلاه.

أعد إنشاء native project بعد تعديل app.json:

npx expo prebuild --clean

يعمل هذا مع إصدارات التطوير فقط، وليس Expo Go.

الاستخدام

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 هو تلميح لواجهة المستخدم، وليس دليلًا على الدفع. أكّد كل عملية دفع من الواجهة الخلفية لديك، عبر webhook payment.succeeded / subscription.active.

CheckoutStatus

مطلوب

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

string

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

string

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

string[]

يُحدَّد عند تضمين منتجات تتطلب license keys في checkout.

string

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

Record<string, string>

كل query parameter من return URL، حرفيًا.

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

Webhooks

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

Get Payment Detail

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

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

الأخطاء

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

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

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

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

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

ما الذي تعنيه النتيجة

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

الأخطاء

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

ذات صلة