> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# React Native
> افتح hosted checkout الخاص بـ Dodo Payments من تطبيق React Native في علامة تبويب متصفح النظام، واحصل على نتيجة مكتوبة النوع في استدعاء واحد.
هذا هو React Native checkout SDK الرسمي من Dodo Payments، `@dodopayments/react-native-checkout`. يفتح hosted checkout الخاص بـ Dodo في عرض متصفح أصلي ويُعيد نتيجة مكتوبة النوع. ملاحظة: توجد حزمة قديمة وغير مرتبطة باسم `dodopayments-react-native-sdk` (غير محددة النطاق) بواجهة API مختلفة تمامًا. توثّق هذه الصفحة الحزمة الرسمية الحالية المحددة النطاق فقط.
أنشئ checkout\_url الذي يفتحه هذا SDK من الواجهة الخلفية لديك.
تعرّف على كيفية اندماج ذلك ضمن تدفق الدفع الكامل على الأجهزة المحمولة.
إن 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.
## التثبيت
تتم إضافة الحزمة تلقائيًا وتستجلب `com.dodopayments.api:checkout-android` من Maven.
```sh theme={null}
npm i @dodopayments/react-native-checkout
```
لا حاجة إلى إعداد إضافي؛ إذ يتم حل التبعية الأصلية تلقائيًا.
```sh theme={null}
npm i @dodopayments/react-native-checkout
cd ios && pod install
```
تأتي نواة Swift مضمنةً في الحزمة ويتم تثبيتها عبر CocoaPods.
لإصدارات التطوير فقط (وليس Expo Go).
```sh theme={null}
npm i @dodopayments/react-native-checkout
npx expo install expo-build-properties
```
بعد ذلك، اضبط `app.json` لديك (راجع تسجيل مخطط URL لاستدعاء callback أدناه).
يجب أن يسجّل تطبيقك مخطط URL لاستقبال return URL من checkout.
في `android/app/build.gradle`:
```kotlin android/app/build.gradle theme={null}
android {
defaultConfig {
manifestPlaceholders["dodoCallbackScheme"] = "myapp"
}
}
```
استبدل `"myapp"` بمخطط تطبيقك.
في `ios/YourApp/Info.plist`:
```xml Info.plist theme={null}
CFBundleURLTypes
CFBundleURLName
myapp
CFBundleURLSchemes
myapp
```
يمكنك أيضًا إضافة ذلك عبر واجهة **Info → URL Types** في Xcode.
في `app.json`:
```json app.json theme={null}
{
"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`:
```sh theme={null}
npx expo prebuild --clean
```
يعمل هذا مع إصدارات التطوير فقط، وليس Expo Go.
## الاستخدام
```typescript theme={null}
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 تتعامل مع إعادة التوجيه أصليًا. من الآمن تسجيل المستمع دون شروط على كلا النظامين الأساسيين.
```typescript theme={null}
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`.
واحد من `succeeded` أو `failed` أو `cancelled` أو `pending` أو `expired`.
يُحدَّد عند تضمين أحدها في return URL. اعرضه في واجهة المستخدم، ولا تستخدمه لمنح الوصول. راجع التحقق من الدفع أدناه.
يُحدَّد لعمليات checkout الخاصة بالاشتراكات.
يُحدَّد عند تضمين منتجات تتطلب license keys في checkout.
يُحدَّد عند التقاط بريد إلكتروني في checkout.
كل query parameter من return URL، حرفيًا.
## التحقق من الدفع
يستدعي Dodo Payments الواجهة الخلفية لديك عند نجاح الدفع أو تفعيل الاشتراك.
ابحث عن `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 التالية وسوِّها مع الواجهة الخلفية لديك.
```typescript theme={null}
import { DodoCheckout } from '@dodopayments/react-native-checkout';
const abandoned = await DodoCheckout.getAbandonedSession();
if (abandoned) {
// reconcile abandoned.sessionId with your backend, then:
await DodoCheckout.clearAbandonedSession();
}
```
## ذات صلة
العقد نفسه لأنظمة Android وiOS وFlutter.
مثال Expo كامل مع تكامل checkout.