Dub

مقدمة

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

إكمال دفعة لمرة واحدة
الاشتراك في خطة مدفوعة
إجراء دفعة اشتراك متكررة

يتطلب هذا التكامل حسابًا في Dub مع تفعيل تتبّع التحويلات على روابطك.

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

آلية العمل

تتتبّع Dub الزوار من خلال معرّف نقرة فريد (dub_id) يُخزَّن في ملف تعريف ارتباط عندما ينقر المستخدمون على روابط Dub المختصرة. لإسناد المبيعات إلى روابطك، عليك تنفيذ ما يلي:

التقاط معرّف النقرة في Dub من ملف تعريف الارتباط dub_id عند إنشاء جلسات الدفع
تخزين معرّف النقرة في بيانات الدفع الوصفية إلى جانب المعرّف الخارجي للعميل
إرسال بيانات البيع إلى Dub عند نجاح الدفعات باستخدام Track API الخاص بها

يتيح ذلك لـ Dub مطابقة المبيعات الناجحة مع النقرة الأصلية على الرابط، ما يمنحك إسنادًا كاملًا للتحويلات.

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

قبل إعداد هذا التكامل، تأكد من توفر ما يلي لديك:

حساب Dub مع مساحة عمل
تفعيل تتبّع التحويلات لروابطك
مفتاح Dub API الخاص بك (متاح في لوحة معلومات Dub ضمن Settings → API Keys)

البدء

Enable Conversion Tracking in Dub

في لوحة معلومات Dub، فعّل تتبّع التحويلات للروابط التي تريد تتبّع المبيعات لها. يتيح ذلك لـ Dub تسجيل أحداث البيع عند إكمال العملاء لعمليات الشراء.

تعرّف على المزيد حول تفعيل تتبّع التحويلات في وثائق Dub.

Get Your Dub API Key

انتقل إلى لوحة معلومات Dub → Settings → API Keys وأنشئ مفتاح API جديدًا بنطاق conversions.write.

احرص على حماية مفتاح API الخاص بك، ولا تكشفه مطلقًا في التعليمات البرمجية من جهة العميل.

Capture Click ID in Checkout

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

Send Sale Data via Webhook

اضبط webhook لإرسال بيانات البيع إلى Track API في Dub عند نجاح الدفعات.

Done!

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

دليل التنفيذ

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

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

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_cart: [{ product_id: productId, quantity: 1 }],
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: customerId,        // Store your customer's unique ID
    },
  });

  return payment;
}

const express = require('express');
const DodoPayments = require('dodopayments').default;
const router = express.Router();

const client = new DodoPayments();

router.post('/create-checkout', async (req, res) => {
  // Capture Dub click ID from cookie
  const dubClickId = req.cookies?.dub_id;

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

  res.json({ payment });
});

from fastapi import FastAPI, Request
from dodopayments import DodoPayments

app = FastAPI()
client = DodoPayments()

@app.post("/create-checkout")
async def create_checkout(request: Request):
    # Capture Dub click ID from cookie
    dub_click_id = request.cookies.get("dub_id")

    body = await request.json()

    payment = client.payments.create(
        billing={
            "city": "New York",
            "country": "US",
            "state": "NY",
            "street": "123 Main St",
            "zipcode": "10001",
        },
        customer={
            "email": body["email"],
            "name": body["name"],
        },
        product_cart=[{"product_id": body["product_id"], "quantity": 1}],
        metadata={
            "dub_click_id": dub_click_id,          # Store Dub click ID
            "dub_external_id": body["customer_id"], # Store your customer's unique ID
        },
    )

    return {"payment": payment}

package main

import (
    "context"

    "github.com/dodopayments/dodopayments-go"
)

func createCheckout(dubClickId, customerId, productId string) (*dodopayments.PaymentNewResponse, error) {
    client := dodopayments.NewClient()

    payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
        Billing: dodopayments.F(dodopayments.BillingAddressParam{
            City:    dodopayments.F("New York"),
            Country: dodopayments.F(dodopayments.CountryCodeUs),
            State:   dodopayments.F("NY"),
            Street:  dodopayments.F("123 Main St"),
            Zipcode: dodopayments.F("10001"),
        }),
        Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
            dodopayments.NewCustomerParam{
                Email: dodopayments.F("customer@example.com"),
                Name:  dodopayments.F("John Doe"),
            },
        ),
        ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
            ProductID: dodopayments.F(productId),
            Quantity:  dodopayments.F(int64(1)),
        }}),
        Metadata: dodopayments.F(map[string]string{
            "dub_click_id":    dubClickId, // Store Dub click ID
            "dub_external_id": customerId, // Store your customer's unique ID
        }),
    })

    return payment, err
}

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

اضبط نقطة نهاية webhook لإرسال بيانات البيع إلى Track API في Dub عند نجاح الدفعات.

Open the Webhook Section

في لوحة معلومات Dodo Payments، انتقل إلى Webhooks → + Add Endpoint ووسّع القائمة المنسدلة للتكاملات.

Select Dub

اختر بطاقة تكامل Dub.

Enter API Key

أدخل مفتاح Dub API في حقل الإعداد.

Configure Transformation

عدّل رمز التحويل لتنسيق بيانات الدفع بما يتوافق مع Track Sale API في Dub.

Test & Create

اختبر باستخدام حمولات نموذجية وانقر على Create لتفعيل التكامل.

أمثلة على رمز التحويل

تتبّع المبيعات الأساسي

تتبّع المبيعات عند نجاح الدفعات:

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;
}

تتبّع المبيعات مع استثناء الضريبة

أرسل المبلغ قبل الضريبة إلى Dub لتتبّع الإيرادات بدقة:

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;
}

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

إذا كنت تفضّل تتبّع المبيعات من خادمك بدلًا من استخدام webhooks، يمكنك استدعاء Track API في Dub مباشرةً بعد نجاح الدفع:

'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,
  });
}

const { Dub } = require('dub');

const dub = new Dub();

async function trackSale(payment) {
  if (payment.metadata?.dub_click_id) {
    await dub.track.sale({
      clickId: payment.metadata.dub_click_id,
      externalId: payment.metadata.dub_external_id,
      amount: payment.total_amount,
      currency: payment.currency,
      paymentProcessor: 'dodo',
      invoiceId: payment.payment_id,
    });
  }
}

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

التقاط معرّف النقرة مبكرًا: خزّن معرّف نقرة Dub في أقرب وقت ممكن ضمن تدفق الدفع، لضمان دقة الإسناد حتى إذا غادر المستخدم ثم عاد لاحقًا.

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

ملاحظات مهمة

تنسيق المبلغ: يتوقع Dub المبالغ بالسنتات (مثلًا، ‎$10.00 = 1000‎)
العملة: استخدم رموز العملات وفق ISO 4217 (USD وEUR وGBP وغيرها)
الفترات التجريبية المجانية: لا تُتتبّع الدفعات بقيمة ‎$0‎ باعتبارها مبيعات
المبالغ المستردة: ضع في الاعتبار تتبّع المبالغ المستردة بشكل منفصل عند الحاجة للحصول على تقارير دقيقة عن الإيرادات

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

Sales not appearing in Dub

تحقّق من صحة مفتاح Dub API وأنه يتضمن نطاق conversions.write
تحقق من التقاط dub_click_id وتخزينه في بيانات الدفع الوصفية
تأكد من أن تحويل webhook ينسّق الحمولة بشكل صحيح
تحقّق من تشغيل webhook عند أحداث payment.succeeded
تأكد من تفعيل تتبّع التحويلات لروابط Dub الخاصة بك

Revenue attribution not working

تأكد من نقر المستخدمين على روابط Dub المختصرة قبل الدفع
تحقّق من تعيين ملف تعريف الارتباط dub_id بشكل صحيح على نطاقك
تحقق من تطابق معرّفات النقر بين إنشاء الدفع وإتمامه
تأكد من التقاط معرّف النقرة قبل إنشاء جلسة الدفع

Transformation errors

تحقّق من توافق بنية JSON مع تنسيق Track Sale API في Dub
تأكد من وجود جميع الحقول المطلوبة (clickId وexternalId وamount)
تأكد من أن المبلغ بالسنتات (عدد صحيح وليس عشريًا)
تحقّق من صحة عنوان URL لنقطة API: https://api.dub.co/track/sale
اختبر التحويل باستخدام حمولات webhook نموذجية

Duplicate sales being tracked

تأكد من التتبّع فقط عند أحداث payment.succeeded، وليس payment.processing
استخدم قيم 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 للحصول على المساعدة بشأن التكامل.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

مقدمة

آلية العمل

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

البدء

دليل التنفيذ

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

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

أمثلة على رمز التحويل

تتبّع المبيعات الأساسي

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

تتبّع المبيعات مع استثناء الضريبة

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

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

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

ملاحظات مهمة

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

موارد إضافية

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

​مقدمة

​آلية العمل

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

​البدء

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

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

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

​أمثلة على رمز التحويل

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

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

​تتبّع المبيعات مع استثناء الضريبة

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

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

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

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

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

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

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

مقدمة

آلية العمل

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

البدء

دليل التنفيذ

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

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

أمثلة على رمز التحويل

تتبّع المبيعات الأساسي

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

تتبّع المبيعات مع استثناء الضريبة

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

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

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

ملاحظات مهمة

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

موارد إضافية