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 وحده.

الأخطاء

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

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

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

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

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

معنى النتيجة

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

الأخطاء

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

ذات صلة