Android

هذا هو Android checkout SDK الرسمي (com.dodopayments.api:checkout-android)، المخصص لفتح صفحة الدفع المستضافة من Dodo. وهو يختلف عن backend Kotlin SDK، الذي يستدعي Payments API من Dodo من خادمك.

Checkout Sessions API

أنشئ checkout_url الذي يفتحه هذا SDK

Mobile Integration Guide

أفضل الممارسات لتدفقات الدفع عبر الأجهزة المحمولة

يفتح Android SDK صفحة الدفع المستضافة من Dodo في Chrome Custom Tab باستخدام androidx.browser.customtabs. ولا يتضمن أي شيفرة للشبكات ولا يحتفظ بأي API key. تمرر checkoutUrl من جلسة الدفع على خادمك، ويعيد SDK قيمة CheckoutResult مكتوبة النوع عند إكمال المستخدم للتدفق أو مغادرته. المتطلبات: minSdk 23، Kotlin، Java 17.

التثبيت

Add the Dependency

build.gradle.kts

dependencies {
    implementation("com.dodopayments.api:checkout-android:1.0.0")
}

عيّن مخطط callback كعنصر نائب في بيان Gradle. يعلن البيان الخاص بالمكتبة مسبقًا عن عامل intent filter لنشاط إعادة التوجيه باستخدام الرمز ${dodoCallbackScheme}، لذا فإن هذه الخاصية الواحدة تمثل كامل إعداد التكامل — ولا تحتاج إلى إضافة أي XML للبيان:

build.gradle.kts

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

يجب أن تتطابق القيمة مع المخطط في CheckoutParams.returnUrl (مثلًا myapp://checkout/return).

إذا حذفت العنصر النائب بالكامل، يفشل البناء فورًا بسبب خطأ عنصر نائب غير محلول، بدلًا من الفشل بصمت وقت الدفع. وإذا عيّنته لكنه لا يتطابق مع مخطط returnUrl، فإن DodoCheckout.start يرمي PLATFORM_ERROR قبل عرض أي شيء.

الاستخدام

يدعم SDK أسلوبي استدعاء.

Launcher (Recommended)
Suspend Function

سجّل العقد باستخدام registerForActivityResult، ثم شغّله:

import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout

private val checkoutLauncher =
    registerForActivityResult(DodoCheckout.contract()) { result ->
        when (result.status) {
            CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
            CheckoutStatus.FAILED -> showFailure()
            CheckoutStatus.CANCELLED -> dismiss()
            CheckoutStatus.PENDING -> showPending()
            CheckoutStatus.EXPIRED -> showExpired()
        }
    }

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl, // from your backend's checkout session
        returnUrl = "myapp://checkout/return"
    )
)

فضّل هذا الأسلوب. تُسلَّم النتيجة من خلال ActivityResultRegistry المُدار بواسطة نظام تشغيل Android، لذا فهي تظل متاحة بعد توقف العملية.

استدعِ DodoCheckout.start من نطاق coroutine:

import com.dodopayments.checkout.CheckoutParams
import com.dodopayments.checkout.CheckoutStatus
import com.dodopayments.checkout.DodoCheckout

lifecycleScope.launch {
    val result = DodoCheckout.start(
        activity = this@MyActivity,
        params = CheckoutParams(
            checkoutUrl = checkoutUrl, // from your backend's checkout session
            returnUrl = "myapp://checkout/return"
        ),
        onEvent = { event -> println(event.name) } // logging only
    )

    when (result.status) {
        CheckoutStatus.SUCCEEDED -> showSuccess(result.paymentId)
        CheckoutStatus.FAILED -> showFailure()
        CheckoutStatus.CANCELLED -> dismiss()
        CheckoutStatus.PENDING -> showPending()
        CheckoutStatus.EXPIRED -> showExpired()
    }
}

يحل هذا الأسلوب CompletableDeferred في الذاكرة، لذا فهو لا يظل متاحًا بعد توقف العملية. يتوفر onEvent هنا فقط، وليس في العقد.

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

حقل status هو تلميح لواجهة المستخدم، وليس دليلًا على الدفع. تحقّق دائمًا من الدفع على خادمك الخلفي باستخدام webhooks أو نقطة النهاية Get Payment Detail قبل منح المستخدم صلاحية الوصول.

CheckoutStatus

مطلوب

واحد من SUCCEEDED أو FAILED أو CANCELLED أو PENDING أو EXPIRED.

String?

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

String?

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

List<String>?

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

String?

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

Map<String, String>

كل query parameter من عنوان URL للإرجاع، حرفيًا.

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

Webhooks

استمع إلى أحداث الدفع في الوقت الفعلي

Get Payment Detail

استعلم عن حالة الدفع عند الطلب

لا تمنح المستخدم صلاحية الوصول إلا بعد أن يؤكد أحد هذين الخيارين الدفع. لا تعتمد على CheckoutResult.status وحده.

تخصيص المظهر

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

لون خلفية شريط الأدوات، على هيئة عدد صحيح ARGB Color.

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

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

CloseButtonStyle

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

CloseButtonPosition

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

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

Boolean

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

Boolean

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

Boolean

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

Boolean

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

ColorScheme

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

import com.dodopayments.checkout.BrowserCustomization

checkoutLauncher.launch(
    CheckoutParams(
        checkoutUrl = checkoutUrl,
        returnUrl = "myapp://checkout/return",
        customization = BrowserCustomization(
            toolbarColor = Color.parseColor("#6366F1"),
            closeButtonStyle = BrowserCustomization.CloseButtonStyle.BACK,
            colorScheme = BrowserCustomization.ColorScheme.DARK,
        )
    )
)

الأخطاء

يرمي DodoCheckout.start قيمة CheckoutError فقط عند سوء الاستخدام أو حدوث فشل في النظام الأساسي. اقرأ الرمز من CheckoutError.code:

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

يكون إلغاء المستخدم أو رفض الدفع دائمًا نتيجة (CANCELLED أو FAILED)، وليس خطأً مُلقى. عند استخدام نمط launcher، تُلقى أخطاء التحقق من launcher.launch(...).

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

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

DodoCheckout.getAbandonedSession(context)?.let { abandoned ->
    // reconcile abandoned.sessionId with your backend, then:
    DodoCheckout.clearAbandonedSession(context)
}

إن abandoned.createdAt هو طابع زمني epoch بالميلي ثانية.

Mobile Integration Guide

أفضل الممارسات لتدفقات checkout على الأجهزة المحمولة

Kotlin SDK

SDK للواجهة الخلفية للعمليات من جانب الخادم

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Checkout Sessions API

Mobile Integration Guide

التثبيت

الاستخدام

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

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

Webhooks

Get Payment Detail

تخصيص المظهر

الأخطاء

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

ذات صلة

Mobile Integration Guide

Kotlin SDK

Checkout Sessions API

Mobile Integration Guide

​التثبيت

​الاستخدام

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

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

Webhooks

Get Payment Detail

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

​الأخطاء

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

​ذات صلة

Mobile Integration Guide

Kotlin SDK

التثبيت

الاستخدام

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

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

تخصيص المظهر

الأخطاء

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

ذات صلة