Dub

소개

Dub은 단축 링크를 생성하고 공유하며 추적할 수 있도록 지원하는 강력한 링크 관리 플랫폼입니다. Dodo Payments을(를) Dub과 통합하면 고객이 구매를 완료할 때 판매 전환 이벤트를 자동으로 추적할 수 있으므로 마케팅 캠페인과 추천 프로그램의 ROI를 측정할 수 있습니다. Dub에서는 고객이 다음 작업을 수행하면 “판매” 이벤트가 기록됩니다:

일회성 결제 완료
유료 플랜 구독
반복 구독 결제

이 통합을 사용하려면 링크에서 전환 추적이 활성화된 Dub 계정이 필요합니다.

Affiliate Program 통합: 이 통합은 제휴 추천 및 커미션 추적을 위해 Dub Partners와도 원활하게 작동합니다. Dub의 전환 추적을 사용하여 제휴 링크에 판매를 귀속하고 파트너 성과를 측정하세요. Affiliates 기능 가이드에서 제휴 프로그램 설정 방법을 자세히 알아보세요.

작동 방식

Dub은 사용자가 Dub 단축 링크를 클릭할 때 쿠키에 저장되는 고유 클릭 ID(dub_id)를 통해 방문자를 추적합니다. 판매를 링크에 귀속하려면 다음을 수행해야 합니다:

체크아웃 세션을 생성할 때 dub_id 쿠키에서 Dub의 클릭 ID 캡처
고객의 외부 ID와 함께 결제 metadata에 클릭 ID 저장
Track API를 사용하여 결제가 성공하면 판매 데이터를 Dub으로 전송

이를 통해 Dub은 성공한 판매와 원래 링크 클릭을 일치시켜 완전한 전환 귀속 데이터를 제공합니다.

사전 요구 사항

이 통합을 설정하기 전에 다음 항목을 준비하세요:

workspace가 있는 Dub 계정
링크의 전환 추적 활성화
Dub API key(Settings → API Keys의 Dub 대시보드에서 확인 가능)

시작하기

Enable Conversion Tracking in Dub

Dub 대시보드에서 판매를 추적하려는 링크의 전환 추적을 활성화하세요. 그러면 고객이 구매를 완료할 때 Dub에서 판매 이벤트를 기록할 수 있습니다.

Dub 문서에서 전환 추적 활성화 방법을 자세히 알아보세요.

Get Your Dub API Key

Dub 대시보드 → Settings → API Keys로 이동하여 conversions.write scope의 새 API key를 생성하세요.

API key를 안전하게 보관하고 client-side code에 절대 노출하지 마세요.

Capture Click ID in Checkout

체크아웃 세션을 생성할 때 쿠키에서 Dub 클릭 ID를 캡처하여 결제 metadata에 추가하세요.

Send Sale Data via Webhook

결제가 성공하면 Dub의 Track API로 판매 데이터를 전송하도록 webhook을 구성하세요.

Done!

이제 판매 전환 이벤트가 링크에 대한 전체 귀속 정보와 함께 Dub analytics dashboard에 표시됩니다.

구현 가이드

1단계: 체크아웃 metadata에 클릭 ID 및 고객 ID 추가

체크아웃 세션을 생성할 때 쿠키에서 Dub 클릭 ID를 캡처하고 고객의 외부 ID와 함께 결제 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으로 전송

결제가 성공하면 Dub의 Track API로 판매 데이터를 전송하도록 webhook endpoint를 구성하세요.

Open the Webhook Section

Dodo Payments dashboard에서 Webhooks → + Add Endpoint로 이동하고 integrations dropdown을 확장하세요.

Select Dub

Dub integration card를 선택하세요.

Enter API Key

configuration field에 Dub API Key를 입력하세요.

Configure Transformation

transformation code를 편집하여 Dub의 Track Sale API에 맞는 결제 데이터를 형식화하세요.

Test & Create

샘플 payload로 테스트한 다음 Create를 클릭하여 통합을 활성화하세요.

Transformation Code 예시

기본 판매 추적

결제가 성공하면 판매를 추적합니다:

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

대안: Client-Side 구현

webhook을 사용하는 대신 server에서 판매를 추적하려면 결제가 성공한 후 Dub의 Track API를 직접 호출할 수 있습니다:

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

모범 사례

클릭 ID를 조기에 캡처하세요: 정확한 귀속을 위해 체크아웃 flow에서 가능한 한 빠르게 Dub 클릭 ID를 저장하세요. 사용자가 페이지를 떠났다가 나중에 돌아오는 경우에도 정확하게 추적할 수 있습니다.

항상 metadata에 클릭 ID 포함: 클릭 ID가 없으면 Dub에서 매출을 링크에 귀속할 수 없습니다
외부 ID를 일관되게 사용: 정확한 고객 수준 analytics를 위해 시스템에서 사용하는 것과 동일한 고객 ID를 전달하세요
organic traffic을 적절히 처리: 클릭 ID가 없을 때 불필요한 API 호출을 방지하려면 webhook.cancel = true을 설정하세요
샘플 결제로 테스트: live 환경으로 전환하기 전에 통합이 올바르게 작동하는지 확인하세요
Dub dashboard 모니터링: 올바른 귀속 정보와 함께 판매가 정상적으로 표시되는지 확인하세요

중요 참고 사항

금액 형식: Dub은 금액을 cents 단위로 요구합니다(예: $10.00 = 1000)
통화: ISO 4217 통화 코드(USD, EUR, GBP 등)를 사용하세요
무료 체험: $0 결제는 판매로 추적되지 않습니다
환불: 정확한 매출 보고가 필요한 경우 환불을 별도로 추적하는 것을 고려하세요

문제 해결

Sales not appearing in Dub

Dub API key가 올바르고 conversions.write scope를 보유하는지 확인하세요
dub_click_id이 캡처되어 결제 metadata에 저장되는지 확인하세요
webhook transformation이 payload를 올바르게 형식화하는지 확인하세요
webhook이 payment.succeeded 이벤트에서 트리거되는지 확인하세요
Dub 링크에서 전환 추적이 활성화되어 있는지 확인하세요

Revenue attribution not working

체크아웃 전에 사용자가 Dub 단축 링크를 클릭하는지 확인하세요
dub_id 쿠키가 도메인에 올바르게 설정되는지 확인하세요
체크아웃 생성과 결제 완료 사이에서 클릭 ID가 일치하는지 확인하세요
체크아웃 세션을 생성하기 전에 클릭 ID를 캡처하는지 확인하세요

Transformation errors

JSON 구조가 Dub의 Track Sale API 형식과 일치하는지 검증하세요
필수 field(clickId, externalId, amount)가 모두 포함되어 있는지 확인하세요
amount가 cents 단위인지 확인하세요(integer이며 decimal이 아님)
API endpoint URL이 올바른지 확인하세요: https://api.dub.co/track/sale
샘플 webhook payload로 transformation을 테스트하세요

Duplicate sales being tracked

payment.succeeded 이벤트에서만 추적하고 payment.processing에서는 추적하지 않는지 확인하세요
각 판매에 고유한 invoiceId 값을 사용하세요
구독의 경우 갱신 시 중복을 방지하기 위해 timestamp 또는 billing period를 추가하세요

추가 리소스

Dub Conversions Documentation

Dub의 전환 추적 및 analytics 기능에 대해 자세히 알아보세요.

Dub Track Sale API

Dub의 Track Sale endpoint에 대한 전체 API reference를 확인하세요.

Dub Dashboard

Dub dashboard에 접속하여 전환 analytics 및 귀속 데이터를 확인하세요.

Webhook Events Guide

사용 가능한 모든 Dodo Payments webhook 이벤트에 대해 알아보세요.

도움이 필요하신가요? 통합 지원이 필요하면 support@dodopayments.com으로 Dodo Payments support에 문의하세요.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

소개

작동 방식

사전 요구 사항

시작하기

구현 가이드

1단계: 체크아웃 metadata에 클릭 ID 및 고객 ID 추가

2단계: 판매 데이터를 Dub으로 전송

Transformation Code 예시

기본 판매 추적

구독 판매 추적

세금 제외 판매 추적

사용자 지정 이벤트 이름으로 판매 추적

대안: Client-Side 구현

모범 사례

중요 참고 사항

문제 해결

추가 리소스

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

​소개

​작동 방식

​사전 요구 사항

​시작하기

​구현 가이드

​1단계: 체크아웃 metadata에 클릭 ID 및 고객 ID 추가

​2단계: 판매 데이터를 Dub으로 전송

​Transformation Code 예시

​기본 판매 추적

​구독 판매 추적

​세금 제외 판매 추적

​사용자 지정 이벤트 이름으로 판매 추적

​대안: Client-Side 구현

​모범 사례

​중요 참고 사항

​문제 해결

​추가 리소스

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

소개

작동 방식

사전 요구 사항

시작하기

구현 가이드

1단계: 체크아웃 metadata에 클릭 ID 및 고객 ID 추가

2단계: 판매 데이터를 Dub으로 전송

Transformation Code 예시

기본 판매 추적

구독 판매 추적

세금 제외 판매 추적

사용자 지정 이벤트 이름으로 판매 추적

대안: Client-Side 구현

모범 사례

중요 참고 사항

문제 해결

추가 리소스