Skip to main content

Introduction

Dub è una piattaforma di attribuzione dei link per short link, monitoraggio delle conversioni e programmi di affiliazione. Con questa integrazione, Dub registra un evento di conversione della vendita ogni volta che un cliente paga tramite Dodo Payments, consentendoti di misurare il rendimento delle tue campagne di marketing e dei programmi di referral. Dub registra una vendita quando un cliente:
  • Completa un pagamento una tantum
  • Si abbona a un piano a pagamento
  • Effettua un pagamento ricorrente dell’abbonamento
Questa integrazione richiede un account Dub con il monitoraggio delle conversioni abilitato sui tuoi link. Il monitoraggio delle conversioni di Dub richiede un piano Business o superiore.
Integrazione del programma di affiliazione: questa integrazione funziona anche con Dub Partners, il prodotto per programmi di affiliazione di Dub. Dub attribuisce le vendite ai link di affiliazione dei tuoi partner, così puoi monitorare referral, commissioni e le prestazioni di ciascun partner. Per configurare un programma di affiliazione, consulta la guida alla funzionalità Affiliates.

How It Works

Quando un visitatore fa clic su uno dei tuoi short link Dub, Dub memorizza un ID clic univoco nel cookie dub_id. Per attribuire le vendite ai tuoi link:
  1. Acquisisci l’ID clic di Dub dal cookie dub_id quando crei il checkout.
  2. Memorizza l’ID clic nel campo metadata del pagamento, insieme all’ID del cliente nel tuo sistema (l’ID esterno).
  3. Invia la vendita a Dub tramite la sua Track API quando il pagamento va a buon fine.
Dub associa ogni vendita completata al clic sul link originale, attribuendo così la conversione a quel link.

Prerequisites

Prima di configurare questa integrazione, ti servono:
  1. Un account Dub con un workspace.
  2. Il monitoraggio delle conversioni abilitato per i tuoi link.
  3. Una chiave API Dub, che puoi creare nella dashboard Dub in Settings → API Keys.

Getting Started

1

Enable Conversion Tracking in Dub

Nella dashboard Dub, abilita il monitoraggio delle conversioni per i link per i quali vuoi monitorare le vendite. Dub registrerà quindi gli eventi di vendita per i clienti che arrivano tramite quei link.
Per abilitare il monitoraggio delle conversioni, consulta la documentazione di Dub.
2

Get Your Dub API Key

Nella tua dashboard Dub, vai su Settings → API Keys e crea una chiave API con l’ambito conversions.write.
Mantieni sicura la tua chiave API. Non esporla mai nel codice lato client.
3

Capture Click ID in Checkout

Quando crei un checkout, leggi l’ID clic di Dub dal cookie e aggiungilo a metadata del pagamento. Consulta lo Step 1.
4

Send Sale Data via Webhook

Crea un endpoint webhook che invii ogni vendita alla Track API di Dub quando un pagamento va a buon fine. Consulta lo Step 2.
5

Done

Gli eventi di conversione delle vendite vengono visualizzati nella dashboard di analisi Dub, attribuiti ai tuoi link.

Implementation Guide

Step 1: Add Click ID and Customer ID to Checkout Metadata

Quando crei un checkout, leggi l’ID clic di Dub dal cookie e includilo in metadata del pagamento, insieme all’ID esterno del cliente.
Gli esempi seguenti utilizzano POST /payments, che è deprecato. Funziona ancora per le integrazioni esistenti, ma per le nuove integrazioni dovresti usare Checkout Sessions (POST /checkouts), che accettano metadata nello stesso modo.

Passaggio 2: invia i dati delle vendite a Dub

Crea un endpoint webhook che invii i dati della vendita alla Track API di Dub quando un pagamento va a buon fine.
1

Open the Webhook Section

Nella dashboard di Dodo Payments, vai a Developer → Webhooks e fai clic su Add endpoint.
Add endpoint dialog with Dub.co selected in the Integration dropdown
2

Select Dub

In Integration, seleziona Dub.co.
3

Enter API Key

In API key, incolla la tua chiave API di Dub. Dodo Payments la invia nell’header Authorization di ogni delivery.
API key field for the Dub integration
4

Check the URL and Events

Se Endpoint URL è vuoto, inserisci https://api.dub.co/track/sale. In Subscribed events, seleziona gli eventi gestiti dalla tua transformation, come payment.succeeded.
5

Configure Transformation

In Transformation code, modifica l’handler per formattare i dati dei pagamenti per la Track Sale API di Dub. Inizia dagli esempi.
6

Test & Create

In Test this code, fai clic su Simulate per eseguire l’handler su un payload di esempio. Quindi fai clic su Create endpoint.

Esempi di Transformation Code

Ogni handler invia una vendita a Dub solo quando metadata contiene un ID clic. Per il traffico organico, privo di ID clic, imposta webhook.cancel = true, quindi non viene inviata alcuna richiesta a Dub; la delivery annullata viene comunque mostrata come riuscita nei log del webhook. Il corpo della richiesta segue la Track Sale API di Dub: customerExternalId e amount sono obbligatori, mentre paymentProcessor è custom, perché l’elenco dei payment processor di Dub non contiene un valore Dodo Payments. Dub interpreta amount nella stessa unità degli importi di Dodo Payments: centesimi per le valute con due decimali e il numero intero completo per le valute senza decimali, come JPY. Gli esempi passano l’importo senza modificarlo.

Monitoraggio delle vendite di base

Monitora una vendita quando un pagamento va a buon fine:
basic_sale.js

Monitoraggio delle vendite degli abbonamenti

Monitora sia gli abbonamenti iniziali sia i pagamenti ricorrenti. Usa questo handler per gli abbonamenti invece degli handler payment.succeeded, non insieme a essi: ogni pagamento di un abbonamento attiva anche payment.succeeded, quindi la gestione di entrambi gli eventi registra ogni vendita due volte. Consulta la guida all’integrazione degli abbonamenti. L’handler legge l’ID clic dai metadata dell’abbonamento, quindi passa gli stessi metadata quando crei l’abbonamento. Per i rinnovi, invoiceId combina l’ID dell’abbonamento con previous_billing_date, l’inizio del periodo di fatturazione corrente, così una delivery ritentata riutilizza lo stesso invoiceId.
subscription_sale.js

Monitoraggio delle vendite con esclusione delle imposte

Invia a Dub solo l’importo al netto delle imposte, in modo che i ricavi in Dub escludano le imposte:
sale_without_tax.js

Monitoraggio delle vendite con nomi di eventi personalizzati

Usa nomi di eventi personalizzati per classificare diversi tipi di vendite. L’esempio legge un flag is_upgrade che imposti nei metadata del pagamento:
custom_events.js

Alternativa: implementazione lato client

Per monitorare le vendite dal tuo server invece di usare una transformation del webhook, chiama direttamente la Track API di Dub dopo un pagamento completato, ad esempio dal tuo handler del webhook payment.succeeded. Il codice usa la tua chiave API di Dub, quindi eseguilo sul server, mai nel browser.

Best practice

Acquisisci presto l’ID clic: salva l’ID clic di Dub il prima possibile nel flusso di checkout, così l’attribuzione rimane accurata anche se il cliente abbandona il processo e torna in un secondo momento.
  • Includi l’ID clic nei metadata: senza l’ID clic, Dub non può attribuire i ricavi ai tuoi link.
  • Usa gli ID esterni in modo coerente: passa ogni volta lo stesso ID cliente del tuo sistema come customerExternalId, per ottenere analisi accurate a livello di cliente.
  • Gestisci il traffico organico: imposta webhook.cancel = true quando non è presente un ID clic, per evitare chiamate API non necessarie.
  • Esegui test con pagamenti di esempio: esegui l’handler con Test this code e verifica che l’integrazione funzioni prima di andare in produzione.
  • Monitora la dashboard di Dub: verifica che le vendite compaiano con l’attribuzione prevista.

Note importanti

  • Formato dell’importo: Dub si aspetta gli importi in centesimi per le valute con due decimali (ad esempio, $10.00 è 1000) e il numero intero completo per le valute senza decimali, come JPY.
  • Valuta: usa i codici valuta ISO 4217, come USD, EUR e GBP. Dub converte ogni vendita in USD al tasso di cambio più recente.
  • Prove gratuite: la Track Sale API di Dub accetta un amount di 0 e gli esempi non ignorano i pagamenti da $0, quindi ogni pagamento da $0 raggiunge Dub come vendita. Per ignorare i pagamenti da $0, imposta webhook.cancel = true quando total_amount è 0.
  • Rimborsi: se hai bisogno di una reportistica accurata dei ricavi, monitora i rimborsi separatamente.

Risoluzione dei problemi

  • Verifica che la tua chiave API di Dub sia corretta e disponga dello scope conversions.write.
  • Verifica che dub_click_id sia acquisito e memorizzato nei metadata del pagamento.
  • Verifica che la transformation del webhook formatti correttamente il payload.
  • Verifica che l’endpoint sia sottoscritto a payment.succeeded.
  • Verifica che il conversion tracking sia abilitato per i tuoi link Dub.
  • Apri i tentativi di delivery dell’endpoint nella scheda Logs di Developer → Webhooks per visualizzare la risposta di Dub. Un pagamento senza ID clic viene annullato e mostrato come riuscito.
  • Verifica che i clienti facciano clic sui tuoi short link Dub prima del checkout.
  • Verifica che il cookie dub_id sia impostato sul tuo dominio.
  • Verifica che l’ID clic nei metadata del pagamento corrisponda al clic effettuato dal cliente.
  • Acquisisci l’ID clic prima di creare il checkout.
  • Verifica che il payload corrisponda al formato della Track Sale API di Dub.
  • Verifica che i campi obbligatori, customerExternalId e amount, siano presenti e che clickId sia impostato per l’attribuzione.
  • Verifica che l’importo sia un numero intero nell’unità monetaria più piccola, non un decimale.
  • Verifica che l’URL dell’endpoint sia https://api.dub.co/track/sale.
  • Testa la transformation con payload di webhook di esempio.
  • Monitora le vendite solo sugli eventi payment.succeeded, non su payment.processing.
  • Usa un invoiceId univoco per ogni vendita. Dub registra una sola vendita per ogni invoiceId.
  • Per i rinnovi, crea invoiceId a partire dall’ID dell’abbonamento e dal periodo di fatturazione, come indicato in Monitoraggio delle vendite degli abbonamenti. Un valore che cambia a ogni delivery, come l’ora corrente, registra una vendita duplicata quando una delivery viene ritentata.

Risorse aggiuntive

Dub Conversions Documentation

Scopri di più sulle funzionalità di conversion tracking e analisi di Dub.

Dub Track Sale API

Consulta la documentazione API completa dell’endpoint Track Sale di Dub.

Dub Dashboard

Visualizza le analisi delle conversioni e i dati di attribuzione nella tua dashboard di Dub.

Webhook Events Guide

Esplora tutti gli eventi webhook di Dodo Payments.
Per ricevere assistenza su questa integrazione, contatta il supporto di Dodo Payments all’indirizzo support@dodopayments.com.
Ultima modifica il 26 settembre 2026