Vai al contenuto principale

​
Introduzione

DataFast è uno strumento di analisi focalizzato sul fatturato che ti aiuta a scoprire quali canali di marketing generano clienti paganti. Integrando Dodo Payments con DataFast, puoi attribuire il fatturato alle tue fonti di traffico, identificare segmenti di clienti ad alto valore e prendere decisioni basate sui dati per far crescere la tua attività.
Questa integrazione richiede la tua chiave API di DataFast, che puoi ottenere dal tuo DataFast dashboard.

​
Come Funziona

DataFast traccia i visitatori attraverso un ID visitatore unico memorizzato in un cookie. Per attribuire il fatturato ai canali di marketing, devi:
  1. Cattura l’ID visitatore di DataFast dal cookie datafast_visitor_id quando crei sessioni di checkout
  2. Memorizza l’ID visitatore nei metadati del pagamento
  3. Invia i dati di pagamento a DataFast quando i pagamenti vanno a buon fine utilizzando la loro Payment API
Questo consente a DataFast di abbinare i pagamenti riusciti con la fonte di traffico originale, fornendoti un’attribuzione completa del fatturato.

​
Iniziare

1

Install DataFast Script

Per prima cosa, installa lo script di tracciamento di DataFast sul tuo sito. Questo crea il cookie datafast_visitor_id che traccia i tuoi visitatori.Visita la documentazione di DataFast per le istruzioni di installazione specifiche per la tua piattaforma.
2

Get Your API Key

Accedi al tuo DataFast dashboard e vai alle impostazioni del sito per ottenere la tua chiave API.
Tieni la tua chiave API al sicuro e non esporla mai nel codice lato client.
3

Capture Visitor ID in Checkout

Quando crei una sessione di checkout, cattura l’ID visitatore di DataFast dal cookie e aggiungilo ai metadati del pagamento.
4

Send Payment Data via Webhook

Configura un webhook per inviare i dati di pagamento alla Payment API di DataFast quando i pagamenti vanno a buon fine.
5

Done!

🎉 I dati di fatturato appariranno ora nel tuo dashboard di DataFast con piena attribuzione ai canali di marketing.

​
Guida all’Implementazione

​
Passo 1: Aggiungi l’ID Visitatore ai Metadati del Checkout

Quando crei una sessione di checkout, cattura l’ID visitatore di DataFast dal cookie e includilo nei tuoi metadati di pagamento. 
import { cookies } from 'next/headers';
import { dodopayments } from '@/lib/dodopayments';

export async function createCheckout(productId: string) {
  // Capture DataFast visitor ID from cookie
  const datafastVisitorId = cookies().get('datafast_visitor_id')?.value;

  const payment = await dodopayments.payments.create({
    product_id: productId,
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });

  return payment;
}

​
Passo 2: Invia Dati di Pagamento a DataFast

Configura un endpoint webhook per inviare i dati di pagamento all’API di pagamento di DataFast quando i pagamenti hanno successo.
1

Open the Webhook Section

Nel tuo dashboard Dodo Payments, vai su Webhooks → + Aggiungi endpoint e espandi il menu a discesa delle integrazioni.
Aggiungi endpoint e menu a discesa delle integrazioni
2

Select DataFast

Scegli la scheda di integrazione DataFast.
3

Enter API Key

Inserisci la tua chiave API di DataFast nel campo di configurazione.
Aggiungi chiave API
4

Configure Transformation

Modifica il codice di trasformazione per formattare i dati di pagamento per la Payment API di DataFast.
5

Test & Create

Testa con payload di esempio e clicca su Crea per attivare l’integrazione.

​
Esempi di Codice di Trasformazione

​
Attribuzione di Pagamento di Base

basic_payment.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Only send to DataFast if visitor ID exists in metadata
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100, // Convert from cents to dollars
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Gestisci Valute Senza Decimali

Alcune valute (come JPY) non utilizzano i decimali. Regola di conseguenza il calcolo dell’importo:
zero_decimal.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      // Zero decimal currencies: JPY, KRW, CLP, etc.
      const zeroDecimalCurrencies = ['JPY', 'KRW', 'CLP', 'VND', 'UGX', 'MGA'];
      const isZeroDecimal = zeroDecimalCurrencies.includes(payment.currency);
      
      webhook.payload = {
        amount: isZeroDecimal 
          ? payment.total_amount // Use amount as-is for zero decimal currencies
          : payment.total_amount / 100, // Convert from cents for other currencies
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Pagamenti in Abbonamento

Per i pagamenti ricorrenti in abbonamento, puoi tracciare ogni pagamento:
subscription_payment.js
function handler(webhook) {
  if (webhook.eventType === "payment.succeeded") {
    const payment = webhook.payload.data;
    
    // Check if this is a subscription payment
    const isSubscription = payment.subscription_id !== null;
    
    if (payment.metadata && payment.metadata.datafast_visitor_id) {
      webhook.payload = {
        amount: payment.total_amount / 100,
        currency: payment.currency,
        transaction_id: payment.payment_id,
        datafast_visitor_id: payment.metadata.datafast_visitor_id,
        // Optional: Add subscription context
        ...(isSubscription && {
          subscription_id: payment.subscription_id,
        }),
      };
    } else {
      // Cancel dispatch if no visitor ID (prevents unnecessary API calls)
      webhook.cancel = true;
    }
  }
  return webhook;
}

​
Migliori Pratiche

Cattura l’ID visitatore il prima possibile: conserva l’ID visitatore di DataFast appena possibile nel tuo flusso di checkout per garantire un’attribuzione accurata, anche se l’utente lascia la pagina e torna più tardi.
  • Includi sempre l’ID visitatore nei metadati: Senza l’ID visitatore, DataFast non può attribuire il fatturato ai canali di marketing
  • Gestisci le valute senza decimali: Alcune valute (JPY, KRW, ecc.) non utilizzano i decimali: regola di conseguenza il calcolo dell’importo
  • Testa con pagamenti di esempio: Verifica che l’integrazione funzioni correttamente prima di andare in produzione
  • Monitora il tuo dashboard di DataFast: Controlla che i pagamenti appaiano correttamente con l’attribuzione adeguata
  • Utilizza i retry dei webhook: L’API di pagamento di DataFast è idempotente, quindi i retry sono sicuri se un webhook fallisce

​
Risoluzione dei Problemi

  • Verifica che la tua chiave API di DataFast sia corretta e attiva
  • Controlla che datafast_visitor_id venga catturato e memorizzato nei metadati del pagamento
  • Assicurati che la trasformazione del webhook stia formattando correttamente il payload
  • Verifica che il webhook si attivi sugli eventi payment.succeeded
  • Controlla il dashboard di DataFast per eventuali messaggi di errore o log delle API
  • Conferma che lo script di tracciamento di DataFast sia installato e funzionante sul tuo sito
  • Verifica che il cookie datafast_visitor_id venga impostato correttamente
  • Controlla che gli ID visitatore corrispondano tra la creazione del checkout e il completamento del pagamento
  • Assicurati di catturare l’ID visitatore prima di creare la sessione di checkout
  • Consulta la documentazione della Payment API di DataFast per ulteriori indicazioni
  • Verifica che la struttura JSON corrisponda al formato della Payment API di DataFast
  • Controlla che tutti i campi obbligatori (amount, currency, transaction_id, datafast_visitor_id) siano presenti
  • Assicurati che l’importo sia correttamente convertito (dividi per 100 per la maggior parte delle valute, tranne quelle a zero decimali)
  • Verifica che l’URL dell’endpoint API sia corretto: https://datafa.st/api/v1/payments
  • Testa la trasformazione con payload di esempio del webhook
  • Per le valute a zero decimali (JPY, KRW, CLP, VND, UGX, MGA), invia l’importo così com’è senza dividere per 100
  • Per tutte le altre valute, dividi l’importo per 100 per convertire dai centesimi all’unità di base
  • Ricontrolla che il codice valuta corrisponda al formato ISO 4217 (ad esempio, “USD”, “EUR”, “JPY”)

​
Risorse Aggiuntive

DataFast Documentation

Scopri di più sulla Payment API di DataFast e sulle funzionalità di attribuzione del fatturato.

DataFast Dashboard

Accedi al tuo dashboard di DataFast per visualizzare l’analisi dei ricavi e i dati di attribuzione.
Hai bisogno di aiuto? Contatta l’assistenza di Dodo Payments all’indirizzo support@dodopayments.com per assistenza con l’integrazione.