Kowal_Affiliate - istruzioni di installazione e configurazione

Questo documento descrive la modalità di installazione, attivazione e prima configurazione del modulo Kowal_Affiliate per Magento 2. La guida include sia i requisiti tecnici sia i passaggi pratici necessari per avviare un programma di affiliazione nello store.

1. Requisiti di sistema

Il modulo è destinato a:

• Magento Open Source / Adobe Commerce 2.4.7+
• PHP 8.2 o 8.3

Nel progetto Magento dovrebbero essere disponibili almeno i seguenti moduli:

• Magento_Store
• Magento_Cms
• Magento_Customer
• Magento_Email
• Magento_Quote
• Magento_Sales
• Magento_SalesRule
• Magento_Backend

2. Metodi di installazione

Il modulo può essere distribuito in modo standard come pacchetto Composer.

2.1. Installazione tramite Composer

Il modulo è distribuito come pacchetto Composer; un processo di esempio è il seguente:

Le credenziali di accesso al repository Composer, ovvero l’indirizzo e-mail del cliente e il token di licenza, saranno inviate via e-mail dopo l’acquisto. Sono disponibili anche nel pannello cliente dopo aver effettuato l’accesso su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l’indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer require kowal/module-affiliatebin/magento module:enable Kowal_Affiliatebin/magento setup:upgradebin/magento setup:di:compilebin/magento cache:flush

2.3. Modalità di produzione

Se lo store opera in production mode, dopo l’installazione è consigliabile eseguire anche:

bin/magento setup:static-content:deploy

3. Che cosa crea il modulo durante l’installazione

Durante l’installazione il modulo:

• crea le proprie tabelle di database relative all’affiliazione,
• estende quote e sales_order con campi di affiliazione,
• aggiunge attributi cliente utilizzati per la gestione dell’affiliato,
• crea una pagina CMS predefinita del programma partner,
• prepara la configurazione di sistema e i cron jobs,
• registra i template e-mail e le risorse del pannello di amministrazione.

3.1. Pagina CMS predefinita

Dopo l’installazione viene creata una pagina di esempio del programma partner:

identifier: affiliate-programtitle: Affiliate Partnership Program

La pagina ha un carattere universale e può essere utilizzata in produzione dopo una leggera personalizzazione dei contenuti.

La patch è idempotente:

• se una pagina con questo identifier esiste già, il modulo non la sovrascriverà.

4. Dove trovare la configurazione del modulo

Il pannello di configurazione si trova in:

Stores -> Configuration -> Affiliate Program

Le sezioni principali:

• General
• Commission
• Payouts
• Affiliate Portal
• Notifications
• Fraud
• AI
• Reporting

5. Prima configurazione dopo l’installazione

Dopo l’attivazione del modulo, si consiglia il seguente ordine di configurazione:

1. attiva il modulo a livello globale,
2. imposta la registrazione degli affiliati,
3. configura la commissione e il hold period,
4. imposta la soglia minima per i pagamenti,
5. completa i contenuti del portale affiliato,
6. configura le notifiche dell’amministratore,
7. configura opzionalmente l’AI,
8. esegui un test di registrazione, di clic affiliato e di ordine.

6. Configurazione dettagliata

6.1. General

Enable Module

Interruttore globale del modulo.

Se l’impostazione è disattivata:

• il tracking affiliato non dovrebbe funzionare,
• il modulo di registrazione non dovrebbe funzionare,
• le commissioni e i payout non saranno gestiti.

Raccomandazione:

• Yes nell’ambiente di produzione dopo il completamento dei test,
• No solo per il periodo di disattivazione del programma.

Enable Affiliate Registration

Attiva il modulo di candidatura al programma di affiliazione sul frontend dello store.

Se l’opzione è disattivata:

• i nuovi partner non potranno registrarsi autonomamente,
• l’amministratore potrà comunque contrassegnare manualmente un cliente come affiliato.

Tracking Cookie Lifetime (days)

Definisce la durata dell’attribuzione basata su cookie dopo il clic su un link affiliato.

Esempi:

• 30 per un programma di affiliazione standard,
• 7 per campagne brevi,
• 60 o 90 solo se il regolamento del programma lo prevede.

Default Redirect Path

Percorso di fallback utilizzato quando il tracking link non contiene un target valido.

Esempi:

• /
• promotions
• catalog/category/view/id/12

6.2. Commission

Enable Commissions

Attiva il calcolo delle commissioni per gli ordini affiliati.

Se il campo è disattivato:

• l’affiliazione può essere registrata,
• ma non verrà creata una voce nella tabella delle commissioni.

Default Commission Rate (%)

Aliquota percentuale predefinita della commissione.

Esempio:

• 10 indica una commissione del 10% sulla base di calcolo corrente.

Commission Hold Period (days)

Numero di giorni durante i quali la commissione rimane nello stato in attesa.

Trascorso questo periodo, il cron può approvare automaticamente la commissione.

Raccomandazione:

• 14 come valore predefinito sicuro,
• 0 solo per un programma molto semplice senza rischio di resi.

6.3. Payouts

Enable Payouts

Attiva il workflow dei pagamenti per gli affiliati.

Se l’opzione è disattivata:

• il partner non potrà presentare una richiesta di payout,
• l’amministratore potrà comunque analizzare le commissioni, ma non gestirà il pagamento nel modulo.

Minimum Payout Amount

Saldo minimo richiesto per richiedere un pagamento.

Esempi:

• 100
• 250
• 500

6.4. Affiliate Portal

Questa sezione controlla i contenuti visualizzati nella dashboard dell’affiliato.

Dashboard Intro

Breve descrizione nella parte superiore della dashboard dell’affiliato.

Dovrebbe spiegare al partner:

• dove trovare il link affiliato,
• dove visualizzare le commissioni,
• come funziona il pannello.

Program Rules

Regole di collaborazione visibili per l’affiliato.

È consigliabile inserire:

• una regola per riga,
• messaggi concisi e inequivocabili.

Banner Title

Titolo predefinito del materiale promozionale di esempio.

Banner Subtitle

Breve descrizione sotto il titolo del banner.

Banner Target Path

Percorso target predefinito per link affiliati e banner.

Esempi:

• /
• promotions/spring
• catalog/category/view/id/24

6.5. Notifications

Enable Notifications

Attiva il sistema interno di notifiche e la coda delle notifiche.

Admin Notification Email

Indirizzo e-mail dell’amministratore che deve ricevere i principali messaggi operativi.

Se il campo rimane vuoto:

• il modulo può usare l’indirizzo predefinito general di Magento come fallback in determinati flow.

Notification Log Retention (days)

Definisce per quanto tempo le voci nel log delle notifiche devono essere conservate prima del cleanup.

6.6. Fraud

Enable Fraud Checks

Attiva i controlli antifrode di base.

Block Self Referral

Blocca la commissione quando il cliente che effettua l’ordine è allo stesso tempo l’affiliato collegato a quell’ordine.

6.7. AI

La sezione AI è opzionale e non è richiesta per il funzionamento di base del programma di affiliazione.

Enable AI

Interruttore principale delle funzioni AI.

OpenAI API Key

Chiave API per la comunicazione con OpenAI.

Il campo è memorizzato nella configurazione cifrata.

AI Model Name

Modello utilizzato per le funzioni AI.

L’elenco dei modelli può essere recuperato da OpenAI dopo il corretto salvataggio della chiave API.

OpenAI Request Timeout (seconds)

Tempo massimo di attesa per la risposta da OpenAI.

Raccomandazione pratica:

• 60 secondi per un funzionamento più stabile in produzione.

Enable AI Diagnostic Logging

Attiva la registrazione diagnostica di request e risposte AI.

Utile per:

• integrazione,
• test,
• analisi di timeout ed errori di risposta.

AI Diagnostic Max Chars

Lunghezza massima della preview del payload registrato.

Enable Affiliate Assistant

Attiva l’assistente affiliato se lo store desidera utilizzare questa funzione.

Enable Weekly AI Reports

Consente di generare riepiloghi AI ricorrenti.

Enable Product Knowledge Retrieval

Consente di utilizzare la conoscenza prodotto da Vector Store.

Enable Program Knowledge Retrieval

Consente di utilizzare la conoscenza sul programma di affiliazione, le FAQ e la documentazione.

Product Vector Store Scope

Definisce come viene risolto product_vector_store_id.

Product Vector Store ID

Identificatore Vector Store se lo store utilizza il retrieval.

Redact Personal Data

Rimuove o maschera i dati personali prima di inviare il prompt al livello AI.

6.8. Reporting

Enable Reporting

Attiva la generazione di report ed esportazioni CSV.

Export Directory

Percorso della directory in cui devono essere salvate le esportazioni generate.

Esempio:

var/export/affiliate

7. Configurazione del cliente come affiliato

Dopo l’installazione, il modulo estende la modifica del cliente Magento con campi di affiliazione.

Nella modifica del cliente è possibile gestire, tra gli altri:

• Affiliate Participant
• Affiliate Status
• Affiliate Referral Code
• Affiliate Website URL
• Affiliate Notes
• Affiliate Balance
• Affiliate Coupon Discount (%)

7.1. Affiliate Participant

Indica se il cliente appartiene al programma di affiliazione.

7.2. Affiliate Status

Stati principali:

• Pending
• Active
• Suspended
• Rejected
• Blocked

7.3. Affiliate Balance

Il saldo viene calcolato automaticamente dalle commissioni approvate e pronte per il pagamento.

Il campo:

• è visibile nella modifica del cliente,
• non dovrebbe essere modificato manualmente,
• si aggiorna automaticamente dopo le modifiche alle commissioni.

7.4. Affiliate Coupon Discount (%)

Questo campo consente di assegnare all’affiliato una percentuale di sconto che sarà applicata al suo referral_code.

Se inserisci un valore maggiore di 0, il modulo:

• creerà o aggiornerà una regola carrello Magento,
• imposterà un coupon uguale al codice dell’affiliato,
• consentirà ai clienti di usare questo codice come coupon nel carrello,
• assegnerà l’ordine all’affiliato in base a coupon_code.

Esempio:

• l’affiliato ha il codice FMX1FBXXY3
• l’amministratore inserisce 5
• il cliente inserisce FMX1FBXXY3 come coupon sconto
• Magento calcola uno sconto del 5%
• il modulo assegna l’ordine all’affiliato.

8. Cron jobs del modulo

Il modulo utilizza cron nel gruppo default.

8.1. Auto approve commissions

job: kowal_affiliate_auto_approve_commissionsschedule: */15 * * * *

Il job:

• controlla le commissioni pending,
• dopo la scadenza del hold period le modifica in approved.

8.2. Process notifications

job: kowal_affiliate_process_notificationsschedule: */10 * * * *

Il job:

• elabora la coda delle notifiche,
• contrassegna le voci come inviate,
• nel caso del canale e-mail invia messaggi transazionali.

8.3. Cleanup notification log

job: kowal_affiliate_cleanup_notification_logschedule: 30 2 * * *

Il job:

• rimuove le vecchie voci dal log delle notifiche in base alla retention.

8.4. Weekly AI insights

job: kowal_affiliate_generate_weekly_ai_insightsschedule: 0 6 * * 1

Il job:

• genera insight AI settimanali, se la funzione è attiva.

9. Comandi CLI

Il modulo mette a disposizione comandi di servizio:

bin/magento kowal:affiliate:auto-approvebin/magento kowal:affiliate:process-notificationsbin/magento kowal:affiliate:cleanup-notificationsbin/magento kowal:affiliate:generate-ai-insightsbin/magento kowal:affiliate:export-report

I più utili al primo avvio sono:

bin/magento kowal:affiliate:process-notificationsbin/magento kowal:affiliate:auto-approve

10. Primo test dopo l’installazione

Dopo aver configurato il modulo, si consiglia un semplice test end-to-end.

10.1. Test di registrazione affiliato

1. Vai al modulo di registrazione affiliato.
2. Invia la candidatura.
3. Verifica che l’account affiliato sia stato creato.
4. Verifica che il cliente abbia lo stato Pending.
5. Verifica che siano state create voci di notifica.

10.2. Test di attivazione

1. Apri la modifica del cliente nel pannello admin.
2. Imposta lo stato dell’affiliato su Active oppure usa l’azione di approvazione.
3. Verifica che il cliente visualizzi la dashboard dell’affiliato.

10.3. Test del link affiliato

1. Copia il link affiliato dalla dashboard.
2. Accedi allo store tramite questo link.
3. Aggiungi un prodotto al carrello.
4. Effettua un ordine.
5. Verifica che l’ordine abbia:
   • affiliate_id
   • affiliate_referral_code
   • is_affiliate_order = 1

10.4. Test del coupon affiliato

1. Imposta per l’affiliato Affiliate Coupon Discount (%), ad es. 5.
2. Salva il cliente.
3. Assicurati che l’affiliato abbia lo stato Active.
4. Nel carrello inserisci il suo Referral Code come coupon.
5. Effettua un ordine.
6. Verifica:
   • che lo sconto sia stato applicato,
   • che l’ordine sia stato assegnato all’affiliato,
   • che sia stata creata una commissione.

10.5. Test dei payout

1. Approva la commissione oppure attendi l’auto-approve.
2. Verifica il saldo dell’affiliato.
3. Presenta una richiesta di pagamento.
4. Contrassegna il payout come pagato nel pannello admin.

11. Problemi più comuni dopo l’installazione

11.1. Nessuna commissione dopo l’ordine

Controlla:

• se l’ordine ha affiliate_id,
• se le commissioni sono attivate,
• se il modulo funziona dopo la correzione della creazione della commissione dopo il salvataggio dei dati di affiliazione sull’ordine,
• se nella tabella kowal_affiliate_commission compare un record.

11.2. La griglia clienti non mostra il saldo affiliato aggiornato

Controlla:

• se l’indice customer_grid è stato aggiornato,
• se dopo i salvataggi funziona reindexRow,
• se il valore nella modifica del cliente corrisponde al valore nella griglia.

Se necessario, esegui:

bin/magento indexer:reindex customer_grid

11.3. L’AI non risponde

Controlla:

• se Enable AI è attivo,
• se è stata salvata una OpenAI API Key corretta,
• se è stato selezionato un modello,
• se il timeout non è troppo basso,
• se var/log non mostra errori della request verso OpenAI.

11.4. Le notifiche non vengono inviate

Controlla:

• se i cron Magento funzionano,
• se Enable Notifications è attivo,
• se le voci vengono salvate in kowal_affiliate_notification_log,
• se è possibile avviare manualmente:

bin/magento kowal:affiliate:process-notifications

12. Configurazione iniziale consigliata

Per la prima implementazione in produzione, si consiglia il seguente set:

• Enable Module = Yes
• Enable Affiliate Registration = Yes
• Tracking Cookie Lifetime = 30
• Enable Commissions = Yes
• Default Commission Rate = 10
• Commission Hold Period = 14
• Enable Payouts = Yes
• Minimum Payout Amount = 100
• Enable Notifications = Yes
• Block Self Referral = Yes
• Enable AI = No all’inizio, se lo store non ha bisogno dell’AI fin dal primo giorno

13. Riepilogo

Dopo una corretta installazione e configurazione, Kowal_Affiliate consente di avviare in Magento 2 un programma partner completo che include:

• affiliati,
• link di referral,
• codici affiliato,
• coupon sconto degli affiliati,
• commissioni,
• payout,
• notifiche,
• dashboard del partner,
• sicurezza di base e automazione.