Skip to main content

소개

Dub는 단축 링크, 전환 추적 및 제휴 프로그램을 위한 링크 귀속 플랫폼입니다. 이 통합을 사용하면 고객이 Dodo Payments를 통해 결제할 때마다 Dub에 판매 전환 이벤트가 기록되므로, 마케팅 캠페인과 추천 프로그램의 투자 수익을 측정할 수 있습니다. Dub은 다음과 같은 경우 판매를 기록합니다:
  • 일회성 결제를 완료한 경우
  • 유료 플랜을 구독한 경우
  • 반복 구독 결제를 한 경우
이 통합을 사용하려면 링크에서 전환 추적이 활성화된 Dub 계정이 필요합니다. Dub의 전환 추적에는 Business 플랜 이상이 필요합니다.
제휴 프로그램 통합: 이 통합은 Dub의 제휴 프로그램 제품인 Dub Partners에서도 작동합니다. Dub은 파트너의 제휴 링크에 판매를 귀속하므로 추천, 커미션 및 각 파트너의 실적을 추적할 수 있습니다. 제휴 프로그램을 설정하려면 제휴 기능 가이드를 참조하세요.

작동 방식

방문자가 Dub 단축 링크 중 하나를 클릭하면 Dub은 dub_id 쿠키에 고유한 클릭 ID를 저장합니다. 판매를 링크에 귀속하려면 다음을 수행하세요:
  1. 체크아웃을 생성할 때 dub_id 쿠키에서 Dub의 클릭 ID를 캡처합니다.
  2. 결제의 metadata에 클릭 ID를 저장하고, 시스템에서 고객의 ID(외부 ID)도 함께 저장합니다.
  3. 결제가 성공하면 Track API를 통해 판매를 Dub으로 전송합니다.
Dub은 각 성공한 판매를 원래 링크 클릭과 일치시켜 해당 링크에 전환을 귀속합니다.

사전 요구 사항

이 통합을 설정하기 전에 다음 항목이 필요합니다:
  1. 워크스페이스가 있는 Dub 계정
  2. 링크에서 활성화된 전환 추적
  3. Dub 대시보드의 Settings → API Keys에서 생성한 Dub API key

시작하기

1

Enable Conversion Tracking in Dub

Dub 대시보드에서 판매를 추적하려는 링크의 전환 추적을 활성화합니다. 그러면 Dub은 해당 링크를 통해 유입된 고객의 판매 이벤트를 기록합니다.
전환 추적을 활성화하려면 Dub 문서를 참조하세요.
2

Get Your Dub API Key

Dub 대시보드에서 Settings → API Keys로 이동하여 conversions.write scope가 있는 API key를 생성합니다.
API key를 안전하게 보관하세요. 클라이언트 측 코드에 절대 노출하지 마세요.
3

Capture Click ID in Checkout

체크아웃을 생성할 때 쿠키에서 Dub 클릭 ID를 읽고 결제의 metadata에 추가합니다. 1단계를 참조하세요.
4

Send Sale Data via Webhook

결제가 성공하면 각 판매를 Dub의 Track API로 전송하는 webhook endpoint를 생성합니다. 2단계를 참조하세요.
5

Done

판매 전환 이벤트는 링크에 귀속된 상태로 Dub 분석 대시보드에 표시됩니다.

구현 가이드

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

체크아웃을 생성할 때 쿠키에서 Dub 클릭 ID를 읽고 고객의 외부 ID와 함께 결제의 metadata에 포함합니다.
아래 예시는 deprecated된 POST /payments을 사용합니다. 기존 통합에서는 계속 작동하지만, 새 통합에서는 metadata을 동일한 방식으로 허용하는 Checkout Sessions(POST /checkouts)을 사용해야 합니다.

2단계: Dub에 판매 데이터 전송

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

Open the Webhook Section

Dodo Payments 대시보드에서 Developer → Webhooks로 이동한 다음 Add endpoint를 클릭합니다.
Add endpoint dialog with Dub.co selected in the Integration dropdown
2

Select Dub

Integration에서 Dub.co를 선택합니다.
3

Enter API Key

API key에 Dub API key를 붙여 넣습니다. Dodo Payments는 모든 전송의 Authorization 헤더에 이 키를 포함합니다.
API key field for the Dub integration
4

Check the URL and Events

Endpoint URL이 비어 있으면 https://api.dub.co/track/sale을 입력합니다. Subscribed events에서 변환이 처리할 이벤트(예: payment.succeeded)를 선택합니다.
5

Configure Transformation

Transformation code에서 핸들러를 편집하여 결제 데이터를 Dub의 Track Sale API 형식으로 지정합니다. 예시에서 시작할 수 있습니다.
6

Test & Create

Test this code에서 Simulate를 클릭하여 샘플 페이로드로 핸들러를 실행합니다. 그런 다음 Create endpoint를 클릭합니다.

Transformation Code Examples

각 핸들러는 metadata에 클릭 ID가 있을 때만 Dub에 판매를 전송합니다. 클릭 ID가 없는 자연 유입 트래픽의 경우 webhook.cancel = true를 설정하므로 Dub으로 요청이 전송되지 않습니다. 취소된 전송은 webhook 로그에 계속 성공으로 표시됩니다. 요청 본문은 Dub의 Track Sale API를 따릅니다. customerExternalId와 amount는 필수이며, Dub의 결제 처리자 목록에 Dodo Payments 값이 없으므로 paymentProcessor는 custom입니다. Dub은 amount에 Dodo Payments 금액과 동일한 단위를 사용합니다. 즉, 소수점 이하 두 자리 통화에서는 센트 단위이고 JPY와 같은 소수점 이하 자릿수가 없는 통화에서는 전체 정수입니다. 예시에서는 금액을 변경하지 않고 전달합니다.

기본 판매 추적

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

구독 판매 추적

최초 구독과 반복 결제를 모두 추적합니다. 구독에는 payment.succeeded 핸들러와 함께 사용하지 말고 대신 이 핸들러를 사용하세요. 각 구독 결제에서도 payment.succeeded가 실행되므로 두 이벤트를 모두 처리하면 모든 판매가 두 번 기록됩니다. Subscription Integration Guide를 참조하세요. 이 핸들러는 구독의 metadata에서 클릭 ID를 읽으므로 구독을 생성할 때 동일한 메타데이터를 전달하세요. 갱신 시 invoiceId는 구독 ID와 현재 결제 기간의 시작인 previous_billing_date를 결합하므로, 재시도된 전송에서도 동일한 invoiceId가 재사용됩니다.
subscription_sale.js

세금을 제외한 판매 추적

세전 금액만 Dub에 전송하여 Dub의 수익에서 세금을 제외합니다:
sale_without_tax.js

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

사용자 지정 이벤트 이름을 사용하여 다양한 판매 유형을 분류합니다. 이 예시에서는 결제의 metadata에 설정한 is_upgrade 플래그를 읽습니다:
custom_events.js

대안: 클라이언트 측 구현

webhook 변환을 통하지 않고 자체 서버에서 판매를 추적하려면 결제 성공 후 Dub의 Track API를 직접 호출합니다. 예를 들어 payment.succeeded webhook 핸들러에서 호출할 수 있습니다. 이 코드는 Dub API key를 사용하므로 브라우저가 아닌 서버에서 실행하세요.

모범 사례

클릭 ID를 일찍 캡처하세요: 결제 흐름에서 가능한 한 일찍 Dub 클릭 ID를 저장하여 고객이 이탈했다가 나중에 돌아오더라도 어트리뷰션이 정확하게 유지되도록 하세요.
  • 메타데이터에 클릭 ID 포함: 클릭 ID가 없으면 Dub은 수익을 링크에 어트리뷰션할 수 없습니다.
  • 외부 ID를 일관되게 사용: 정확한 고객 수준 분석을 위해 매번 시스템의 동일한 고객 ID를 customerExternalId로 전달하세요.
  • 자연 유입 트래픽 처리: 클릭 ID가 없을 때 webhook.cancel = true를 설정하여 불필요한 API 호출을 방지하세요.
  • 샘플 결제로 테스트: Test this code를 사용하여 핸들러를 실행하고, 라이브 환경으로 전환하기 전에 통합이 작동하는지 확인하세요.
  • Dub 대시보드 모니터링: 예상한 어트리뷰션과 함께 판매가 표시되는지 확인하세요.

중요 참고 사항

  • 금액 형식: Dub은 소수점 이하 두 자리 통화의 경우 센트 단위(예: $10.00은 1000)를 사용하고, JPY와 같은 소수점 이하 자릿수가 없는 통화의 경우 전체 정수를 사용합니다.
  • 통화: USD, EUR, GBP와 같은 ISO 4217 통화 코드를 사용하세요. Dub은 최신 환율로 각 판매를 USD로 변환합니다.
  • 무료 체험: Dub의 Track Sale API는 amount에 0를 허용합니다. 예시에서는 $0 결제를 건너뛰지 않으므로 각 $0 결제가 판매로 Dub에 도달합니다. $0 결제를 건너뛰려면 total_amount가 0일 때 webhook.cancel = true를 설정하세요.
  • 환불: 정확한 수익 보고가 필요하면 환불을 별도로 추적하세요.

문제 해결

  • Dub API key가 올바르고 conversions.write scope를 보유하는지 확인하세요.
  • dub_click_id가 캡처되어 결제 메타데이터에 저장되었는지 확인하세요.
  • webhook 변환이 페이로드 형식을 올바르게 지정하는지 확인하세요.
  • endpoint가 payment.succeeded를 구독하는지 확인하세요.
  • Dub 링크에서 전환 추적이 활성화되어 있는지 확인하세요.
  • Developer → Webhooks의 Logs 탭에서 endpoint의 전송 시도를 열어 Dub의 응답을 확인하세요. 클릭 ID가 없는 결제는 취소되며 성공으로 표시됩니다.
  • 고객이 결제 전에 Dub 단축 링크를 클릭하는지 확인하세요.
  • dub_id 쿠키가 도메인에 설정되는지 확인하세요.
  • 결제 메타데이터의 클릭 ID가 고객이 클릭한 항목과 일치하는지 확인하세요.
  • checkout을 생성하기 전에 클릭 ID를 캡처하세요.
  • 페이로드가 Dub의 Track Sale API 형식과 일치하는지 확인하세요.
  • 필수 필드인 customerExternalId와 amount가 있고, 어트리뷰션을 위해 clickId가 설정되었는지 확인하세요.
  • 금액이 소수가 아닌 가장 작은 통화 단위의 정수인지 확인하세요.
  • endpoint URL이 https://api.dub.co/track/sale인지 확인하세요.
  • 샘플 webhook 페이로드로 변환을 테스트하세요.
  • payment.succeeded 이벤트에서만 판매를 추적하고 payment.processing에서는 추적하지 마세요.
  • 각 판매에 고유한 invoiceId를 사용하세요. Dub은 각 invoiceId에 대해 하나의 판매만 기록합니다.
  • 갱신의 경우 Track Subscription Sales에 나온 것처럼 구독 ID와 결제 기간으로 invoiceId를 생성하세요. 현재 시간처럼 전송될 때마다 변경되는 값을 사용하면 전송이 재시도될 때 중복 판매가 기록됩니다.

추가 리소스

Dub Conversions Documentation

Dub의 전환 추적 및 분석 기능에 대해 알아보세요.

Dub Track Sale API

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

Dub Dashboard

Dub 대시보드에서 전환 분석 및 어트리뷰션 데이터를 확인하세요.

Webhook Events Guide

모든 Dodo Payments webhook 이벤트를 찾아보세요.
이 통합에 대한 도움이 필요하면 support@dodopayments.com으로 Dodo Payments 지원팀에 문의하세요.
마지막 수정일 2026년 9월 28일