Skip to main content

مقدمة

Dub هي منصة لإسناد الروابط للروابط المختصرة وتتبع التحويلات والبرامج التابعة. من خلال هذا التكامل، تسجّل Dub حدث تحويل مبيعات في كل مرة يدفع فيها العميل عبر Dodo Payments، ما يتيح لك قياس العائد على حملاتك التسويقية وبرامج الإحالة. تسجّل Dub عملية بيع عندما يقوم العميل بما يلي:
  • إكمال دفعة لمرة واحدة
  • الاشتراك في خطة مدفوعة
  • إجراء دفعة اشتراك متكررة
يتطلب هذا التكامل حسابًا في Dub مع تفعيل تتبع التحويلات على روابطك. يتطلب تتبع التحويلات في Dub خطة Business أو أعلى.
تكامل البرنامج التابع: يعمل هذا التكامل أيضًا مع Dub Partners، وهو منتج البرامج التابعة من Dub. تنسب Dub المبيعات إلى روابط الشركاء التابعة، ما يتيح لك تتبع الإحالات والعمولات وأداء كل شريك. لإعداد برنامج تابع، راجع دليل ميزة البرامج التابعة.

آلية العمل

عندما ينقر زائر على أحد روابط Dub المختصرة، تخزّن Dub معرّف نقرة فريدًا في ملف تعريف الارتباط dub_id. لإسناد المبيعات إلى روابطك:
  1. التقاط معرّف نقرة Dub من ملف تعريف الارتباط dub_id عند إنشاء عملية الدفع.
  2. تخزين معرّف النقرة في metadata الخاص بالدفع، إلى جانب معرّف العميل في نظامك (المعرّف الخارجي).
  3. إرسال عملية البيع إلى Dub من خلال Track API عند نجاح الدفع.
تطابق Dub كل عملية بيع ناجحة مع نقرة الرابط الأصلية، ما ينسب التحويل إلى ذلك الرابط.

المتطلبات الأساسية

قبل إعداد هذا التكامل، تحتاج إلى ما يلي:
  1. حساب Dub مع مساحة عمل.
  2. تفعيل تتبع التحويلات لروابطك.
  3. مفتاح 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.
احفظ مفتاح API بأمان. لا تكشفه مطلقًا في التعليمات البرمجية من جانب العميل.
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.
مربع حوار إضافة نقطة النهاية مع تحديد Dub.co في القائمة المنسدلة Integration
2

Select Dub

في Integration، حدّد Dub.co.
3

Enter API Key

في API key، الصق مفتاح Dub API الخاص بك. يرسله Dodo Payments في رأس Authorization لكل عملية تسليم.
حقل مفتاح API لتكامل Dub
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 في أقرب وقت ممكن ضمن مسار الدفع، حتى تظل الإحالة دقيقةً حتى إذا غادر العميل ثم عاد لاحقًا.
  • ضمّن معرّف النقرة في البيانات الوصفية: من دون معرّف النقرة، لا يستطيع 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.
  • المبالغ المستردة: إذا كنت تحتاج إلى تقارير دقيقة عن الإيرادات، فتتبّع المبالغ المستردة بشكل منفصل.

استكشاف الأخطاء وإصلاحها

  • تحقّق من صحة مفتاح Dub API وأنه يتضمن نطاق conversions.write.
  • تحقّق من التقاط dub_click_id وتخزينه في البيانات الوصفية للدفع.
  • تحقّق من أن تحويل webhook ينسّق الحمولة بشكل صحيح.
  • تحقّق من اشتراك نقطة النهاية في payment.succeeded.
  • تأكد من تمكين تتبّع التحويل لروابط Dub الخاصة بك.
  • افتح محاولات تسليم نقطة النهاية ضمن علامة التبويب Logs في Developer → Webhooks لرؤية استجابة Dub. يُلغى الدفع الذي لا يحتوي على معرّف نقرة ويظهر على أنه ناجح.
  • تأكد من نقر العملاء على روابط Dub المختصرة قبل الدفع.
  • تحقّق من تعيين ملف تعريف الارتباط dub_id على نطاقك.
  • تحقّق من تطابق معرّف النقرة في البيانات الوصفية للدفع مع النقرة التي أجراها العميل.
  • التقط معرّف النقرة قبل إنشاء عملية الدفع.
  • تحقّق من تطابق الحمولة مع تنسيق Track Sale API الخاص بـ Dub.
  • تحقّق من وجود الحقول المطلوبة، customerExternalId وamount، ومن تعيين clickId للإحالة.
  • تحقّق من أن المبلغ عدد صحيح بوحدة العملة الأصغر، وليس رقمًا عشريًا.
  • تحقّق من أن عنوان URL لنقطة النهاية هو https://api.dub.co/track/sale.
  • اختبر التحويل باستخدام حمولات webhook نموذجية.
  • تتبّع المبيعات في أحداث 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.
آخر تعديل في ٢٨ سبتمبر ٢٠٢٦