Dub

介绍

Dub 是一个强大的链接管理平台，帮助您创建、分享和跟踪短链接。通过将 Dodo Payments 与 Dub 集成，您可以在客户完成购买时自动跟踪销售转化事件，使您能够衡量营销活动和推荐计划的投资回报率。当客户完成以下操作时，Dub 会记录一个 “销售” 事件：

完成一次性付款
订阅付费计划
进行定期订阅付款

此集成需要在您的链接上启用转化跟踪的 Dub 账户。

联盟计划集成：此集成还与 Dub Partners 无缝协作，以跟踪联盟推荐和佣金。使用 Dub 的转化跟踪将销售归因于您的联盟链接，并衡量合作伙伴的表现。了解有关设置联盟计划的更多信息，请参阅我们的联盟功能指南。

工作原理

当用户点击您的 Dub 短链接时，Dub 通过存储在 cookie 中的唯一点击 ID (dub_id) 跟踪访客。要将销售归因于您的链接，您需要：

在创建结账会话时捕获 Dub 的点击 ID，从 dub_id cookie 中获取
将点击 ID 存储在您的支付元数据中，连同客户的外部 ID
在支付成功时通过其 Track API 发送销售数据到 Dub

这使得 Dub 能够将成功的销售与原始链接点击匹配，从而为您提供完整的转化归因。

先决条件

在设置此集成之前，请确保您拥有：

一个 Dub 账户和一个工作区
为您的链接启用转化跟踪
您的 Dub API 密钥（可在您的 Dub 仪表板的设置 → API 密钥中找到）

开始使用

在 Dub 中启用转化跟踪

在您的 Dub 仪表板中，为您想要跟踪销售的链接启用转化跟踪。这允许 Dub 在客户完成购买时记录销售事件。

了解有关在 Dub 文档中启用转化跟踪的更多信息。

获取您的 Dub API 密钥

导航到您的 Dub 仪表板 → 设置 → API 密钥，并创建一个具有 conversions.write 范围的新 API 密钥。

保持您的 API 密钥安全，切勿在客户端代码中暴露它。

在结账中捕获点击 ID

在创建结账会话时，从 cookie 中捕获 Dub 点击 ID，并将其添加到您的支付元数据中。

通过 Webhook 发送销售数据

配置一个 webhook，在支付成功时将销售数据发送到 Dub 的 Track API。

完成！

销售转化事件现在将在您的 Dub 分析仪表板中显示，并完全归因于您的链接。

实施指南

第 1 步：将点击 ID 和客户 ID 添加到结账元数据

在创建结账会话时，从 cookie 中捕获 Dub 点击 ID，并将其与客户的外部 ID 一起包含在您的支付元数据中。

以下示例使用 POST /payments，该方式已被弃用。对于现有集成仍然有效，但新集成应使用 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 发送销售数据

配置 webhook endpoint，以便在支付成功时将销售数据发送到 Dub 的 Track API。

Open the Webhook Section

在 Dodo Payments dashboard 中，前往 Webhooks → + Add Endpoint，然后展开 integrations 下拉菜单。

Select Dub

选择 Dub integration card。

Enter API Key

在配置字段中提供你的 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;
}

跟踪订阅销售

跟踪初始订阅和 recurring payments：

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 实现

如果你更希望从服务器跟踪销售，而不是使用 webhooks，可以在支付成功后直接调用 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,
    });
  }
}

最佳实践

尽早捕获 click ID：在 checkout 流程中尽快存储 Dub click ID，以确保准确归因，即使用户离开后稍后返回也不受影响。

始终在 metadata 中包含 click ID：没有 click ID，Dub 无法将收入归因到你的链接
一致使用 external IDs：传递你系统中使用的相同 customer ID，以便进行准确的客户级分析
妥善处理 organic traffic：没有 click ID 时设置 webhook.cancel = true，以避免不必要的 API 调用
使用示例支付进行测试：在正式上线前验证集成是否正常工作
监控你的 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 是否已被捕获并存储在 payment metadata 中
确保 webhook transformation 正确格式化 payload
验证 webhook 是否在 payment.succeeded events 上触发
确认你的 Dub 链接已启用 conversion tracking

Revenue attribution not working

确认用户在 checkout 前点击了你的 Dub short links
验证 dub_id cookie 是否已在你的 domain 上正确设置
检查 click IDs 在 checkout 创建和支付完成之间是否匹配
确保在创建 checkout session 前捕获 click ID

Transformation errors

验证 JSON structure 是否符合 Dub 的 Track Sale API format
检查所有必需字段（clickId、externalId、amount）是否存在
确保 amount 以 cents 表示（整数，而非小数）
验证 API endpoint URL 是否正确：https://api.dub.co/track/sale
使用示例 webhook payload 测试 transformation

Duplicate sales being tracked

确保仅在 payment.succeeded events 上进行跟踪，而不是 payment.processing
为每笔销售使用唯一的 invoiceId 值
对于订阅，在其中附加 timestamps 或 billing period，以防续费时产生重复

其他资源

Dub Conversions Documentation

详细了解 Dub 的 conversion tracking 和 analytics 功能。

Dub Track Sale API

查看 Dub Track Sale endpoint 的完整 API reference。

Dub Dashboard

访问你的 Dub dashboard，查看 conversion analytics 和 attribution data。

Webhook Events Guide

了解所有可用的 Dodo Payments webhook events。

需要帮助？请通过 support@dodopayments.com 联系 Dodo Payments support，以获得集成方面的帮助。

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

介绍

工作原理

先决条件

开始使用

实施指南

第 1 步：将点击 ID 和客户 ID 添加到结账元数据

步骤 2：向 Dub 发送销售数据

Transformation Code 示例

基本销售跟踪

跟踪订阅销售

排除税费后跟踪销售

使用自定义事件名称跟踪销售

替代方案：Client-Side 实现

最佳实践

重要说明

故障排除

其他资源

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

​介绍

​工作原理

​先决条件

​开始使用

​实施指南

​第 1 步：将点击 ID 和客户 ID 添加到结账元数据

​步骤 2：向 Dub 发送销售数据

​Transformation Code 示例

​基本销售跟踪

​跟踪订阅销售

​排除税费后跟踪销售

​使用自定义事件名称跟踪销售

​替代方案：Client-Side 实现

​最佳实践

​重要说明

​故障排除

​其他资源

Dub Conversions Documentation

Dub Track Sale API

Dub Dashboard

Webhook Events Guide

介绍

工作原理

先决条件

开始使用

实施指南

第 1 步：将点击 ID 和客户 ID 添加到结账元数据

步骤 2：向 Dub 发送销售数据

Transformation Code 示例

基本销售跟踪

跟踪订阅销售

排除税费后跟踪销售

使用自定义事件名称跟踪销售

替代方案：Client-Side 实现

最佳实践

重要说明

故障排除

其他资源