DataFast

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:

Cattura l’ID visitatore di DataFast dal cookie datafast_visitor_id quando crei sessioni di checkout
Memorizza l’ID visitatore nei metadati del pagamento
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

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.

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.

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.

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.

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.

Gli esempi riportati di seguito usano POST /payments, che è deprecato. Funziona ancora per le integrazioni esistenti, ma per le nuove integrazioni è consigliato usare Checkout Sessions (POST /checkouts) — metadata viene passato nello stesso modo.

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_cart: [{ product_id: productId, quantity: 1 }],
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });

  return payment;
}

const express = require('express');
const router = express.Router();

router.post('/create-checkout', async (req, res) => {
  // Capture DataFast visitor ID from cookie
  const datafastVisitorId = req.cookies?.datafast_visitor_id;

  const payment = await dodopayments.payments.create({
    product_cart: [{ product_id: req.body.productId, quantity: 1 }],
    // ... other payment configuration
    metadata: {
      datafast_visitor_id: datafastVisitorId, // Store visitor ID in metadata
    },
  });

  res.json({ payment });
});

// Capture DataFast visitor ID from cookie
const datafastVisitorId = getCookie('datafast_visitor_id'); // Use your framework's cookie method

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

Passaggio 2: invia i dati di pagamento a DataFast

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

Open the Webhook Section

Nella dashboard di Dodo Payments, vai a Webhooks → + Add Endpoint ed espandi il menu a discesa delle integrazioni.

Select DataFast

Seleziona la scheda dell’integrazione DataFast.

Enter API Key

Inserisci la tua DataFast API Key nel campo di configurazione.

Configure Transformation

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

Test & Create

Esegui un test con payload di esempio e fai clic su Create per attivare l’integrazione.

Esempi di codice di trasformazione

Attribuzione di base dei pagamenti

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

Gestione delle valute senza decimali

Alcune valute, come JPY, non usano cifre decimali. Adatta 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 degli abbonamenti

Per i pagamenti ricorrenti degli abbonamenti, puoi monitorare 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;
}

Best practice

Acquisisci presto l’ID del visitatore: salva l’ID del visitatore di DataFast il prima possibile nel flusso di checkout per garantire un’attribuzione accurata, anche se l’utente abbandona il sito e torna in un secondo momento.

Includi sempre l’ID del visitatore nei metadati: senza l’ID del visitatore, DataFast non può attribuire i ricavi ai canali di marketing
Gestisci le valute senza decimali: alcune valute (JPY, KRW, ecc.) non usano cifre decimali; adatta di conseguenza il calcolo dell’importo
Esegui test con pagamenti di esempio: verifica che l’integrazione funzioni correttamente prima di passare alla produzione
Monitora la dashboard di DataFast: verifica che i pagamenti vengano visualizzati correttamente con la giusta attribuzione
Usa i retry dei webhook: la Payment API di DataFast è idempotente, quindi i retry sono sicuri in caso di errore di un webhook

Risoluzione dei problemi

Payments not appearing in DataFast

Verifica che la tua DataFast API key sia corretta e attiva
Controlla che datafast_visitor_id venga acquisito e memorizzato nei metadati del pagamento
Assicurati che la trasformazione del webhook formatti correttamente il payload
Verifica che il webhook venga attivato per gli eventi payment.succeeded
Controlla la dashboard di DataFast per eventuali messaggi di errore o log API

Revenue attribution not working

Conferma che lo script di tracking di DataFast sia installato e funzionante sul tuo sito web
Verifica che il cookie datafast_visitor_id venga impostato correttamente
Controlla che gli ID dei visitatori corrispondano tra la creazione del checkout e il completamento del pagamento
Assicurati di acquisire l’ID del visitatore prima di creare la checkout session
Consulta la documentazione della Payment API di DataFast per ulteriori indicazioni

Transformation errors

Convalida che la struttura JSON corrisponda al formato della Payment API di DataFast
Controlla che siano presenti tutti i campi obbligatori (amount, currency, transaction_id, datafast_visitor_id)
Assicurati che l’importo sia convertito correttamente (dividi per 100 per la maggior parte delle valute, ad eccezione delle valute senza decimali)
Verifica che l’URL dell’endpoint API sia corretto: https://datafa.st/api/v1/payments
Testa la trasformazione con payload webhook di esempio

Currency conversion issues

Per le valute senza decimali (JPY, KRW, CLP, VND, UGX, MGA), invia l’importo così com’è, senza dividerlo per 100
Per tutte le altre valute, dividi l’importo per 100 per convertirlo nell’unità di base
Ricontrolla che il codice valuta corrisponda al formato ISO 4217 (ad es. “USD”, “EUR”, “JPY”)

Risorse aggiuntive

DataFast Documentation

Scopri di più sulla Payment API di DataFast e sulle funzionalità di attribuzione dei ricavi.

DataFast Dashboard

Accedi alla dashboard di DataFast per visualizzare le analisi dei ricavi e i dati di attribuzione.

Hai bisogno di aiuto? Contatta l’assistenza di Dodo Payments all’indirizzo support@dodopayments.com per ricevere assistenza sull’integrazione.

External Integrations

Messaging

Workflow Automation

CRM

Email

Analytics

Introduzione

Come Funziona

Iniziare

Guida all’Implementazione

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

Passaggio 2: invia i dati di pagamento a DataFast

Esempi di codice di trasformazione

Attribuzione di base dei pagamenti

Gestione delle valute senza decimali

Pagamenti degli abbonamenti

Best practice

Risoluzione dei problemi

Risorse aggiuntive

DataFast Documentation

DataFast Dashboard

​Introduzione

​Come Funziona

​Iniziare

​Guida all’Implementazione

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

​Passaggio 2: invia i dati di pagamento a DataFast

​Esempi di codice di trasformazione

​Attribuzione di base dei pagamenti

​Gestione delle valute senza decimali

​Pagamenti degli abbonamenti

​Best practice

​Risoluzione dei problemi

​Risorse aggiuntive

DataFast Documentation

DataFast Dashboard

Introduzione

Come Funziona

Iniziare

Guida all’Implementazione

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

Passaggio 2: invia i dati di pagamento a DataFast

Esempi di codice di trasformazione

Attribuzione di base dei pagamenti

Gestione delle valute senza decimali

Pagamenti degli abbonamenti

Best practice

Risoluzione dei problemi

Risorse aggiuntive