Langsung ke konten utama

​
Pendahuluan

Dub adalah platform manajemen tautan yang kuat yang membantu Anda membuat, membagikan, dan melacak tautan pendek. Dengan mengintegrasikan Dodo Payments dengan Dub, Anda dapat secara otomatis melacak peristiwa konversi penjualan ketika pelanggan menyelesaikan pembelian, memungkinkan Anda untuk mengukur ROI dari kampanye pemasaran dan program rujukan Anda. Peristiwa “penjualan” dicatat di Dub ketika seorang pelanggan:
  • Menyelesaikan pembayaran satu kali
  • Berlangganan ke rencana berbayar
  • Melakukan pembayaran langganan berulang
Integrasi ini memerlukan akun Dub dengan pelacakan konversi yang diaktifkan pada tautan Anda.

​
Cara Kerjanya

Dub melacak pengunjung melalui ID klik unik (dub_id) yang disimpan dalam cookie ketika pengguna mengklik tautan pendek Dub Anda. Untuk mengaitkan penjualan dengan tautan Anda, Anda perlu:
  1. Tangkap ID klik Dub dari cookie dub_id saat membuat sesi checkout
  2. Simpan ID klik dalam metadata pembayaran Anda bersama dengan ID eksternal pelanggan
  3. Kirim data penjualan ke Dub ketika pembayaran berhasil menggunakan API Pelacakan mereka
Ini memungkinkan Dub untuk mencocokkan penjualan yang berhasil dengan klik tautan asli, memberikan Anda atribusi konversi yang lengkap.

​
Prasyarat

Sebelum mengatur integrasi ini, pastikan Anda memiliki:
  1. Akun Dub dengan ruang kerja
  2. Pelacakan konversi diaktifkan untuk tautan Anda
  3. Kunci API Dub Anda (tersedia di dasbor Dub Anda di bawah Pengaturan → Kunci API)

​
Memulai

1

Aktifkan Pelacakan Konversi di Dub

Di dasbor Dub Anda, aktifkan pelacakan konversi untuk tautan yang ingin Anda lacak penjualannya. Ini memungkinkan Dub untuk mencatat peristiwa penjualan ketika pelanggan menyelesaikan pembelian.
Pelajari lebih lanjut tentang mengaktifkan pelacakan konversi di dokumentasi Dub.
2

Dapatkan Kunci API Dub Anda

Navigasikan ke dasbor Dub Anda → Pengaturan → Kunci API dan buat kunci API baru dengan cakupan conversions.write.
Jaga kunci API Anda tetap aman dan jangan pernah mengeksposnya dalam kode sisi klien.
3

Tangkap ID Klik di Checkout

Saat membuat sesi checkout, tangkap ID klik Dub dari cookie dan tambahkan ke metadata pembayaran Anda.
4

Kirim Data Penjualan melalui Webhook

Konfigurasikan webhook untuk mengirim data penjualan ke API Pelacakan Dub ketika pembayaran berhasil.
5

Selesai!

Peristiwa konversi penjualan sekarang akan muncul di dasbor analitik Dub Anda dengan atribusi penuh ke tautan Anda.

​
Panduan Implementasi

​
Langkah 1: Tambahkan ID Klik dan ID Pelanggan ke Metadata Checkout

Saat membuat sesi checkout, tangkap ID klik Dub dari cookie dan sertakan dalam metadata pembayaran Anda bersama dengan ID eksternal pelanggan Anda. 
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;
}

​
Langkah 2: Kirim Data Penjualan ke Dub

Konfigurasikan endpoint webhook untuk mengirim data penjualan ke API Pelacakan Dub ketika pembayaran berhasil.
1

Buka Bagian Webhook

Di dasbor Dodo Payments Anda, navigasikan ke Webhooks → + Tambah Endpoint dan perluas dropdown integrasi.
Tambahkan Endpoint dan dropdown integrasi
2

Pilih Dub

Pilih kartu integrasi Dub.
3

Masukkan Kunci API

Berikan Kunci API Dub Anda di bidang konfigurasi.
Tambahkan Kunci API
4

Konfigurasikan Transformasi

Edit kode transformasi untuk memformat data pembayaran untuk API Pelacakan Penjualan Dub.
5

Uji & Buat

Uji dengan payload contoh dan klik Buat untuk mengaktifkan integrasi.

​
Contoh Kode Transformasi

​
Pelacakan Penjualan Dasar

Lacak penjualan ketika pembayaran berhasil:
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;
}

​
Lacak Penjualan Langganan

Lacak baik langganan awal maupun pembayaran berulang:
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;
}

​
Lacak Penjualan dengan Pengecualian Pajak

Kirim hanya jumlah sebelum pajak ke Dub untuk pelacakan pendapatan yang akurat:
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;
}

​
Lacak Penjualan dengan Nama Acara Kustom

Gunakan nama acara kustom untuk mengkategorikan berbagai jenis penjualan:
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;
}

​
Alternatif: Implementasi Sisi Klien

Jika Anda lebih suka melacak penjualan dari server Anda daripada menggunakan webhook, Anda dapat memanggil API Pelacakan Dub secara langsung setelah pembayaran berhasil: 
'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,
  });
}

​
Praktik Terbaik

Tangkap ID klik lebih awal: Simpan ID klik Dub sesegera mungkin dalam alur checkout Anda untuk memastikan atribusi yang akurat, bahkan jika pengguna berpindah dan kembali nanti.
  • Selalu sertakan ID klik dalam metadata: Tanpa ID klik, Dub tidak dapat mengaitkan pendapatan dengan tautan Anda
  • Gunakan ID eksternal secara konsisten: Kirim ID pelanggan yang sama yang Anda gunakan dalam sistem Anda untuk analitik tingkat pelanggan yang akurat
  • Tangani lalu lintas organik dengan baik: Atur webhook.cancel = true ketika tidak ada ID klik untuk menghindari panggilan API yang tidak perlu
  • Uji dengan pembayaran contoh: Verifikasi bahwa integrasi berfungsi dengan benar sebelum diluncurkan
  • Pantau dasbor Dub Anda: Periksa bahwa penjualan muncul dengan benar dengan atribusi yang tepat

​
Catatan Penting

  • Format jumlah: Dub mengharapkan jumlah dalam sen (misalnya, $10.00 = 1000)
  • Mata uang: Gunakan kode mata uang ISO 4217 (USD, EUR, GBP, dll.)
  • Uji coba gratis: Pembayaran $0 tidak dilacak sebagai penjualan
  • Pengembalian dana: Pertimbangkan untuk melacak pengembalian dana secara terpisah jika diperlukan untuk pelaporan pendapatan yang akurat

​
Pemecahan Masalah

  • Verifikasi bahwa kunci API Dub Anda benar dan memiliki cakupan conversions.write
  • Periksa bahwa dub_click_id ditangkap dan disimpan dalam metadata pembayaran
  • Pastikan transformasi webhook memformat payload dengan benar
  • Verifikasi bahwa webhook dipicu pada peristiwa payment.succeeded
  • Konfirmasi bahwa pelacakan konversi diaktifkan untuk tautan Dub Anda
  • Konfirmasi pengguna mengklik tautan pendek Dub Anda sebelum checkout
  • Verifikasi bahwa cookie dub_id disetel dengan benar di domain Anda
  • Periksa bahwa ID klik cocok antara pembuatan checkout dan penyelesaian pembayaran
  • Pastikan Anda menangkap ID klik sebelum membuat sesi checkout
  • Validasi struktur JSON sesuai dengan format API Pelacakan Penjualan Dub
  • Periksa bahwa semua bidang yang diperlukan (clickId, externalId, amount) ada
  • Pastikan jumlah dalam sen (integer, bukan desimal)
  • Verifikasi URL endpoint API benar: https://api.dub.co/track/sale
  • Uji transformasi dengan payload webhook contoh
  • Pastikan Anda hanya melacak pada peristiwa payment.succeeded, bukan payment.processing
  • Gunakan nilai invoiceId yang unik untuk setiap penjualan
  • Untuk langganan, tambahkan cap waktu atau periode penagihan untuk mencegah duplikat pada pembaruan

​
Sumber Daya Tambahan

Dokumentasi Konversi Dub

Pelajari lebih lanjut tentang pelacakan konversi dan fitur analitik Dub.

API Pelacakan Penjualan Dub

Lihat referensi API lengkap untuk endpoint Pelacakan Penjualan Dub.

Dasbor Dub

Akses dasbor Dub Anda untuk melihat analitik konversi dan data atribusi.

Panduan Acara Webhook

Pelajari tentang semua acara webhook Dodo Payments yang tersedia.
Butuh bantuan? Hubungi dukungan Dodo Payments di [email protected] untuk bantuan dengan integrasi.