الدفع المضمَّن

يتيح دمج ميزة "الدفع المضمّن" تضمين عملية الدفع المستندة إلى الويب في مساحات عرض Google. استخدِم هذا المسار إذا كان منتجك يتطلّب منطقًا معقّدًا (مثل التخصيصات) لا يمكن أن توفّره واجهة برمجة التطبيقات الأصلية. عليك تنفيذ واجهة مستخدم للدفع سيتم تضمينها في عملية الدفع من خلال إطار iframe.

ما هي ميزة "الدفع المضمّن"؟

تتيح ميزة "الدفع المضمّن" (EC) للمضيف (مثل "بحث Google" أو "وكيل الذكاء الاصطناعي") عرض عملية الدفع الحالية المستندة إلى الويب ضمن تطبيقه (باستخدام إطار iframe أو WebView). وعلى عكس عملية إعادة التوجيه العادية على الويب، يتيح ذلك التواصل في اتجاهين. يمكن للمضيف "تفويض" مهام معيّنة، مثل اختيار عنوان محفوظ أو الدفع باستخدام بيانات اعتماد مخزّنة، وذلك لتوفير تجربة أسرع وأكثر سلاسة، مع بقائك التاجر المسؤول عن تسجيل المعاملات والتعامل مع عملية إنشاء الطلب الفعلية.

قائمة التحقّق الخاصة بالتجار

لإتاحة ميزة "الدفع المضمّن"، يجب استيفاء المتطلبات التالية في واجهة برمجة التطبيقات UCP وتطبيق الدفع في الواجهة الأمامية.

1- تفعيل الاكتشاف (UCP API)

يجب أن توضّح أنّ عملية الدفع تتوافق مع الإضافة المضمّنة في ردود واجهة برمجة التطبيقات الخاصة بمنصة UCP.

• الإجراء: أضِف عنصر إمكانية dev.ucp.shopping.embedded_checkout إلى مصفوفة إمكانات الردّ على UCP.
• المتطلبات: تضمين عناوين URL الخاصة بالمواصفات والمخطط
• اختياري: إذا كنت بحاجة إلى مصادقة (مثل رمز JWT المميز) لتحميل صفحة الدفع، اضبط قيمة auth.required على "صحيح".

"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. التعامل مع عملية تهيئة عنوان URL (الواجهة الأمامية)

عندما يحمّل المضيف continue_url، سيضيف مَعلمات طلب بحث محدّدة. يجب أن يحلّل الواجهة الأمامية هذه البيانات فور تحميلها.

• الإجراء: حلِّل مَعلمات طلب البحث التالية لعنوان URL:
  • ‫ec_version: إصدار البروتوكول (مثلاً 2026-01-11).
  • ec_auth: (في حال توفّره) تحقّق من صحة رمز المصادقة الذي يقدّمه المضيف، إذا ضبطت auth.required: true.
  • ec_delegate: قائمة بالإجراءات التي يريد المضيف التعامل معها بشكل أصلي، مفصولة بفواصل (مثلاً payment.credential, fulfillment.address_change, payment.instruments_change).

3- إنشاء قناة تواصل (الواجهة الأمامية)

تتم عملية التواصل باستخدام postMessage بتنسيق JSON-RPC 2.0.

• الإجراء: نفِّذ أداة معالجة لأحداث message.
• المتطلّبات: يجب التحقّق من مصدر كل رسالة للتأكّد من تطابقه مع المضيف.
• التوافق مع التطبيقات الأصلية: بالنسبة إلى مضيفي التطبيقات الأصلية، تحقَّق من المتغيّرات العامة التي تم إدخالها واستخدِمها (مثل window.EmbeddedCheckoutProtocolConsumer) إذا لم يكن postMessage متاحًا.

4. تنفيذ عملية تأكيد الاتصال (الواجهة الأمامية)

فور عرض صفحة الدفع، عليك إخبار المضيف بأنّك جاهز وتأكيد عمليات التفويض التي تقبلها.

• الإجراء: أرسِل طلب ec.ready فور تحميل الصفحة.
• الحمولة: أدرِج مصفوفة delegate تسرد الإمكانات التي توافق على أن يتولّى المضيف التعامل معها.
• مثال: إذا كان عنوان URL المطلوب هو ec_delegate=payment.credential ووافقت عليه، أدرِج "payment.credential" في حمولة ec.ready.

// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5- تنفيذ منطق التفويض (الواجهة الأمامية)

إذا قبلت تفويضًا في المصافحة، عليك تعديل سلوك واجهة المستخدم لتجنُّب التعارضات.

• الإجراء: إخفاء عناصر واجهة المستخدم ذات الصلة بالمهام المفوضة
• مثال: إذا تم تفويض fulfillment.address_change، عليك إخفاء نموذج العنوان وعرض زر "تغيير العنوان" بدلاً من ذلك.
• الإجراء: عندما ينقر المستخدم على هذا الزر، أرسِل رسالة _request (مثلاً، ec.fulfillment.address_change_request) إلى المضيف.
• الإجراء: انتظِر ردّ المضيف. سيتضمّن الرد البيانات الجديدة (مثل العنوان المحدّد).
• المتطلّبات: عدِّل حالة الدفع باستخدام عملية استبدال بنمط PUT (استبدِل قسم الكائن بأكمله) استنادًا إلى البيانات التي يعرضها المضيف.

// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. إرسال آخر الأخبار عن مراحل النشاط والحالة (الواجهة الأمامية)

يجب إبقاء المضيف على علم بحالة الدفع حتى يتمكّن من تعديل واجهة المستخدم أو معالجة الأخطاء.

• الإجراء: إرسال إشعارات (رسائل بدون رقم تعريف) عند تغيُّر الحالة:
  • ec.start: عندما تكون صفحة الدفع مرئية بالكامل
  • ‫ec.line_items.change: في حال تعديل محتويات السلة أو المبالغ الإجمالية
  • ‫ec.buyer.change: في حال تعديل تفاصيل المشتري
  • ‫ec.complete: عند تقديم الطلب بنجاح
  • ‫ec.error: في حال حدوث خطأ ملِحّ

7. فرض الأمان (الخادم/العناوين)

عليك التأكّد من أنّه لا يمكن للجهات المسيئة تضمين صفحة الدفع.

• الإجراء: تنفيذ عناوين "سياسة أمان المحتوى" (CSP).
• المتطلبات: اضبط frame-ancestors <host_origin>; للسماح بالتضمين فقط من خلال المضيفين الموثوق بهم.
• التنقّل: منطق الحظر الذي ينقل المستخدم بعيدًا عن مسار الدفع (على سبيل المثال، إزالة الروابط "متابعة التسوّق" التي تؤدي إلى صفحتك الرئيسية) يُسمح بالاستثناءات لعمليات التحقّق من خلال نظام الأمان الثلاثي الأبعاد أو عمليات إعادة التوجيه إلى خدمات الدفع التابعة لجهات خارجية.