الانتقال إلى المحتوى الرئيسي

​
المقدمة

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

​
كيف يعمل

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

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

قبل إعداد هذا التكامل، تأكد من أن لديك:
  1. حساب دوب مع مساحة عمل
  2. تم تمكين تتبع التحويلات لروابطك
  3. مفتاح واجهة برمجة التطبيقات الخاص بك من دوب (متاح في لوحة معلومات دوب تحت الإعدادات → مفاتيح واجهة برمجة التطبيقات)

​
البدء

1

تمكين تتبع التحويلات في دوب

في لوحة معلومات دوب الخاصة بك، قم بتمكين تتبع التحويلات للروابط التي تريد تتبع المبيعات لها. هذا يسمح لدوب بتسجيل أحداث المبيعات عندما يكمل العملاء عمليات الشراء.
تعرف على المزيد حول تمكين تتبع التحويلات في وثائق دوب.
2

احصل على مفتاح واجهة برمجة التطبيقات الخاص بدوب

انتقل إلى لوحة معلومات دوب → الإعدادات → مفاتيح واجهة برمجة التطبيقات وأنشئ مفتاح واجهة برمجة تطبيقات جديد مع نطاق conversions.write.
احتفظ بمفتاح واجهة برمجة التطبيقات الخاص بك آمنًا ولا تكشف عنه في كود جانب العميل.
3

التقاط معرف النقرة في الدفع

عند إنشاء جلسة الدفع، قم بالتقاط معرف نقرة دوب من ملف تعريف الارتباط وأضفه إلى بيانات التعريف الخاصة بالدفع.
4

إرسال بيانات المبيعات عبر الويب هوك

قم بتكوين ويب هوك لإرسال بيانات المبيعات إلى واجهة برمجة التطبيقات Track الخاصة بدوب عند نجاح المدفوعات.
5

تم!

ستظهر الآن أحداث تحويل المبيعات في لوحة معلومات تحليلات دوب الخاصة بك مع نسبة كاملة إلى روابطك.

​
دليل التنفيذ

​
الخطوة 1: إضافة معرف النقرة ومعرف العميل إلى بيانات التعريف الخاصة بالدفع

عند إنشاء جلسة الدفع، قم بالتقاط معرف نقرة دوب من ملف تعريف الارتباط وأدرجه في بيانات التعريف الخاصة بالدفع مع معرف العميل الخارجي الخاص بك. 
import { cookies } from 'next/headers';
import DodoPayments from 'dodopayments';

const client = new DodoPayments();

export async function createCheckout(productId: string, customerId: string) {
  // Capture Dub click ID from cookie
  const dubClickId = cookies().get('dub_id')?.value;

  const payment = await client.payments.create({
    billing: {
      city: 'New York',
      country: 'US',
      state: 'NY',
      street: '123 Main St',
      zipcode: '10001',
    },
    customer: {
      email: 'customer@example.com',
      name: 'John Doe',
    },
    product_id: productId,
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: customerId,        // Store your customer's unique ID
    },
  });

  return payment;
}

​
الخطوة 2: إرسال بيانات المبيعات إلى دوب

قم بتكوين نقطة نهاية ويب هوك لإرسال بيانات المبيعات إلى واجهة برمجة التطبيقات Track الخاصة بدوب عند نجاح المدفوعات.
1

فتح قسم الويب هوك

في لوحة معلومات مدفوعات دودو الخاصة بك، انتقل إلى الويب هوك → + إضافة نقطة نهاية وقم بتوسيع قائمة التكاملات.
إضافة نقطة نهاية وقائمة التكاملات
2

اختيار دوب

اختر بطاقة تكامل دوب.
3

إدخال مفتاح واجهة برمجة التطبيقات

قدم مفتاح واجهة برمجة التطبيقات الخاص بدوب في حقل التكوين.
إضافة مفتاح واجهة برمجة التطبيقات
4

تكوين التحويل

قم بتحرير كود التحويل لتنسيق بيانات الدفع لواجهة برمجة التطبيقات Track Sale الخاصة بدوب.
5

اختبار وإنشاء

اختبر باستخدام حمولات عينة وانقر على إنشاء لتفعيل التكامل.

​
أمثلة كود التحويل

​
تتبع المبيعات الأساسية

تتبع المبيعات عند نجاح المدفوعات:
basic_sale.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    // Only send to Dub if click ID exists in metadata
    if (payment.metadata && payment.metadata.dub_click_id) {
      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount, // Ensure the amount is in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          customer_email: payment.customer.email,
          customer_name: payment.customer.name,
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
تتبع مبيعات الاشتراك

تتبع كل من الاشتراكات الأولية والمدفوعات المتكررة:
subscription_sale.js
function handler(webhook) {
  const data = webhook.payload.data;

  // Track initial subscription activation
  if (webhook.eventType === "subscription.active") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount, // Amount in cents
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: data.subscription_id,
        eventName: "Subscription Started",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          billing_interval: data.payment_frequency_interval,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  // Track recurring subscription payments
  if (webhook.eventType === "subscription.renewed") {
    if (data.metadata && data.metadata.dub_click_id) {
      webhook.payload = {
        clickId: data.metadata.dub_click_id,
        externalId: data.metadata.dub_external_id || data.customer.customer_id,
        amount: data.recurring_pre_tax_amount,
        currency: data.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: `${data.subscription_id}_${Date.now()}`,
        eventName: "Subscription Renewed",
        metadata: {
          subscription_id: data.subscription_id,
          product_id: data.product_id,
          customer_email: data.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }

  return webhook;
}

​
تتبع المبيعات مع استبعاد الضرائب

أرسل فقط المبلغ قبل الضريبة إلى دوب لتتبع الإيرادات بدقة:
sale_without_tax.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Calculate pre-tax amount (total minus tax)
      const preTaxAmount = payment.total_amount - (payment.tax || 0);

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: preTaxAmount, // Pre-tax amount in cents
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        metadata: {
          total_amount: payment.total_amount,
          tax_amount: payment.tax || 0,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
تتبع المبيعات مع أسماء أحداث مخصصة

استخدم أسماء أحداث مخصصة لتصنيف أنواع مختلفة من المبيعات:
custom_events.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;

    if (payment.metadata && payment.metadata.dub_click_id) {
      // Determine event name based on payment type
      let eventName = "Purchase";
      if (payment.subscription_id) {
        eventName = "Subscription Purchase";
      } else if (payment.metadata && payment.metadata.is_upgrade) {
        eventName = "Plan Upgrade";
      }

      webhook.payload = {
        clickId: payment.metadata.dub_click_id,
        externalId: payment.metadata.dub_external_id || payment.customer.customer_id,
        amount: payment.total_amount,
        currency: payment.currency || "USD",
        paymentProcessor: "dodo",
        invoiceId: payment.payment_id,
        eventName: eventName,
        metadata: {
          product_id: payment.product_cart ? payment.product_cart.map(product => product.product_id).join(', ') : undefined,
          customer_email: payment.customer.email,
        },
      };
    } else {
      // Cancel dispatch if no click ID (organic traffic)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
بديل: تنفيذ جانب العميل

إذا كنت تفضل تتبع المبيعات من خادمك بدلاً من استخدام الويب هوك، يمكنك استدعاء واجهة برمجة التطبيقات Track الخاصة بدوب مباشرة بعد نجاح الدفع: 
'use server';

import { Dub } from 'dub';

const dub = new Dub();

export async function trackSale(
  paymentId: string,
  clickId: string,
  customerId: string,
  amount: number,
  currency: string
) {
  await dub.track.sale({
    clickId: clickId,
    externalId: customerId,
    amount: amount,
    currency: currency,
    paymentProcessor: 'dodo',
    invoiceId: paymentId,
  });
}

​
أفضل الممارسات

التقاط معرف النقرة مبكرًا: قم بتخزين معرف نقرة دوب في أقرب وقت ممكن في تدفق الدفع الخاص بك لضمان نسبة دقيقة، حتى إذا انتقل المستخدم بعيدًا وعاد لاحقًا.
  • تأكد دائمًا من تضمين معرف النقرة في بيانات التعريف: بدون معرف النقرة، لا يمكن لدوب نسب الإيرادات إلى روابطك
  • استخدم معرفات خارجية بشكل متسق: مرر نفس معرف العميل الذي تستخدمه في نظامك لتحليلات دقيقة على مستوى العميل
  • تعامل مع حركة المرور العضوية بشكل جيد: قم بتعيين webhook.cancel = true عندما لا يكون هناك معرف نقرة لتجنب مكالمات واجهة برمجة التطبيقات غير الضرورية
  • اختبر باستخدام مدفوعات عينة: تحقق من أن التكامل يعمل بشكل صحيح قبل الانتقال إلى الإنتاج
  • راقب لوحة معلومات دوب الخاصة بك: تحقق من أن المبيعات تظهر بشكل صحيح مع نسبة دقيقة

​
ملاحظات مهمة

  • تنسيق المبلغ: تتوقع دوب المبالغ بالسنت (على سبيل المثال، 10.00 دولار = 1000)
  • العملة: استخدم رموز العملات ISO 4217 (USD، EUR، GBP، إلخ)
  • التجارب المجانية: لا يتم تتبع المدفوعات بقيمة 0.00 دولار كمبيعات
  • الاستردادات: ضع في اعتبارك تتبع الاستردادات بشكل منفصل إذا لزم الأمر لتقارير الإيرادات الدقيقة

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

  • تحقق من أن مفتاح واجهة برمجة التطبيقات الخاص بدوب صحيح وله نطاق conversions.write
  • تحقق من أن dub_click_id يتم التقاطه وتخزينه في بيانات التعريف الخاصة بالدفع
  • تأكد من أن تحويل الويب هوك يقوم بتنسيق الحمولة بشكل صحيح
  • تحقق من أن الويب هوك يتم تفعيله على أحداث payment.succeeded
  • تأكد من تمكين تتبع التحويلات لروابط دوب الخاصة بك
  • تأكد من أن المستخدمين ينقرون على روابط دوب القصيرة الخاصة بك قبل الدفع
  • تحقق من أن ملف تعريف الارتباط dub_id يتم تعيينه بشكل صحيح على نطاقك
  • تحقق من أن معرفات النقرة تتطابق بين إنشاء الدفع وإكمال الدفع
  • تأكد من أنك تلتقط معرف النقرة قبل إنشاء جلسة الدفع
  • تحقق من أن هيكل JSON يتطابق مع تنسيق واجهة برمجة التطبيقات Track Sale الخاصة بدوب
  • تحقق من أن جميع الحقول المطلوبة (clickId، externalId، amount) موجودة
  • تأكد من أن المبلغ بالسنت (عدد صحيح، وليس عشري)
  • تحقق من أن عنوان URL لنقطة نهاية واجهة برمجة التطبيقات صحيح: https://api.dub.co/track/sale
  • اختبر التحويل باستخدام حمولات ويب هوك عينة
  • تأكد من أنك تتبع فقط على أحداث payment.succeeded، وليس payment.processing
  • استخدم قيم invoiceId فريدة لكل عملية بيع
  • بالنسبة للاشتراكات، أضف الطوابع الزمنية أو فترة الفوترة لمنع التكرار عند التجديدات

​
موارد إضافية

وثائق تحويلات دوب

تعرف على المزيد حول تتبع التحويلات وميزات التحليلات من دوب.

واجهة برمجة التطبيقات Track Sale الخاصة بدوب

عرض مرجع واجهة برمجة التطبيقات الكامل لنقطة نهاية Track Sale الخاصة بدوب.

لوحة معلومات دوب

الوصول إلى لوحة معلومات دوب الخاصة بك لعرض تحليلات التحويلات وبيانات النسبة.

دليل أحداث الويب هوك

تعرف على جميع أحداث ويب هوك المتاحة من مدفوعات دودو.
هل تحتاج إلى مساعدة؟ اتصل بدعم مدفوعات دودو على support@dodopayments.com للحصول على المساعدة في التكامل.