Pular para o conteúdo principal

​
Introdução

Dub é uma poderosa plataforma de gerenciamento de links que ajuda você a criar, compartilhar e rastrear links curtos. Ao integrar o Dodo Payments com o Dub, você pode rastrear automaticamente eventos de conversão de vendas quando os clientes completam compras, permitindo que você meça o ROI de suas campanhas de marketing e programas de referência. Um evento de “venda” é registrado no Dub quando um cliente:
  • Completa um pagamento único
  • Se inscreve em um plano pago
  • Faz um pagamento de assinatura recorrente
Esta integração requer uma conta Dub com rastreamento de conversão habilitado em seus links.

​
Como Funciona

O Dub rastreia visitantes através de um ID de clique único (dub_id) armazenado em um cookie quando os usuários clicam em seus links curtos do Dub. Para atribuir vendas aos seus links, você precisa:
  1. Capturar o ID de clique do Dub do cookie dub_id ao criar sessões de checkout
  2. Armazenar o ID de clique em seus metadados de pagamento junto com o ID externo do cliente
  3. Enviar dados de venda para o Dub quando os pagamentos forem bem-sucedidos usando sua API Track
Isso permite que o Dub associe vendas bem-sucedidas ao clique original do link, dando a você uma atribuição completa de conversão.

​
Pré-requisitos

Antes de configurar esta integração, certifique-se de que você tem:
  1. Uma conta Dub com um espaço de trabalho
  2. Rastreamento de conversão habilitado para seus links
  3. Sua chave API do Dub (disponível no seu painel do Dub em Configurações → Chaves API)

​
Começando

1

Habilitar Rastreamento de Conversão no Dub

No seu painel do Dub, habilite o rastreamento de conversão para os links que você deseja rastrear vendas. Isso permite que o Dub registre eventos de venda quando os clientes completam compras.
Saiba mais sobre como habilitar o rastreamento de conversão na documentação do Dub.
2

Obter Sua Chave API do Dub

Navegue até seu painel do Dub → Configurações → Chaves API e crie uma nova chave API com o escopo conversions.write.
Mantenha sua chave API segura e nunca a exponha em código do lado do cliente.
3

Capturar ID de Clique no Checkout

Ao criar uma sessão de checkout, capture o ID de clique do Dub do cookie e adicione-o aos seus metadados de pagamento.
4

Enviar Dados de Venda via Webhook

Configure um webhook para enviar dados de venda para a API Track do Dub quando os pagamentos forem bem-sucedidos.
5

Pronto!

Eventos de conversão de vendas agora aparecerão no seu painel de análises do Dub com atribuição completa aos seus links.

​
Guia de Implementação

​
Passo 1: Adicionar ID de Clique e ID do Cliente aos Metadados do Checkout

Ao criar uma sessão de checkout, capture o ID de clique do Dub do cookie e inclua-o em seus metadados de pagamento junto com o ID externo do seu cliente. 
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: '[email protected]',
      name: 'John Doe',
    },
    product_id: productId,
    metadata: {
      dub_click_id: dubClickId,           // Store Dub click ID
      dub_external_id: customerId,        // Store your customer's unique ID
    },
  });

  return payment;
}

​
Passo 2: Enviar Dados de Venda para o Dub

Configure um endpoint de webhook para enviar dados de venda para a API Track do Dub quando os pagamentos forem bem-sucedidos.
1

Abrir a Seção de Webhook

No seu painel do Dodo Payments, navegue até Webhooks → + Adicionar Endpoint e expanda o menu suspenso de integrações.
Adicionar Endpoint e menu suspenso de integrações
2

Selecionar Dub

Escolha o cartão de integração Dub.
3

Inserir Chave API

Forneça sua Chave API do Dub no campo de configuração.
Adicionar Chave API
4

Configurar Transformação

Edite o código de transformação para formatar os dados de pagamento para a API Track Sale do Dub.
5

Testar e Criar

Teste com cargas úteis de exemplo e clique em Criar para ativar a integração.

​
Exemplos de Código de Transformação

​
Rastreamento Básico de Vendas

Rastreie vendas quando os pagamentos forem bem-sucedidos:
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;
}

​
Rastrear Vendas de Assinatura

Rastreie tanto assinaturas iniciais quanto pagamentos recorrentes:
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;
}

​
Rastrear Vendas com Exclusão de Impostos

Envie apenas o valor antes dos impostos para o Dub para rastreamento preciso de receita:
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;
}

​
Rastrear Vendas com Nomes de Eventos Personalizados

Use nomes de eventos personalizados para categorizar diferentes tipos de vendas:
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;
}

​
Alternativa: Implementação do Lado do Cliente

Se você preferir rastrear vendas do seu servidor em vez de usar webhooks, pode chamar a API Track do Dub diretamente após um pagamento bem-sucedido: 
'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,
  });
}

​
Melhores Práticas

Capture o ID de clique cedo: Armazene o ID de clique do Dub o mais rápido possível em seu fluxo de checkout para garantir atribuição precisa, mesmo que o usuário navegue para longe e retorne mais tarde.
  • Sempre inclua o ID de clique nos metadados: Sem o ID de clique, o Dub não pode atribuir receita aos seus links
  • Use IDs externos de forma consistente: Passe o mesmo ID de cliente que você usa em seu sistema para análises precisas em nível de cliente
  • Lide com tráfego orgânico de forma adequada: Defina webhook.cancel = true quando não houver ID de clique para evitar chamadas desnecessárias à API
  • Teste com pagamentos de exemplo: Verifique se a integração funciona corretamente antes de entrar em produção
  • Monitore seu painel do Dub: Verifique se as vendas estão aparecendo corretamente com a atribuição adequada

​
Notas Importantes

  • Formato do valor: O Dub espera valores em centavos (por exemplo, $10.00 = 1000)
  • Moeda: Use códigos de moeda ISO 4217 (USD, EUR, GBP, etc.)
  • Testes gratuitos: Pagamentos de $0 não são rastreados como vendas
  • Reembolsos: Considere rastrear reembolsos separadamente, se necessário, para relatórios precisos de receita

​
Solução de Problemas

  • Verifique se sua chave API do Dub está correta e tem o escopo conversions.write
  • Verifique se o dub_click_id está sendo capturado e armazenado nos metadados de pagamento
  • Certifique-se de que a transformação do webhook está formatando corretamente a carga útil
  • Verifique se o webhook está sendo acionado em eventos payment.succeeded
  • Confirme se o rastreamento de conversão está habilitado para seus links do Dub
  • Confirme se os usuários estão clicando em seus links curtos do Dub antes do checkout
  • Verifique se o cookie dub_id está sendo definido corretamente em seu domínio
  • Verifique se os IDs de clique correspondem entre a criação do checkout e a conclusão do pagamento
  • Certifique-se de que você está capturando o ID de clique antes de criar a sessão de checkout
  • Valide se a estrutura JSON corresponde ao formato da API Track Sale do Dub
  • Verifique se todos os campos obrigatórios (clickId, externalId, amount) estão presentes
  • Certifique-se de que o valor está em centavos (inteiro, não decimal)
  • Verifique se a URL do endpoint da API está correta: https://api.dub.co/track/sale
  • Teste a transformação com cargas úteis de webhook de exemplo
  • Certifique-se de que você está rastreando apenas em eventos payment.succeeded, não em payment.processing
  • Use valores únicos invoiceId para cada venda
  • Para assinaturas, anexe timestamps ou períodos de cobrança para evitar duplicatas em renovações

​
Recursos Adicionais

Documentação de Conversões do Dub

Saiba mais sobre o rastreamento de conversão e recursos de análise do Dub.

API Track Sale do Dub

Veja a referência completa da API para o endpoint Track Sale do Dub.

Painel do Dub

Acesse seu painel do Dub para visualizar análises de conversão e dados de atribuição.

Guia de Eventos de Webhook

Aprenda sobre todos os eventos de webhook disponíveis do Dodo Payments.
Precisa de ajuda? Entre em contato com o suporte do Dodo Payments em [email protected] para assistência com a integração.