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 一起包含在您的支付元数据中。

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 端点，在支付成功时将销售数据发送到 Dub 的 Track API。

Open the Webhook Section

在您的 Dodo Payments 仪表板中，导航到 Webhooks → + Add Endpoint 并展开集成下拉菜单。

选择 Dub

选择 Dub 集成卡片。

Enter API Key

在配置字段中提供您的 Dub API 密钥。

配置转换

编辑转换代码以格式化支付数据以适应 Dub 的 Track Sale API。

测试并创建

使用示例有效负载进行测试，然后单击创建以激活集成。

转换代码示例

基本销售跟踪

在支付成功时跟踪销售：

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

替代方案：客户端实现

如果您更喜欢从服务器跟踪销售而不是使用 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：在结账流程中尽早存储 Dub 点击 ID，以确保准确的归因，即使用户导航离开并稍后返回。

始终在元数据中包含点击 ID：没有点击 ID，Dub 无法将收入归因于您的链接
一致使用外部 ID：传递您在系统中使用的相同客户 ID，以便进行准确的客户级分析
优雅处理自然流量：在没有点击 ID 时设置 webhook.cancel = true 以避免不必要的 API 调用
使用示例支付进行测试：在上线之前验证集成是否正常工作
监控您的 Dub 仪表板：检查销售是否正确显示并具有适当的归因

重要说明

金额格式：Dub 期望金额以美分为单位（例如，$10.00 = 1000）
货币：使用 ISO 4217 货币代码（USD、EUR、GBP 等）
免费试用：$0 的支付不会被跟踪为销售
退款：如有需要，考虑单独跟踪退款以进行准确的收入报告

故障排除

销售未出现在 Dub 中

验证您的 Dub API 密钥是否正确，并具有 conversions.write 范围
检查 dub_click_id 是否被捕获并存储在支付元数据中
确保 webhook 转换正确格式化有效负载
验证 webhook 是否在 payment.succeeded 事件上触发
确认为您的 Dub 链接启用了转化跟踪

转换错误

验证 JSON 结构是否符合 Dub 的 Track Sale API 格式
检查所有必需字段 (clickId, externalId, amount) 是否存在
确保金额以美分为单位（整数，而不是小数）
验证 API 端点 URL 是否正确：https://api.dub.co/track/sale
使用示例 webhook 有效负载测试转换

重复销售被跟踪

确保您仅在 payment.succeeded 事件上进行跟踪，而不是 payment.processing
为每笔销售使用唯一的 invoiceId 值
对于订阅，在续订时附加时间戳或计费周期以防止重复

其他资源

Dub 转化文档

了解有关 Dub 的转化跟踪和分析功能的更多信息。

Dub Track Sale API

查看 Dub 的 Track Sale 端点的完整 API 参考。

Dub 仪表板

访问您的 Dub 仪表板以查看转化分析和归因数据。

Webhook 事件指南

了解所有可用的 Dodo Payments webhook 事件。

需要帮助吗？请联系 Dodo Payments 支持，邮箱 support@dodopayments.com，以获取集成的帮助。

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

介绍

工作原理

先决条件

开始使用

实施指南

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

第 2 步：将销售数据发送到 Dub

转换代码示例

基本销售跟踪

跟踪订阅销售

跟踪不含税销售

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

替代方案：客户端实现

最佳实践

重要说明

故障排除

其他资源

Dub 转化文档

Dub Track Sale API

Dub 仪表板

Webhook 事件指南

​介绍

​工作原理

​先决条件

​开始使用

​实施指南

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

​第 2 步：将销售数据发送到 Dub

​转换代码示例

​基本销售跟踪

​跟踪订阅销售

​跟踪不含税销售

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

​替代方案：客户端实现

​最佳实践

​重要说明

​故障排除

​其他资源

Dub 转化文档

Dub Track Sale API

Dub 仪表板

Webhook 事件指南

介绍

工作原理

先决条件

开始使用

实施指南

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

第 2 步：将销售数据发送到 Dub

转换代码示例

基本销售跟踪

跟踪订阅销售

跟踪不含税销售

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

替代方案：客户端实现

最佳实践

重要说明

故障排除

其他资源