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 من ملف تعريف الارتباط وأدرجه في بيانات الدفع الوصفية إلى جانب المعرّف الخارجي للعميل.

تستخدم الأمثلة أدناه POST /payments، وهو مهمل. لا يزال يعمل مع عمليات التكامل الحالية، ولكن يجب أن تستخدم عمليات التكامل الجديدة Checkout Sessions (POST /checkouts) — يتم تمرير metadata بالطريقة نفسها.

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 Key في حقل التكوين.

Configure Transformation

عدّل كود التحويل لتنسيق بيانات الدفع من أجل Dub’s Track Sale API.

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 click ID في أقرب وقت ممكن ضمن تدفق الدفع لديك لضمان دقة الإسناد، حتى إذا غادر المستخدم ثم عاد لاحقًا.

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

ملاحظات مهمة

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

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

Sales not appearing in Dub

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

Revenue attribution not working

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

Transformation errors

تحقّق من تطابق بنية JSON مع تنسيق Dub’s Track Sale API
تحقّق من وجود جميع الحقول المطلوبة (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

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

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

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

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

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

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

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

ملاحظات مهمة

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

موارد إضافية