Chuyển đến nội dung chính

​
Giới thiệu

Dub là một nền tảng quản lý liên kết mạnh mẽ giúp bạn tạo, chia sẻ và theo dõi các liên kết ngắn. Bằng cách tích hợp Dodo Payments với Dub, bạn có thể tự động theo dõi các sự kiện chuyển đổi bán hàng khi khách hàng hoàn tất mua hàng, cho phép bạn đo lường ROI của các chiến dịch tiếp thị và chương trình giới thiệu của mình. Một sự kiện “bán hàng” được ghi lại trong Dub khi một khách hàng:
  • Hoàn tất một khoản thanh toán một lần
  • Đăng ký một gói trả phí
  • Thực hiện một khoản thanh toán đăng ký định kỳ
Tích hợp này yêu cầu một tài khoản Dub với theo dõi chuyển đổi được kích hoạt trên các liên kết của bạn.

​
Cách hoạt động

Dub theo dõi khách truy cập thông qua một ID nhấp chuột duy nhất (dub_id) được lưu trữ trong cookie khi người dùng nhấp vào các liên kết ngắn của bạn. Để gán doanh thu cho các liên kết của bạn, bạn cần:
  1. Bắt ID nhấp chuột của Dub từ cookie dub_id khi tạo các phiên thanh toán
  2. Lưu ID nhấp chuột trong siêu dữ liệu thanh toán của bạn cùng với ID bên ngoài của khách hàng
  3. Gửi dữ liệu bán hàng đến Dub khi các khoản thanh toán thành công bằng cách sử dụng Track API của họ
Điều này cho phép Dub khớp các doanh thu thành công với lần nhấp chuột liên kết ban đầu, mang lại cho bạn sự gán chuyển đổi hoàn chỉnh.

​
Điều kiện tiên quyết

Trước khi thiết lập tích hợp này, hãy đảm bảo bạn đã có:
  1. Một tài khoản Dub với một không gian làm việc
  2. Theo dõi chuyển đổi được kích hoạt cho các liên kết của bạn
  3. Khóa API Dub của bạn (có sẵn trong bảng điều khiển Dub của bạn dưới Cài đặt → Khóa API)

​
Bắt đầu

1

Kích hoạt theo dõi chuyển đổi trong Dub

Trong bảng điều khiển Dub của bạn, kích hoạt theo dõi chuyển đổi cho các liên kết mà bạn muốn theo dõi doanh thu. Điều này cho phép Dub ghi lại các sự kiện bán hàng khi khách hàng hoàn tất mua hàng.
Tìm hiểu thêm về việc kích hoạt theo dõi chuyển đổi trong tài liệu Dub.
2

Lấy khóa API Dub của bạn

Điều hướng đến bảng điều khiển Dub → Cài đặt → Khóa API và tạo một khóa API mới với phạm vi conversions.write.
Giữ cho khóa API của bạn an toàn và không bao giờ tiết lộ nó trong mã phía client.
3

Bắt ID nhấp chuột trong thanh toán

Khi tạo một phiên thanh toán, hãy bắt ID nhấp chuột của Dub từ cookie và thêm nó vào siêu dữ liệu thanh toán của bạn.
4

Gửi dữ liệu bán hàng qua Webhook

Cấu hình một webhook để gửi dữ liệu bán hàng đến Track API của Dub khi các khoản thanh toán thành công.
5

Xong!

Các sự kiện chuyển đổi bán hàng sẽ xuất hiện trong bảng điều khiển phân tích Dub của bạn với sự gán hoàn chỉnh cho các liên kết của bạn.

​
Hướng dẫn triển khai

​
Bước 1: Thêm ID nhấp chuột và ID khách hàng vào siêu dữ liệu thanh toán

Khi tạo một phiên thanh toán, hãy bắt ID nhấp chuột của Dub từ cookie và bao gồm nó trong siêu dữ liệu thanh toán của bạn cùng với ID bên ngoài của khách hàng. 
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: '[email protected]',
      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;
}

​
Bước 2: Gửi dữ liệu bán hàng đến Dub

Cấu hình một điểm cuối webhook để gửi dữ liệu bán hàng đến Track API của Dub khi các khoản thanh toán thành công.
1

Mở phần Webhook

Trong bảng điều khiển Dodo Payments của bạn, điều hướng đến Webhooks → + Thêm Điểm cuối và mở rộng danh sách thả xuống tích hợp.
Thêm Điểm cuối và danh sách thả xuống tích hợp
2

Chọn Dub

Chọn thẻ tích hợp Dub.
3

Nhập Khóa API

Cung cấp Khóa API Dub của bạn trong trường cấu hình.
Thêm Khóa API
4

Cấu hình Chuyển đổi

Chỉnh sửa mã chuyển đổi để định dạng dữ liệu thanh toán cho Track Sale API của Dub.
5

Kiểm tra & Tạo

Kiểm tra với các payload mẫu và nhấp vào Tạo để kích hoạt tích hợp.

​
Ví dụ mã chuyển đổi

​
Theo dõi bán hàng cơ bản

Theo dõi doanh thu khi các khoản thanh toán thành công:
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;
}

​
Theo dõi doanh thu đăng ký

Theo dõi cả các đăng ký ban đầu và các khoản thanh toán định kỳ:
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;
}

​
Theo dõi doanh thu không bao gồm thuế

Chỉ gửi số tiền trước thuế đến Dub để theo dõi doanh thu chính xác:
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;
}

​
Theo dõi doanh thu với tên sự kiện tùy chỉnh

Sử dụng tên sự kiện tùy chỉnh để phân loại các loại doanh thu khác nhau:
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;
}

​
Lựa chọn: Triển khai phía client

Nếu bạn muốn theo dõi doanh thu từ máy chủ của mình thay vì sử dụng webhook, bạn có thể gọi Track API của Dub trực tiếp sau khi thanh toán thành công: 
'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,
  });
}

​
Thực hành tốt nhất

Bắt ID nhấp chuột sớm: Lưu ID nhấp chuột của Dub càng sớm càng tốt trong quy trình thanh toán của bạn để đảm bảo gán chính xác, ngay cả khi người dùng điều hướng đi và quay lại sau.
  • Luôn bao gồm ID nhấp chuột trong siêu dữ liệu: Nếu không có ID nhấp chuột, Dub không thể gán doanh thu cho các liên kết của bạn
  • Sử dụng ID bên ngoài một cách nhất quán: Truyền cùng một ID khách hàng mà bạn sử dụng trong hệ thống của bạn để có phân tích cấp độ khách hàng chính xác
  • Xử lý lưu lượng truy cập tự nhiên một cách khéo léo: Đặt webhook.cancel = true khi không có ID nhấp chuột để tránh các cuộc gọi API không cần thiết
  • Kiểm tra với các khoản thanh toán mẫu: Xác minh rằng tích hợp hoạt động chính xác trước khi đưa vào hoạt động
  • Theo dõi bảng điều khiển Dub của bạn: Kiểm tra rằng doanh thu xuất hiện chính xác với sự gán đúng

​
Lưu ý quan trọng

  • Định dạng số tiền: Dub mong đợi số tiền tính bằng xu (ví dụ: $10.00 = 1000)
  • Tiền tệ: Sử dụng mã tiền tệ ISO 4217 (USD, EUR, GBP, v.v.)
  • Thử nghiệm miễn phí: Các khoản thanh toán $0 không được theo dõi như là doanh thu
  • Hoàn tiền: Cân nhắc theo dõi hoàn tiền riêng biệt nếu cần thiết để báo cáo doanh thu chính xác

​
Khắc phục sự cố

  • Xác minh rằng khóa API Dub của bạn là chính xác và có phạm vi conversions.write
  • Kiểm tra rằng dub_click_id đang được bắt và lưu trữ trong siêu dữ liệu thanh toán
  • Đảm bảo rằng chuyển đổi webhook đang định dạng đúng payload
  • Xác minh rằng webhook đang kích hoạt trên các sự kiện payment.succeeded
  • Xác nhận rằng theo dõi chuyển đổi đã được kích hoạt cho các liên kết Dub của bạn
  • Xác nhận rằng người dùng đang nhấp vào các liên kết ngắn của Dub của bạn trước khi thanh toán
  • Xác minh rằng cookie dub_id đang được thiết lập đúng trên miền của bạn
  • Kiểm tra rằng các ID nhấp chuột khớp nhau giữa việc tạo thanh toán và hoàn tất thanh toán
  • Đảm bảo bạn đang bắt ID nhấp chuột trước khi tạo phiên thanh toán
  • Xác thực cấu trúc JSON khớp với định dạng Track Sale API của Dub
  • Kiểm tra rằng tất cả các trường bắt buộc (clickId, externalId, amount) đều có mặt
  • Đảm bảo số tiền là tính bằng xu (số nguyên, không phải số thập phân)
  • Xác minh rằng URL điểm cuối API là chính xác: https://api.dub.co/track/sale
  • Kiểm tra chuyển đổi với các payload webhook mẫu
  • Đảm bảo bạn chỉ theo dõi trên các sự kiện payment.succeeded, không phải payment.processing
  • Sử dụng các giá trị invoiceId duy nhất cho mỗi doanh thu
  • Đối với các đăng ký, thêm dấu thời gian hoặc kỳ thanh toán để ngăn chặn trùng lặp khi gia hạn

​
Tài nguyên bổ sung

Tài liệu chuyển đổi Dub

Tìm hiểu thêm về theo dõi chuyển đổi và các tính năng phân tích của Dub.

Dub Track Sale API

Xem tài liệu API hoàn chỉnh cho điểm cuối Track Sale của Dub.

Bảng điều khiển Dub

Truy cập bảng điều khiển Dub của bạn để xem phân tích chuyển đổi và dữ liệu gán.

Hướng dẫn sự kiện Webhook

Tìm hiểu về tất cả các sự kiện webhook có sẵn của Dodo Payments.
Cần giúp đỡ? Liên hệ với hỗ trợ Dodo Payments tại [email protected] để được hỗ trợ về tích hợp.