Attribution

Attribution collega i tuoi dati di visibilità AI a lead e ricavi reali. Invece di vedere soltanto se il tuo brand compare nelle risposte AI, puoi vedere se i clienti dichiarano davvero di averti trovato tramite ChatGPT, Perplexity, Claude, Google, annunci, passaparola o altri canali — e quanto fatturato genera ciascun canale. L’attribution di Finseo lavora con due tipi di dati che vengono uniti automaticamente:

Risposte — la risposta di un cliente alla domanda “Come ci hai conosciuto?”, dal popup del sondaggio Finseo, dai tuoi moduli, da uno strumento di sondaggi o dal tuo CRM.
Conversioni — acquisti e lead con un ID transazione e un valore, dal tuo tracking esistente (Google/Meta), da Stripe, dal tuo sistema shop o da un webhook.

Quando una risposta e una conversione condividono lo stesso ID ordine o la stessa email, vengono unite in un unico dato attribuito: “questo ordine da 1.234 € è arrivato da ChatGPT.”

Configurazione guidata

Il modo più rapido per configurare l’attribution è il wizard integrato: apri Attribution nella dashboard e clicca su Set up attribution. Ti chiede cosa vuoi tracciare (acquisti, lead o entrambi), quale sistema utilizzi e se hai già un tracking o un sondaggio post-acquisto — poi consiglia esattamente un percorso di installazione con snippet da copiare e incollare e verifica in tempo reale che il primo evento arrivi. I percorsi consigliati, a seconda del tuo setup:

Finseo Snippet

Un solo tag script. Popup del sondaggio più cattura automatica degli acquisti dal tuo tracking Google/Meta esistente.

Stripe

Un solo evento webhook di Stripe. Importi, trial e rinnovi vengono classificati automaticamente.

Shopify

Un Custom Pixel che segnala ogni checkout completato — gli script del tema non possono girare sul checkout di Shopify, il pixel sì.

WooCommerce

Un webhook ordini nativo, inclusa l’origine della funzione Order Attribution integrata in WooCommerce.

Shopware

Un webhook Flow Builder sull’evento “Order placed”.

Webhook / CRM

HubSpot, Pipedrive, Calendly, strumenti per moduli o il tuo backend.

Lo snippet Finseo

Lo snippet è un singolo tag script servito per progetto:

<script src="https://app.finseo.ai/api/attribution/widget/YOUR_PROJECT_ID" async></script>

Incollalo prima di </head> su ogni pagina (oppure aggiungilo tramite Google Tag Manager come tag Custom HTML). Fa tre cose:

1. Cattura le risposte dai tuoi moduli esistenti

Se i tuoi moduli chiedono già “How did you hear about us?” (rilevato anche in tedesco: “Wie bist du auf uns aufmerksam geworden?”), lo snippet cattura la risposta al momento dell’invio — e il popup non viene mai mostrato. Email e nomi dello stesso modulo vengono allegati come chiavi di associazione, così la risposta può essere collegata in seguito a un deal o a un ordine. Se nessun modulo sulla pagina pone la domanda, lo snippet mostra un piccolo popup con la domanda e le opzioni di risposta che hai configurato. Controlli tutto in Attribution → Survey settings:

Domanda e canali — i canali predefiniti includono AI Search, Google/Bing, Social Media, Online Ads, Referral, Content e Other (con testo libero). Puoi anche usare canali AI dettagliati (ChatGPT, Perplexity, Claude, Gemini, Copilot).
Trigger — al caricamento della pagina, dopo l’invio di un modulo, dopo un acquisto rilevato oppure manuale via JavaScript.
Stile — colore d’accento, posizione, raggio degli angoli, font (di sistema o ereditato dal tuo sito) e mescolamento opzionale delle risposte per evitare il bias di posizione (“Other” resta sempre per ultimo).

A ogni visitatore la domanda viene posta una sola volta (memorizzato in localStorage).

3. Sfrutta il tuo tracking delle conversioni esistente

Se sono installati Google Analytics / Google Ads (dataLayer / gtag) o il Meta Pixel (fbq), lo snippet ascolta passivamente gli eventi di conversione e li segnala a Finseo — nessun setup di tracking duplicato:

Origine	Eventi catturati
`dataLayer` / `gtag`	`purchase` (inclusi i formati e-commerce di GA4 e Universal Analytics), `generate_lead`
Meta Pixel (`fbq`)	`Purchase`, `Lead`

Lo snippet legge ID transazione, valore, valuta e articoli dall’evento, deduplica per ID transazione (i ricaricamenti della thank-you page non vengono contati due volte) e analizza anche gli eventi scattati prima del suo caricamento. Il comportamento visibile ai visitatori non viene mai alterato.

API JavaScript

Per il controllo manuale, lo snippet espone una piccola API:

// Show the survey popup programmatically (e.g. after signup)
window.finseoAttribution.show();

// Report a conversion from your own code
window.finseoAttribution.trackConversion({
  transactionId: "ORDER-12345",
  value: 1234.56,
  currency: "EUR",
  email: "kunde@example.com" // optional merge key
});

Come vengono unite risposte e conversioni

Conversioni e risposte al sondaggio di solito arrivano separatamente — un cliente risponde al popup mentre naviga, e l’ordine arriva più tardi via Stripe o tramite il webhook del tuo shop. Finseo le unisce automaticamente:

Chiavi di associazione: ID transazione (respondentExternalId ↔ transactionId) oppure email. Una corrispondenza per ID transazione vince sempre su una corrispondenza per email.
Finestre temporali: una nuova conversione guarda indietro di 90 giorni in cerca di una risposta al sondaggio (i trial SaaS spesso convertono settimane dopo la registrazione). Una nuova risposta al sondaggio guarda indietro solo di 48 ore in cerca di una conversione non abbinata, così una risposta fresca non viene mai collegata a un ordine vecchio e non correlato.
Valori dei deal: se la risposta non ha un valore, l’importo della conversione unita lo compila — i ricavi non vengono mai contati due volte.
Tipi di conversione: i checkout Stripe con totale a 0 $ vengono salvati come trial, le fatture ricorrenti come rinnovi. Solo gli acquisti regolari contano come nuovi clienti in attesa di attribuzione.
Ricavi non attribuiti: le conversioni che non hanno mai ricevuto una risposta al sondaggio vengono mostrate come KPI a sé, così vedi sempre quanto fatturato resta ancora senza spiegazione.

Qualunque cosa invii la conversione (Stripe, Shopify Pixel, webhook), includi sempre l’email del cliente quando disponibile — è la chiave di associazione più affidabile per i lead che rispondono al sondaggio prima di acquistare.

Privacy by default

Le email dei clienti vengono hashate con SHA-256 all’ingestione. Finseo non memorizza mai indirizzi in chiaro — solo l’hash (usato per unire gli ordini alle risposte del sondaggio) e un’anteprima mascherata come j***@company.com per la dashboard.

Importa risposte dagli strumenti di sondaggio

Hai già un sondaggio post-acquisto? Tienilo — Finseo importa le sue risposte invece di mostrare un secondo popup:

Fairing

Via Shopify Flow

KnoCommerce

Via webhook nativo

Zigpoll

Via webhook nativo

SurveyMonkey

Via Zapier/Make

Typeform

Supporto nativo

Tally

Supporto nativo

Invia dati con un webhook

L’endpoint webhook del tuo progetto ha questa forma:

https://app.finseo.ai/api/attribution/webhook/PROJECT_ID?token=WEBHOOK_TOKEN

Puoi trovare o rigenerare il token webhook nelle impostazioni Attribution del progetto. Tratta l’URL come un segreto — il token autentica ogni richiesta. Invia richieste POST con Content-Type: application/json. Sono accettati anche invii form-encoded e multipart, per gli strumenti di moduli che non possono inviare JSON grezzo.

curl --request POST \
  --url "https://app.finseo.ai/api/attribution/webhook/PROJECT_ID?token=wh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "channelId": "AI Search",
    "respondentEmail": "kunde@example.com",
    "respondentName": "Max Mustermann",
    "respondentExternalId": "BESTELLUNG-12345",
    "dealValue": 1234.56,
    "dealCurrency": "EUR",
    "metadata": {
      "produkt": "Produkt XY",
      "sku": "ABC-123",
      "menge": 2
    }
  }'

Le risposte webhook riuscite hanno questo aspetto:

{
  "success": true,
  "id": "response-id",
  "source": "raw"
}

I payload di soli ordini diventano conversioni

Se un payload contiene dati d’ordine (ID transazione + importo) ma nessuna risposta di attribuzione — un evento Stripe, un ordine WooCommerce o un webhook ordini personalizzato — Finseo lo salva come conversione invece di rifiutarlo. La risposta ha allora questo aspetto:

{
  "success": true,
  "type": "conversion",
  "id": "conversion-id",
  "matched": true
}

matched: true significa che la conversione è stata immediatamente unita a una risposta al sondaggio precedente.

Riferimento dei campi

Campo	Obbligatorio	Descrizione
`channelId`	Sì	La fonte selezionata dal cliente, per esempio `AI Search`, `ChatGPT`, `Google`, `Referral` o `Paid Ads`.
`channelLabel`	No	Etichetta leggibile, se vuoi che sia diversa da `channelId`.
`channelCategory`	No	Categoria opzionale come `ai_search`, `organic_search`, `paid`, `social`, `referral`, `content`, `direct` o `other`.
`respondentEmail`	No	Email del cliente o del lead. Accettata anche come `email` nei webhook raw. Hashata all’ingestione.
`respondentName`	No	Nome del cliente o del lead. Accettato anche come `name` nei webhook raw.
`respondentExternalId`	No	ID dal tuo CRM, sistema ordini, checkout o data warehouse — la chiave di associazione più forte per le conversioni.
`dealValue`	No	Valore numerico di ricavo o pipeline.
`dealCurrency`	No	Codice valuta come `EUR`, `USD` o `GBP`. Invia la valuta effettivamente pagata.
`freetextResponse`	No	Risposta testuale originale se il cliente ha usato un campo a testo libero.
`formId`	No	Identificatore del modulo, del sondaggio o della fonte.
`pageUrl`	No	Pagina dove è avvenuto il modulo o il checkout.
`metadata`	No	Dati chiave-valore extra come prodotto, SKU, paese, piano o quantità.

Finseo normalizza il testo del canale in categorie. Per esempio, le risposte contenenti chatgpt, openai, claude, perplexity, gemini, copilot o ai search vengono categorizzate come ai_search.

Mappa i campi in ingresso

Molti strumenti inviano payload con nomi propri, come LeadSource, how_did_you_find_us, q3_howDid o risposte Typeform annidate. Finseo può mappare questi campi nei workflow di Attribution.

Apri Attribution.
Vai su Workflows.
Invia un webhook di test dal tuo sistema di origine.
Apri il workflow creato.
Mappa i campi in ingresso su attribuzione, email, nome, valore del deal, valuta, ID modulo o regole.
Salva la mappatura.

Dopo la mappatura, i webhook futuri con la stessa struttura vengono interpretati automaticamente. Quando un payload non può essere interpretato affatto, Finseo crea il workflow per te e suggerisce una mappatura dei campi tramite AI — devi solo confermarla.

{
  "attribution": "lead.source",
  "email": "lead.email",
  "name": "lead.full_name",
  "dealValue": "order.total",
  "dealCurrency": "order.currency",
  "formId": "form.id"
}

Puoi anche usare regole quando un campo di origine deve essere tradotto. Per esempio, se utm_source contiene chatgpt, mappalo su AI Search.

Formati di origine supportati

Finseo rileva automaticamente diverse origini comuni:

HubSpot: payload dei webhook contatto legacy con properties, oppure body JSON personalizzati da Operations Hub.
Typeform: form_response.answers, inclusi campi choice, choices, text ed email.
Tally: payload data.fields.
Salesforce: JSON da Flow HTTP Callout, per esempio LeadSource, Email, Name, Amount e CurrencyIsoCode.
Jotform: multipart/form-data con rawRequest o campi come q3_howDid, formID e submissionID.
Stripe: payload di eventi (checkout.session.completed, invoice.paid, …) — salvati come conversioni con conversione automatica dei centesimi e classificazione trial/rinnovo.
WooCommerce: webhook degli ordini, inclusi i meta di Order Attribution come origine marketing.
Shopware: payload ordini di Flow Builder con orderNumber, amountTotal ed email del cliente.
Raw JSON: payload diretti con campi come channelId, respondentEmail, dealValue e metadata.

Esempi

{
  "channelId": "ChatGPT",
  "respondentEmail": "jane@company.com",
  "respondentName": "Jane Smith",
  "respondentExternalId": "lead_98421",
  "dealValue": 12000,
  "dealCurrency": "EUR",
  "metadata": {
    "country": "DE",
    "plan": "Enterprise"
  }
}

{
  "channelId": "Perplexity",
  "respondentEmail": "kunde@example.com",
  "respondentExternalId": "ORDER-12345",
  "dealValue": 1234.56,
  "dealCurrency": "EUR",
  "metadata": {
    "produkt": "Produkt XY",
    "sku": "ABC-123",
    "menge": 2,
    "shop": "DE"
  }
}

{
  "LeadSource": "Claude",
  "Email": "buyer@example.com",
  "Name": "Alex Buyer",
  "Id": "00Qxx0000012345",
  "Amount": 8500,
  "CurrencyIsoCode": "USD"
}

Import batch giornaliero

Se preferisci un job giornaliero, invia fino a 1000 risposte in una volta con la bulk API.

curl --request POST \
  --url "https://api.finseo.ai/v1/projects/PROJECT_ID/attribution/bulk" \
  --header "Authorization: Bearer sk_live_xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "responses": [
      {
        "channelId": "AI Search",
        "respondentEmail": "kunde@example.com",
        "respondentExternalId": "BESTELLUNG-12345",
        "dealValue": 1234.56,
        "dealCurrency": "EUR"
      }
    ]
  }'

Consulta la Bulk Create Attributions API per il riferimento completo.

Ricevi eventi di attribuzione

Puoi configurare un URL webhook in uscita nelle impostazioni Attribution. Finseo invia un evento al tuo URL ogni volta che viene salvata una nuova risposta.

{
  "event": "attribution.response.created",
  "data": {
    "id": "response-id",
    "channel_id": "ai_chatgpt",
    "channel_label": "ChatGPT",
    "channel_category": "ai_search",
    "respondent_email": "kunde@example.com",
    "respondent_name": "Max Mustermann",
    "deal_value": 1234.56,
    "deal_currency": "EUR",
    "source": "webhook",
    "created_at": "2026-07-07T10:00:00Z"
  },
  "project_id": "PROJECT_ID",
  "timestamp": "2026-07-07T10:00:01Z"
}

Se aggiungi un secret per il webhook in uscita, Finseo firma il body JSON con un header X-FinSEO-Signature usando HMAC-SHA256.

Limiti di frequenza

Endpoint webhook: 120 richieste al minuto per progetto.
Endpoint collect dello snippet: 60 richieste al minuto per IP visitatore.

Le richieste oltre il limite ricevono 429 e possono essere ritentate senza problemi dopo un minuto.

Risoluzione dei problemi

Ogni richiesta webhook in ingresso viene registrata con il risultato del parsing in Attribution → Webhook logs — incluse le richieste rifiutate. Gli stati:

Stato	Significato
`stored`	Risposta di attribuzione salvata.
`stored_conversion`	Payload di soli dati d’ordine salvato come conversione.
`parse_failed`	Nessun campo di attribuzione o dato d’ordine riconosciuto — è stato creato un workflow per la mappatura manuale dei campi.
`invalid_token`	Il parametro query `token` manca o è errato — copia di nuovo l’URL dalla dashboard.
`error`	Body non valido o errore del server.

Best practice

Aggiungi la domanda di attribuzione vicino alla conversione, come registrazione, richiesta demo, checkout o qualificazione del lead.
Mantieni le opzioni di risposta stabili tra i vari paesi. Traduci le etichette per gli utenti se necessario, ma mantieni coerenti i valori dei webhook.
Invia in dealCurrency la valuta originale pagata; Finseo può comunque aggregare e mappare i valori.
Includi un respondentExternalId stabile come ID ordine, ID lead del CRM, ID contatto o ID deal.
Metti prodotto, SKU, mercato, campagna e altro contesto di business in metadata.
Invia un evento per ogni lead, ordine o deal. Evita di inviare ogni visualizzazione di pagina come attribuzione.

Panoramica

Per iniziare

Analytics

Attribution

Attribution

Configurazione guidata

Finseo Snippet

Stripe

Shopify

WooCommerce

Shopware

Webhook / CRM

Lo snippet Finseo

1. Cattura le risposte dai tuoi moduli esistenti

3. Sfrutta il tuo tracking delle conversioni esistente

API JavaScript

Come vengono unite risposte e conversioni

Privacy by default

Importa risposte dagli strumenti di sondaggio

Fairing

KnoCommerce

Zigpoll

SurveyMonkey

Typeform

Tally

Invia dati con un webhook

I payload di soli ordini diventano conversioni

Riferimento dei campi

Mappa i campi in ingresso

Formati di origine supportati

Esempi

Import batch giornaliero

Ricevi eventi di attribuzione

Limiti di frequenza

Risoluzione dei problemi

Best practice

​Attribution

​Configurazione guidata

Finseo Snippet

Stripe

Shopify

WooCommerce

Shopware

Webhook / CRM

​Lo snippet Finseo

​1. Cattura le risposte dai tuoi moduli esistenti

​2. Mostra il popup del sondaggio

​3. Sfrutta il tuo tracking delle conversioni esistente

​API JavaScript

​Come vengono unite risposte e conversioni

​Privacy by default

​Importa risposte dagli strumenti di sondaggio

Fairing

KnoCommerce

Zigpoll

SurveyMonkey

Typeform

Tally

​Invia dati con un webhook

​I payload di soli ordini diventano conversioni

​Riferimento dei campi

​Mappa i campi in ingresso

​Formati di origine supportati

​Esempi

​Import batch giornaliero

​Ricevi eventi di attribuzione

​Limiti di frequenza

​Risoluzione dei problemi

​Best practice

Attribution

Configurazione guidata

Lo snippet Finseo

1. Cattura le risposte dai tuoi moduli esistenti

2. Mostra il popup del sondaggio

3. Sfrutta il tuo tracking delle conversioni esistente

API JavaScript

Come vengono unite risposte e conversioni

Privacy by default

Importa risposte dagli strumenti di sondaggio

Invia dati con un webhook

I payload di soli ordini diventano conversioni

Riferimento dei campi

Mappa i campi in ingresso

Formati di origine supportati

Esempi

Import batch giornaliero

Ricevi eventi di attribuzione

Limiti di frequenza

Risoluzione dei problemi

Best practice