مقدمة
Dub هي منصة لإسناد الروابط للروابط المختصرة وتتبع التحويلات والبرامج التابعة. من خلال هذا التكامل، تسجّل Dub حدث تحويل مبيعات في كل مرة يدفع فيها العميل عبر Dodo Payments، ما يتيح لك قياس العائد على حملاتك التسويقية وبرامج الإحالة. تسجّل Dub عملية بيع عندما يقوم العميل بما يلي:- إكمال دفعة لمرة واحدة
- الاشتراك في خطة مدفوعة
- إجراء دفعة اشتراك متكررة
يتطلب هذا التكامل حسابًا في Dub مع تفعيل تتبع التحويلات على روابطك. يتطلب تتبع التحويلات في Dub خطة Business أو أعلى.
آلية العمل
عندما ينقر زائر على أحد روابط Dub المختصرة، تخزّن Dub معرّف نقرة فريدًا في ملف تعريف الارتباطdub_id. لإسناد المبيعات إلى روابطك:
- التقاط معرّف نقرة Dub من ملف تعريف الارتباط
dub_idعند إنشاء عملية الدفع. - تخزين معرّف النقرة في
metadataالخاص بالدفع، إلى جانب معرّف العميل في نظامك (المعرّف الخارجي). - إرسال عملية البيع إلى Dub من خلال Track API عند نجاح الدفع.
المتطلبات الأساسية
قبل إعداد هذا التكامل، تحتاج إلى ما يلي:- حساب Dub مع مساحة عمل.
- تفعيل تتبع التحويلات لروابطك.
- مفتاح API من Dub، تنشئه من لوحة تحكم Dub ضمن Settings → API Keys.
البدء
1
Enable Conversion Tracking in Dub
في لوحة تحكم Dub، فعّل تتبع التحويلات للروابط التي تريد تتبع المبيعات لها. بعد ذلك تسجّل Dub أحداث المبيعات للعملاء الذين يصلون من خلال تلك الروابط.
لتفعيل تتبع التحويلات، راجع وثائق Dub.
2
Get Your Dub API Key
في لوحة تحكم Dub، انتقل إلى Settings → API Keys وأنشئ مفتاح API باستخدام نطاق
conversions.write.3
Capture Click ID in Checkout
عند إنشاء عملية دفع، اقرأ معرّف نقرة Dub من ملف تعريف الارتباط وأضِفه إلى
metadata الخاص بالدفع. راجع الخطوة 1.4
Send Sale Data via Webhook
أنشئ نقطة نهاية webhook ترسل كل عملية بيع إلى Track API الخاص بـ Dub عند نجاح الدفع. راجع الخطوة 2.
5
Done
تظهر أحداث تحويل المبيعات في لوحة تحليلات Dub، منسوبة إلى روابطك.
دليل التنفيذ
الخطوة 1: إضافة معرّف النقرة ومعرّف العميل إلى بيانات الدفع الوصفية
عند إنشاء عملية دفع، اقرأ معرّف نقرة Dub من ملف تعريف الارتباط وأدرجه فيmetadata الخاص بالدفع، إلى جانب المعرّف الخارجي لعميلك.
تستخدم الأمثلة أدناه
POST /payments، وهو مهمل. لا يزال يعمل مع عمليات التكامل الحالية، لكن ينبغي أن تستخدم عمليات التكامل الجديدة Checkout Sessions (POST /checkouts)، التي تقبل metadata بالطريقة نفسها.الخطوة 2: إرسال بيانات المبيعات إلى Dub
أنشئ نقطة نهاية webhook ترسل بيانات المبيعات إلى Track API الخاص بـ Dub عند نجاح الدفع.1
Open the Webhook Section
في لوحة تحكم Dodo Payments، انتقل إلى Developer → Webhooks وانقر على Add endpoint.

2
Select Dub
في Integration، حدّد Dub.co.
3
Enter API Key
في API key، الصق مفتاح Dub API الخاص بك. يرسله Dodo Payments في رأس 
Authorization لكل عملية تسليم.
4
Check the URL and Events
إذا كان Endpoint URL فارغًا، فأدخل
https://api.dub.co/track/sale. في Subscribed events، حدّد الأحداث التي يعالجها التحويل، مثل payment.succeeded.5
Configure Transformation
ضمن Transformation code، عدّل المعالج لتنسيق بيانات الدفع من أجل Track Sale API الخاص بـ Dub. ابدأ من الأمثلة.
6
Test & Create
ضمن Test this code، انقر على Simulate لتشغيل المعالج باستخدام حمولة نموذجية. ثم انقر على Create endpoint.
أمثلة على Transformation Code
يرسل كل معالج عملية بيع إلى Dub فقط عندما يحتويmetadata على معرّف نقرة. بالنسبة إلى الزيارات العضوية التي لا تحتوي على معرّف نقرة، يعيّن webhook.cancel = true، لذلك لا يُرسل أي طلب إلى Dub؛ ويظل التسليم المُلغى ظاهرًا على أنه ناجح في سجلات webhook.
يتبع نص الطلب Track Sale API الخاص بـ Dub: يُعد كل من customerExternalId وamount مطلوبًا، بينما تكون قيمة paymentProcessor هي custom، لأن قائمة معالجات الدفع لدى Dub لا تتضمن قيمة Dodo Payments. يأخذ Dub قيمة amount بالوحدة نفسها التي تستخدمها مبالغ Dodo Payments: السنتات للعملات ذات الرقمين العشريين، والعدد الصحيح الكامل للعملات التي لا تتضمن كسورًا عشرية مثل JPY. تمرّر الأمثلة المبلغ دون تغيير.
تتبّع المبيعات الأساسية
تتبّع عملية بيع عند نجاح الدفع:basic_sale.js
تتبّع مبيعات الاشتراكات
تتبّع الاشتراكات الأولية والمدفوعات المتكررة. استخدم هذا المعالج للاشتراكات بدلًا من معالجاتpayment.succeeded، وليس إلى جانبها: إذ يؤدي كل دفع اشتراك أيضًا إلى تشغيل payment.succeeded، لذا فإن معالجة الحدثين تسجّل كل عملية بيع مرتين. راجع دليل تكامل الاشتراكات.
يقرأ المعالج معرّف النقرة من metadata الخاص بالاشتراك، لذا مرّر البيانات الوصفية نفسها عند إنشاء الاشتراك. بالنسبة إلى التجديدات، يجمع invoiceId بين معرّف الاشتراك وprevious_billing_date، وهو بداية فترة الفوترة الحالية، ولذلك يعيد التسليم الذي تمت إعادة محاولته استخدام invoiceId نفسه.
subscription_sale.js
تتبّع المبيعات مع استبعاد الضريبة
أرسل المبلغ قبل الضريبة فقط إلى Dub، بحيث تستبعد الإيرادات في Dub الضريبة:sale_without_tax.js
تتبّع المبيعات باستخدام أسماء أحداث مخصّصة
استخدم أسماء أحداث مخصّصة لتصنيف أنواع المبيعات المختلفة. يقرأ المثال علامةis_upgrade التي تعيّنها في metadata الخاص بالدفع:
custom_events.js
بديل: التنفيذ من جانب العميل
لتتبّع المبيعات من خادمك الخاص بدلًا من استخدام تحويل webhook، استدعِ Track API الخاص بـ Dub مباشرةً بعد نجاح الدفع، مثلًا من معالج webhook الخاص بـpayment.succeeded. يستخدم الكود مفتاح Dub API الخاص بك، لذا شغّله على خادمك، وليس في المتصفح مطلقًا.
أفضل الممارسات
- ضمّن معرّف النقرة في البيانات الوصفية: من دون معرّف النقرة، لا يستطيع Dub إسناد الإيرادات إلى روابطك.
- استخدم المعرّفات الخارجية باستمرار: مرّر معرّف العميل نفسه من نظامك كقيمة
customerExternalIdفي كل مرة، للحصول على تحليلات دقيقة على مستوى العميل. - تعامل مع الزيارات العضوية: عيّن
webhook.cancel = trueعند عدم وجود معرّف نقرة، لتجنّب استدعاءات API غير الضرورية. - اختبر باستخدام مدفوعات نموذجية: شغّل المعالج باستخدام Test this code، وتأكد من عمل التكامل قبل إطلاقه.
- راقب لوحة تحكم Dub: تحقق من ظهور المبيعات مع الإحالة المتوقعة.
ملاحظات مهمة
- تنسيق المبلغ: يتوقع Dub المبالغ بالسنتات للعملات ذات الرقمين العشريين (على سبيل المثال، $10.00 تساوي
1000) وبالعدد الصحيح الكامل للعملات التي لا تتضمن كسورًا عشرية مثل JPY. - العملة: استخدم رموز العملات وفق ISO 4217، مثل USD وEUR وGBP. يحوّل Dub كل عملية بيع إلى USD وفق أحدث سعر صرف.
- التجارب المجانية: يقبل Track Sale API الخاص بـ Dub قيمة
amountتساوي0، ولا تتخطى الأمثلة المدفوعات بقيمة $0، لذا تصل كل دفعة بقيمة $0 إلى Dub كعملية بيع. لتخطّي المدفوعات بقيمة $0، عيّنwebhook.cancel = trueعندما تكون قيمةtotal_amountهي0. - المبالغ المستردة: إذا كنت تحتاج إلى تقارير دقيقة عن الإيرادات، فتتبّع المبالغ المستردة بشكل منفصل.
استكشاف الأخطاء وإصلاحها
Sales Not Appearing in Dub
Sales Not Appearing in Dub
- تحقّق من صحة مفتاح Dub API وأنه يتضمن نطاق
conversions.write. - تحقّق من التقاط
dub_click_idوتخزينه في البيانات الوصفية للدفع. - تحقّق من أن تحويل webhook ينسّق الحمولة بشكل صحيح.
- تحقّق من اشتراك نقطة النهاية في
payment.succeeded. - تأكد من تمكين تتبّع التحويل لروابط Dub الخاصة بك.
- افتح محاولات تسليم نقطة النهاية ضمن علامة التبويب Logs في Developer → Webhooks لرؤية استجابة Dub. يُلغى الدفع الذي لا يحتوي على معرّف نقرة ويظهر على أنه ناجح.
Revenue Attribution Not Working
Revenue Attribution Not Working
- تأكد من نقر العملاء على روابط Dub المختصرة قبل الدفع.
- تحقّق من تعيين ملف تعريف الارتباط
dub_idعلى نطاقك. - تحقّق من تطابق معرّف النقرة في البيانات الوصفية للدفع مع النقرة التي أجراها العميل.
- التقط معرّف النقرة قبل إنشاء عملية الدفع.
Transformation Errors
Transformation Errors
- تحقّق من تطابق الحمولة مع تنسيق Track Sale API الخاص بـ Dub.
- تحقّق من وجود الحقول المطلوبة،
customerExternalIdوamount، ومن تعيينclickIdللإحالة. - تحقّق من أن المبلغ عدد صحيح بوحدة العملة الأصغر، وليس رقمًا عشريًا.
- تحقّق من أن عنوان URL لنقطة النهاية هو
https://api.dub.co/track/sale. - اختبر التحويل باستخدام حمولات webhook نموذجية.
Duplicate Sales Being Tracked
Duplicate Sales Being Tracked
- تتبّع المبيعات في أحداث
payment.succeededفقط، وليس فيpayment.processing. - استخدم
invoiceIdفريدًا لكل عملية بيع. يسجّل Dub عملية بيع واحدة فقط لكلinvoiceId. - بالنسبة إلى التجديدات، أنشئ
invoiceIdمن معرّف الاشتراك وفترة الفوترة، كما هو موضح في تتبّع مبيعات الاشتراكات. إن تسجيل قيمة تتغير مع كل عملية تسليم، مثل الوقت الحالي، يؤدي إلى تسجيل عملية بيع مكررة عند إعادة محاولة التسليم.
موارد إضافية
Dub Conversions Documentation
تعرّف على ميزات تتبّع التحويلات والتحليلات في Dub.
Dub Track Sale API
راجع مرجع API الكامل لنقطة نهاية Track Sale في Dub.
Dub Dashboard
اعرض تحليلات التحويل وبيانات الإحالة في لوحة تحكم Dub.
Webhook Events Guide
تصفّح جميع أحداث webhook في Dodo Payments.
للحصول على مساعدة بشأن هذا التكامل، تواصل مع دعم Dodo Payments على support@dodopayments.com.