Perché un'app e non un plugin
Un plugin Shopware è PHP che gira dentro lo shop; un'app è un manifest che dice a Shopware quali URL chiamare. Per il tracking degli ordini l'app basta: Shopware invia webhook firmati per gli eventi a cui ti iscrivi, e nulla di Track viene eseguito nello shop. integrations/shopware/manifest.xml è quel manifest.
Registrazione
All'app:install Shopware chiama l'URL di registrazione dell'app con shop-id, shop-url e un timestamp, firmati nell'header shopware-app-signature con l'app secret del manifest. Il collector verifica la firma, risponde con una proof (HMAC-SHA256 su ID dello shop, URL dello shop e nome dell'app) e uno shop secret, e Shopware conferma inviando le credenziali API all'URL di conferma. Track scarta di proposito quelle credenziali: l'integrazione riceve soltanto webhook e non chiama mai l'API dello shop. Lo stesso segreto che hai salvato nella connessione funge da app secret e da shop secret, così ogni webhook successivo viene verificato con shopware-shop-signature, l'HMAC-SHA256 in esadecimale del body grezzo.
Quali eventi diventano cosa
| Evento Shopware | Evento Track |
|---|---|
state_enter.order_transaction.state.paid | purchase |
state_enter.order_transaction.state.refunded | refund (totale dell'ordine) |
checkout.order.placed | purchase solo quando la connessione è impostata per contare gli ordini effettuati |
Il comportamento predefinito conta la transazione pagata, non l'ordine effettuato. Negli shop con pagamento anticipato o su fattura un ordine può restare non pagato per giorni o non essere pagato mai; contarlo al momento dell'effettuazione gonfia il fatturato e insegna alle piattaforme pubblicitarie la cosa sbagliata. Gli shop in cui l'effettuazione è il momento significativo (pagamento alla consegna, fatturazione B2B) impostano la connessione su effettuato.
L'acquisto porta l'ID ordine, il numero d'ordine come ID transazione, gli importi totale e netto (l'imposta come differenza), la spedizione, la valuta, le righe prodotto identificate dal numero di prodotto e l'e-mail, il nome e la città, il CAP e il paese di fatturazione del cliente dell'ordine come dati di abbinamento grezzi che il router sottopone a hash. Le righe di promozione e di spedizione non sono prodotti e vengono saltate.
Valuta
Nelle versioni attuali di Shopware gli eventi paid e refunded portano l'ordine con la sua associazione alla valuta. Se una versione la omette, si applica la valuta di fallback della connessione; in mancanza di entrambe, l'evento viene memorizzato senza valuta e il monitor delle destinazioni segnala il campo mancante invece di tirare a indovinare.
Lo snippet nella Storefront
Aggiungi lo snippet standard al file base.html.twig del tuo tema, nel blocco base_head. Copre la Storefront e la pagina di conclusione del checkout, che Shopware renderizza da sé, così l'acquisto browser — con il record del consenso e i click ID del visitatore — esiste accanto al webhook. L'abbinamento per ID ordine permette poi all'acquisto server verificato di ereditare quel consenso; senza un acquisto browser il record server resta operativo e non raggiunge alcuna destinazione pubblicitaria.
Configurazione
- Sito → Connessione shop → Shopware 6: dominio dello shop, valuta di fallback, momento dell'acquisto; salva un segreto (32 caratteri casuali); copia l'URL di registrazione.
- Metti il manifest in
custom/apps/TrackSite/manifest.xml, sostituisci tracking ID, token del percorso e segreto, eseguibin/console app:install --activate TrackSite. - Contrassegna come pagata la transazione di un ordine di prova. La connessione segnala la registrazione e il primo webhook; il debugger mostra l'acquisto shopware.
Limiti
- Un secondo rimborso parziale sullo stesso ordine viene deduplicato per ID ordine; viene registrato il primo.
- Le app non possono iniettare script nella Storefront da sole; lo snippet è una modifica al tema, documentata nel README.
- Gli ordini modificati nell'admin dopo il pagamento non rinviano l'evento di pagamento; le correzioni di valore avvengono nel tuo reporting, non presso i fornitori.