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.
How It Works
Quando un visitatore fa clic su uno dei tuoi short link Dub, Dub memorizza un ID clic univoco nel cookiedub_id. Per attribuire le vendite ai tuoi link:
- Acquisisci l’ID clic di Dub dal cookie
dub_idquando crei il checkout. - Memorizza l’ID clic nel campo
metadatadel pagamento, insieme all’ID del cliente nel tuo sistema (l’ID esterno). - Invia la vendita a Dub tramite la sua Track API quando il pagamento va a buon fine.
Prerequisites
Prima di configurare questa integrazione, ti servono:- Un account Dub con un workspace.
- Il monitoraggio delle conversioni abilitato per i tuoi link.
- 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.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 inmetadata 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.

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.
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 quandometadata 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 handlerpayment.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 flagis_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 webhookpayment.succeeded. Il codice usa la tua chiave API di Dub, quindi eseguilo sul server, mai nel browser.
Best practice
- 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 = truequando 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
amountdi0e gli esempi non ignorano i pagamenti da $0, quindi ogni pagamento da $0 raggiunge Dub come vendita. Per ignorare i pagamenti da $0, impostawebhook.cancel = truequandototal_amountè0. - Rimborsi: se hai bisogno di una reportistica accurata dei ricavi, monitora i rimborsi separatamente.
Risoluzione dei problemi
Sales Not Appearing in Dub
Sales Not Appearing in Dub
- Verifica che la tua chiave API di Dub sia corretta e disponga dello scope
conversions.write. - Verifica che
dub_click_idsia 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.
Revenue Attribution Not Working
Revenue Attribution Not Working
- Verifica che i clienti facciano clic sui tuoi short link Dub prima del checkout.
- Verifica che il cookie
dub_idsia 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.
Transformation Errors
Transformation Errors
- Verifica che il payload corrisponda al formato della Track Sale API di Dub.
- Verifica che i campi obbligatori,
customerExternalIdeamount, siano presenti e checlickIdsia 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.
Duplicate Sales Being Tracked
Duplicate Sales Being Tracked
- Monitora le vendite solo sugli eventi
payment.succeeded, non supayment.processing. - Usa un
invoiceIdunivoco per ogni vendita. Dub registra una sola vendita per ogniinvoiceId. - Per i rinnovi, crea
invoiceIda 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.