Guida all'installazione, configurazione e utilizzo di Affiliate Tracker Pro
Prima di procedere all'installazione di Affiliate Tracker Pro, assicurati che il tuo ambiente soddisfi i seguenti requisiti minimi.
| Requisito | Versione Minima | Consigliata |
|---|---|---|
| PrestaShop | 1.7.0 | 8.x (ultima stabile) |
| PHP | 7.4 | 8.1 o superiore |
| MySQL / MariaDB | 5.7 / 10.2 | 8.0 / 10.6 |
| Accesso Back Office | Amministratore con permessi completi | |
| Cron Job (opzionale) | Necessario per report mensili automatici e recupero ordini | |
Note importanti:
ps_affiliate_tracker_.L'installazione del modulo richiede pochi minuti e non necessita di competenze tecniche avanzate. Segui questi passaggi:
Accedi al tuo account su affiliatetracker.it e scarica il file affiliatetracker.zip dalla sezione "I Miei Download". Il file contiene l'ultima versione stabile del modulo.
Entra nel back office del tuo negozio PrestaShop. Naviga su Moduli → Module Manager (su PrestaShop 8.x) oppure Moduli → Moduli e Servizi (su PrestaShop 1.7.x).
Clicca il pulsante "Carica un modulo" (o "Upload a module") in alto a destra. Trascina il file affiliatetracker.zip nell'area di caricamento oppure clicca per selezionarlo dal tuo computer.
Dopo il caricamento, il modulo apparira nella lista. Clicca "Installa". PrestaShop eseguira automaticamente lo script di installazione che:
affiliate_tracker_affiliates, affiliate_tracker_commissions, affiliate_tracker_customer_orders, ecc.)Al termine dell'installazione verrai reindirizzato alla pagina di configurazione. Inserisci la tua license key (vedi sezione 3 per i dettagli).
Il database viene creato automaticamente durante l'installazione. Verifica che nel menu di back office siano apparse le voci:
Installazione alternativa via FTP: Se preferisci, puoi estrarre il contenuto del file ZIP e caricare la cartella affiliatetracker nella directory /modules/ del tuo PrestaShop via FTP. Poi procedi all'installazione dal back office.
Affiliate Tracker Pro richiede una licenza valida per funzionare. La licenza viene verificata al momento dell'attivazione e periodicamente durante l'utilizzo.
La license key viene generata al momento dell'acquisto. Puoi trovarla:
Naviga su Moduli → Affiliate Tracker → Configura. Nella sezione "Licenza" in alto, troverai il campo per inserire la chiave.
La license key ha il seguente formato:
AT-XXXX-XXXX-XXXX-XXXX
Dove ogni X rappresenta un carattere alfanumerico. Inserisci la chiave esattamente come la trovi, inclusi i trattini.
Quando inserisci la license key e salvi la configurazione, il modulo:
| Errore | Causa | Soluzione |
|---|---|---|
License key non valida |
Chiave errata o scaduta | Verifica la chiave nel tuo account. Controlla che non ci siano spazi extra. |
Impossibile contattare il server |
Problema di rete o firewall | Verifica che il server possa effettuare connessioni HTTPS in uscita verso affiliatetracker.it. Controlla con il tuo hosting. |
Dominio non autorizzato |
La licenza e associata a un dominio diverso | Contatta il supporto per trasferire la licenza al nuovo dominio. |
Licenza scaduta |
L'abbonamento non e stato rinnovato | Rinnova l'abbonamento dal tuo account su affiliatetracker.it. |
Dopo l'attivazione della licenza, configura i parametri fondamentali del modulo. Accedi a Moduli → Affiliate Tracker → Configura.
Questo parametro definisce il nome del parametro GET utilizzato nei link di affiliazione.
| Impostazione | Dettaglio |
|---|---|
| Campo | Parametro URL Referral |
| Valore predefinito | referral |
| Esempio URL | https://tuosito.com?referral=CODICE_AFFILIATO |
| Quando cambiarlo | Se usi gia il parametro "referral" per altro, oppure preferisci un nome personalizzato (es: ref, aff, partner) |
Attenzione: Se modifichi questo parametro dopo aver gia distribuito link agli affiliati, i vecchi link non funzioneranno piu. Comunica la modifica a tutti gli affiliati attivi.
Definisce per quanti giorni il cookie di affiliazione resta attivo nel browser del visitatore.
| Impostazione | Dettaglio |
|---|---|
| Valore predefinito | 30 giorni |
| Range consigliato | 7 – 90 giorni |
| Significato | Se un visitatore clicca un link affiliato oggi e acquista entro il periodo configurato, la commissione viene attribuita all'affiliato |
| Quando aumentare | Per prodotti con ciclo di acquisto lungo (es: prodotti costosi, B2B) |
| Quando diminuire | Per prodotti ad acquisto impulsivo, o per limitare i costi di commissione |
Nota: La durata del cookie puo essere personalizzata per singolo affiliato (vedi sezione 6). Il valore impostato qui funge da default globale.
Quando abilitata, questa opzione invia una notifica email all'affiliato ogni volta che un ordine viene completato tramite il suo link di referral.
mails/it/affiliate_order_notification.htmlAbilita l'invio automatico di report riepilogativi mensili a ogni affiliato.
Questa opzione controlla se i clienti del negozio possono registrarsi automaticamente come affiliati.
Questa impostazione e indipendente dalla registrazione influencer, che ha un flusso separato con approvazione manuale.
La percentuale di commissione applicata di default a tutti i nuovi affiliati. Puo essere sovrascritta per singolo affiliato dalla pagina di modifica.
Definisce su quale importo viene calcolata la percentuale di commissione:
| Opzione | Descrizione |
|---|---|
| Solo prodotti (senza tasse) | Importo netto dei soli prodotti nell'ordine |
| Solo prodotti (con tasse) | Importo lordo dei soli prodotti |
| Totale ordine (senza tasse) | Totale inclusa la spedizione, al netto delle tasse |
| Totale ordine (con tasse) | Totale ordine incluse tasse e spedizione |
Il sistema COIN e un meccanismo alternativo (o complementare) alle commissioni monetarie. Invece di guadagnare euro, gli affiliati accumulano punti (COIN) che possono convertire in codici sconto per il tuo negozio. E particolarmente adatto per i programmi di affiliazione tra clienti.
Puoi personalizzare il nome visualizzato dai clienti. Esempi: "COIN", "Punti", "Crediti", "Stars". Questo nome apparira nella dashboard dell'affiliato e nelle email.
Definisce quanti COIN vengono assegnati per ogni euro di commissione generata.
| Parametro | Esempio | Significato |
|---|---|---|
| COIN per euro | 10 | Per ogni 1€ di commissione base, l'affiliato riceve 10 COIN |
Esempio pratico: Se la commissione e del 5% su un ordine di 100€, la commissione base sarebbe 5€. Con un rapporto di 10 COIN per euro, l'affiliato riceve 50 COIN.
Definisce quanti COIN sono necessari per ottenere 1€ di sconto.
| Parametro | Esempio | Significato |
|---|---|---|
| COIN per euro sconto | 100 | Servono 100 COIN per ottenere 1€ di sconto |
Esempio pratico: Con il rapporto sopra (10 COIN/€ guadagno, 100 COIN/€ sconto), il "tasso effettivo" e del 10%: per ogni 10€ di commissione generata, il cliente ottiene 1€ di sconto. Regolando questi due valori puoi controllare con precisione il valore del programma.
Il numero minimo di COIN che un affiliato deve accumulare prima di poter effettuare una conversione in codice sconto. Questo evita la generazione di codici sconto di valore irrisorio.
Consiglio: Imposta la soglia in modo che il codice sconto minimo abbia un valore significativo (es: almeno 5€). Con un rapporto di 100 COIN/€, una soglia di 500 COIN corrisponde a uno sconto minimo di 5€.
La sezione "Affiliati" nel back office ti permette di visualizzare, aggiungere, modificare e gestire tutti gli affiliati del tuo programma.
Ogni affiliato puo avere impostazioni diverse da quelle globali. I parametri sovrascrivono quelli predefiniti nella configurazione:
| Parametro | Descrizione | Default |
|---|---|---|
| Commissione (%) | Percentuale di commissione per questo affiliato | Valore globale |
| Base di calcolo | Su cosa calcolare la commissione (prodotti/totale, con/senza tasse) | Valore globale |
| Durata cookie | Giorni di validita del cookie per questo affiliato | Valore globale |
| Fixed Reward | Importo fisso in euro per ogni ordine (al posto della percentuale) | Non impostato |
| Min Reward | Commissione minima per ordine: se la percentuale genera un importo inferiore, viene usato questo valore | Non impostato |
| Max Reward | Commissione massima per ordine: se la percentuale genera un importo superiore, viene usato questo limite | Non impostato |
Per gestire grandi quantita di affiliati, puoi utilizzare le funzioni di import e export:
La lista affiliati puo essere filtrata per tipo:
Il sistema influencer e il cuore della modalita dual-track di Affiliate Tracker Pro. Permette a content creator e influencer di candidarsi al tuo programma di affiliazione attraverso un processo di registrazione e approvazione dedicato.
Gli influencer possono candidarsi al tuo programma attraverso un form dedicato, accessibile dalla pagina del tuo negozio.
Il form di candidatura raccoglie le seguenti informazioni:
| Stato | Descrizione | Azione Successiva |
|---|---|---|
| Pending | In attesa di revisione dell'amministratore | Approvare o Rifiutare |
| Approved | Candidatura approvata, affiliato attivo | L'influencer puo iniziare a promuovere |
| Rejected | Candidatura rifiutata con motivazione | L'influencer puo ripresentare la candidatura (se consentito) |
Naviga su Affiliate Tracker → Candidature Influencer. Vedrai la lista di tutte le candidature con il loro stato attuale. Le candidature "Pending" sono evidenziate per facilitare la revisione.
Per impostazione predefinita, un influencer rifiutato puo ripresentare la candidatura dopo un periodo configurabile. Questo e gestito tramite il parametro "Retry Days":
Configura questo parametro in Moduli → Affiliate Tracker → Configura → Impostazioni Influencer.
Una delle funzionalita piu potenti di Affiliate Tracker Pro e la possibilita di generare codici sconto personalizzati per gli influencer, che funzionano sia come strumento promozionale sia come meccanismo di tracking.
Il codice sconto viene creato come una CartRule nativa di PrestaShop. Questo significa che:
Quando un cliente utilizza il codice sconto di un influencer, la commissione viene attribuita all'influencer anche in assenza di cookie. Il tracking via codice e complementare al tracking via cookie.
Capire come funziona il tracking e fondamentale per sfruttare al meglio il modulo. Affiliate Tracker Pro utilizza un sistema a doppio canale: cookie tracking e codice sconto tracking.
Ecco il flusso completo, passo per passo:
https://tuosito.com?referral=MARIO123hookDisplayHeaderGli affiliati possono aggiungere il parametro referral a qualsiasi URL del tuo negozio:
https://tuosito.com?referral=CODICEhttps://tuosito.com/prodotto-123.html?referral=CODICEhttps://tuosito.com/categoria/scarpe?referral=CODICEIl parametro funziona su qualsiasi pagina del negozio. Il link puo essere condiviso tramite social media, email, blog, YouTube, newsletter o qualsiasi altro canale.
Quando un cliente inserisce un codice sconto associato a un influencer nel carrello:
Affiliate Tracker Pro supporta due modalita di attribuzione:
| Modalita | Descrizione | Caso d'uso |
|---|---|---|
| Solo primo ordine | La commissione viene generata solo per il primo ordine del cliente tracciato | Programmi di acquisizione clienti, per premiare chi porta nuovi clienti |
| Tutti gli ordini | La commissione viene generata per ogni ordine del cliente (finche il cookie e attivo) | Programmi di fidelizzazione, influencer con audience ricorrente |
La modalita viene configurata a livello globale in Configura → Modalita Tracking e puo essere sovrascritta per singolo affiliato.
La tab "Commissioni" e il centro operativo per la gestione finanziaria del programma di affiliazione.
Naviga su Affiliate Tracker → Commissioni. La lista mostra tutte le commissioni generate con le seguenti informazioni:
| Stato | Significato | Colore Badge |
|---|---|---|
| Pending | Commissione creata ma non ancora approvata. In attesa di revisione dell'amministratore. | Giallo/Arancione |
| Approved | Commissione approvata e confermata. L'affiliato ha diritto al pagamento. | Verde |
| Cancelled | Commissione annullata (ordine rimborsato, frode, ecc.) | Rosso |
Dalla lista commissioni:
In alcuni casi potresti aver bisogno di creare o modificare una commissione manualmente:
Per la contabilita e i pagamenti, puoi esportare le commissioni in formato CSV:
La sezione Statistiche offre una panoramica completa delle performance del tuo programma di affiliazione.
Naviga su Affiliate Tracker → Statistiche. La dashboard si apre con una vista riassuntiva del periodo selezionato.
| Metrica | Descrizione |
|---|---|
| Totale commissioni | Somma di tutte le commissioni nel periodo |
| Commissioni approvate | Importo delle sole commissioni con stato Approved |
| Commissioni pendenti | Importo delle commissioni in attesa di approvazione |
| Numero ordini tracciati | Quanti ordini sono stati attribuiti ad affiliati |
| Affiliati attivi | Numero di affiliati che hanno generato almeno una commissione nel periodo |
| Top affiliati | Classifica degli affiliati per volume di commissioni |
| Conversione media | Rapporto tra click sul link e ordini completati |
| Valore medio ordine | Importo medio degli ordini tracciati |
La funzionalita Link Referral permette di creare e monitorare link tracciati per campagne specifiche.
Per ogni link creato puoi visualizzare:
Affiliate Tracker Pro include due processi automatizzabili tramite cron job: i report mensili e il recupero ordini mancanti.
I report mensili inviano automaticamente un riepilogo a ogni affiliato con le commissioni del mese precedente.
Aggiungi il seguente comando al crontab del tuo server:
0 8 1 * * php /path/to/prestashop/modules/affiliatetracker/cron_monthly_reports.php TOKEN| Parte | Significato |
|---|---|
0 8 1 * * |
Esecuzione alle ore 8:00 del 1° di ogni mese |
php |
Interprete PHP (potrebbe essere php8.1 o /usr/bin/php a seconda del server) |
/path/to/prestashop/ |
Sostituisci con il percorso assoluto della tua installazione PrestaShop |
TOKEN |
Token di sicurezza per autorizzare l'esecuzione |
Il token di sicurezza e configurabile dalla pagina Configura → Impostazioni Cron. Puoi:
Attenzione: Se rigeneri il token, ricordati di aggiornare anche il comando cron sul server.
Il report mensile deve essere eseguito una volta al mese, idealmente:
Questo cron job scansiona gli ordini recenti e verifica che tutte le commissioni siano state create correttamente. E utile per recuperare commissioni che potrebbero essere sfuggite per problemi tecnici temporanei.
0 3 * * * php /path/to/prestashop/modules/affiliatetracker/cron_recover_missing_orders.php TOKEN| Parte | Significato |
|---|---|
0 3 * * * |
Esecuzione alle ore 3:00 ogni notte |
TOKEN |
Lo stesso token di sicurezza usato per i report mensili |
Per testare il processo senza creare effettivamente le commissioni, aggiungi il parametro --dry-run:
php /path/to/prestashop/modules/affiliatetracker/cron_recover_missing_orders.php TOKEN --dry-runIn modalita dry-run, il processo mostra quante commissioni verrebbero create senza effettivamente modificare il database. Utile per verificare che tutto funzioni correttamente prima di attivare il cron automatico.
Affiliate Tracker Pro invia diversi tipi di email. Tutti i template sono personalizzabili e si trovano nella cartella modules/affiliatetracker/mails/it/.
| # | Template | Quando viene inviata | Destinatario |
|---|---|---|---|
| 1 | affiliate_order_notification |
Quando un ordine viene completato tramite il link/codice di un affiliato | Affiliato |
| 2 | affiliate_monthly_report |
Il 1° del mese con il riepilogo commissioni del mese precedente | Affiliato |
| 3 | affiliate_influencer_order |
Quando un ordine viene effettuato con il codice sconto di un influencer | Influencer |
| 4 | affiliate_cancellation |
Quando una commissione viene cancellata dall'amministratore | Affiliato |
| 5 | Notifica nuova candidatura | Quando un influencer invia una candidatura | Amministratore |
| 6 | Approvazione candidatura | Quando l'amministratore approva una candidatura influencer | Influencer |
| 7 | Rifiuto candidatura | Quando l'amministratore rifiuta una candidatura influencer | Influencer |
/modules/affiliatetracker/mails/it/.html (versione grafica) e .txt (versione testuale)| Variabile | Descrizione | Disponibile in |
|---|---|---|
{firstname} |
Nome dell'affiliato | Tutte le email |
{lastname} |
Cognome dell'affiliato | Tutte le email |
{shop_name} |
Nome del negozio | Tutte le email |
{order_reference} |
Riferimento ordine | Notifiche ordine |
{commission_amount} |
Importo della commissione | Notifiche ordine, report mensile |
{order_total} |
Totale dell'ordine | Notifiche ordine |
{total_commissions} |
Totale commissioni del periodo | Report mensile |
{total_orders} |
Numero totale ordini del periodo | Report mensile |
{period} |
Periodo di riferimento del report | Report mensile |
{referral_code} |
Codice referral dell'affiliato | Approvazione candidatura |
{rejection_reason} |
Motivo del rifiuto | Rifiuto candidatura |
Affiliate Tracker Pro viene aggiornato regolarmente con nuove funzionalita, miglioramenti e correzioni di sicurezza.
ps_affiliate_tracker_*)/modules/affiliatetracker/Il modulo include script di upgrade automatici nella cartella /upgrade/. Quando installi una nuova versione, il sistema:
Ecco le soluzioni ai problemi piu comuni riscontrati dagli utenti di Affiliate Tracker Pro.
Sintomo: I visitatori cliccano il link affiliato ma la commissione non viene creata.
Verifiche da effettuare:
referral). L'URL deve essere nel formato ?referral=CODICE.displayHeader e actionValidateOrder.Sintomo: Il cookie e presente ma la commissione non appare nella lista.
Verifiche da effettuare:
/var/logs/) eventuali errori legati al modulo.Sintomo: Il form di registrazione influencer non e accessibile o restituisce un errore.
Verifiche da effettuare:
affiliateregistration.Sintomo: Gli ordini tracciati non generano COIN per l'affiliato.
Verifiche da effettuare:
Sintomo: Gli affiliati non ricevono le notifiche email (ordini, report, approvazione/rifiuto).
Verifiche da effettuare:
Sintomo: Un cliente usa il codice sconto di un influencer ma la commissione non viene attribuita.
Verifiche da effettuare:
Sintomo: L'installazione del modulo fallisce con un errore.
Verifiche da effettuare:
/modules/ deve essere scrivibile dal server web (permessi 755 per le cartelle, 644 per i file).phpinfo().upload_max_filesize e post_max_size nella configurazione PHP.ps_affiliate_tracker_*.Se non trovi la risposta al tuo problema in questa documentazione, contattaci:
Quando ci contatti, includi le seguenti informazioni per velocizzare la risoluzione: