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에 포함하세요.

아래 예제에서는 POST /payments을 사용하며, 이는 deprecated 상태입니다. 기존 통합에서는 계속 작동하지만, 새로운 통합에서는 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에 판매 데이터 전송

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

Open the Webhook Section

Dodo Payments 대시보드에서 Webhooks → + Add Endpoint로 이동한 다음 integrations 드롭다운을 엽니다.

Select Dub

Dub integration 카드를 선택합니다.

Enter API Key

구성 필드에 Dub API Key를 입력합니다.

Configure Transformation

결제 데이터를 Dub의 Track Sale API 형식으로 변환하도록 transformation code를 수정합니다.

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을 사용하는 대신 서버에서 판매를 추적하려면, 결제가 성공한 후 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를 조기에 캡처: 정확한 attribution을 보장하려면 checkout flow에서 가능한 한 빨리 Dub click ID를 저장하세요. 사용자가 페이지를 떠났다가 나중에 돌아오는 경우에도 attribution을 유지할 수 있습니다.

항상 metadata에 click ID 포함: click ID가 없으면 Dub은 링크에 매출을 attribution할 수 없습니다
external ID를 일관되게 사용: 정확한 customer-level analytics를 위해 시스템에서 사용하는 것과 동일한 customer ID를 전달하세요
organic traffic을 적절히 처리: click ID가 없을 때는 불필요한 API 호출을 방지하도록 webhook.cancel = true을 설정하세요
샘플 결제로 테스트: 실제 운영을 시작하기 전에 통합이 올바르게 작동하는지 확인하세요
Dub 대시보드 모니터링: 올바른 attribution과 함께 판매가 정상적으로 표시되는지 확인하세요

중요 참고 사항

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

문제 해결

Sales not appearing in Dub

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

Revenue attribution not working

checkout 전에 사용자가 Dub short link를 클릭하는지 확인하세요
dub_id cookie가 도메인에 올바르게 설정되는지 확인하세요
checkout 생성 시점과 결제 완료 시점의 click ID가 일치하는지 확인하세요
checkout session을 생성하기 전에 click ID를 캡처하는지 확인하세요

Transformation errors

JSON 구조가 Dub의 Track Sale API 형식과 일치하는지 검증하세요
필요한 모든 필드(clickId, externalId, amount)가 포함되어 있는지 확인하세요
amount가 센트 단위인지 확인하세요(소수가 아닌 정수)
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의 conversion tracking 및 analytics 기능에 대해 자세히 알아보세요.

Dub Track Sale API

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

Dub Dashboard

Dub 대시보드에 접속하여 conversion analytics 및 attribution data를 확인하세요.

Webhook Events Guide

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

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

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 구현

모범 사례

중요 참고 사항

문제 해결

추가 리소스