Primi passi

Per iniziare

Benvenuto nella documentazione ufficiale di **Keoxs Co-Pilot**, un motore di intelligenza open-source e locale progettato per automatizzare, controllare e ottimizzare le tue campagne Amazon PPC. Keoxs offre un potere di diagnosi economica e di analisi IA cognitiva di livello aziendale direttamente sul tuo computer locale, garantendo la totale riservatezza dei dati e tempi di analisi rapidissimi.

💡

Privacy Assoluta (Local-First)

A differenza delle tradizionali piattaforme SaaS che richiedono l'integrazione completa del tuo account venditore e memorizzano i tuoi dati finanziari su server remoti, Keoxs funziona **interamente in locale sul tuo computer**. I tuoi report sui termini di ricerca (STR), COGS, strutture dei prezzi e chiavi API non lasciano mai la tua macchina.

Come funziona Keoxs Co-Pilot

Keoxs Co-Pilot si basa su un'**architettura a doppio motore** che unisce il rigore matematico alla sintesi qualitativa dell'IA:

1. Algoritmi Economici Unitari

Il motore di calcolo analizza i tuoi report sui termini di ricerca (STR) riga per riga, confrontando ogni metrica con i tuoi prezzi di vendita reali, COGS e tariffe FBA per identificare i target in perdita e calcolare offerte ottimali.

2. Cervello IA Cognitivo

Alimentato da Google Gemini, il cervello dell'IA supera i limiti dei rigidi filtri algoritmici per analizzare l'intento di ricerca, il potenziale organico e le opportunità di conquista della concorrenza, generando una roadmap strategica personalizzata.

Di cosa hai bisogno

Prima di installare Keoxs Co-Pilot, assicurati che il tuo computer soddisfi la seguente configurazione:

  • Node.js – Versione 18+ consigliata (v20+ completamente supportata) per eseguire l'interfaccia web frontend.
  • Python – Versione 3.10+ richiesta per avviare il server backend locale con FastAPI.
  • Chiave API Google AI Studio – Indispensabile per attivare il Cervello IA Cognitivo. Puoi ottenerla gratuitamente su Google AI Studio.
  • Git – Consigliato per recuperare facilmente gli aggiornamenti e gestire il repository locale.

Installazione Rapida

Forniamo uno script di installazione a riga singola che verifica i requisiti, clona il repository più recente, configura l'ambiente virtuale locale e avvia automaticamente entrambi i server.

Windows PowerShell (Consigliato) Automatico
powershell -ExecutionPolicy Bypass -Command "Invoke-Expression (New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/scalerify-keoxs/keoxs-website/main/install.ps1')"
Terminale macOS / Linux
curl -fsSL https://raw.githubusercontent.com/scalerify-keoxs/keoxs-website/main/install.sh | bash

Installazione Manuale per Sviluppatori

Se preferisci configurare manualmente il tuo spazio di lavoro o desideri contribuire al progetto open-source, segui questi passaggi.

1. Clonare il Repository

git clone https://github.com/scalerify-keoxs/keoxs-co-pilot.git
cd keoxs-co-pilot

2. Configurare il Backend FastAPI

cd backend
python -m venv venv
# Windows:
.\venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt
python -m uvicorn api:app --host 127.0.0.1 --port 8001 --reload

3. Configurare il Frontend React

cd ../frontend
npm install
npm run dev
Moduli principali

La Configurazione Iniziale

All'avvio, Keoxs ti guida attraverso un pannello di configurazione finanziaria estremamente completo. Inserisci i tuoi parametri:

  • Chiave API – Protegge la connessione con i modelli Gemini. Salvata esclusivamente nella memoria locale del browser.
  • Prezzo Medio & COGS – Consente all'algoritmo di calcolare il tuo ACOS di pareggio in tempo reale (`Margine Netto = (Prezzo Vendita - COGS - Tariffe FBA) / Prezzo Vendita`).
  • Soglia Spese Inutili (Wasted Spend) – Valore standard: 10 clic senza conversione. Determina quando un termine in perdita deve essere disattivato o subire una riduzione aggressiva dell'offerta.

Area di Caricamento (Drop Zone)

Trascina e rilascia il tuo file di **Report sui Termini di Ricerca** (Sponsored Products o Report Generali) in formato CSV o XLSX direttamente nell'area di caricamento.

Keoxs normalizza istantaneamente il file (indipendentemente dal paese di origine di Amazon), filtra i dati corrotti e mostra una dashboard esecutiva ordinata per urgenza economica:

🔴 Urgenze

Parole chiave che spendono budget con molti clic ma 0 vendite. Suggerisce l'esclusione immediata in Negativo Esatto.

🟠 Ottimizzazioni

Parole chiave con conversioni ma il cui ACOS supera il margine di profitto calcolato. Suggerisce riduzioni progressive dell'offerta.

🟢 Opportunità

Termini altamente redditizi, espressioni stagionali o target concorrenti ad alto potenziale. Suggerisce aumenti dell'offerta.

Cervello IA Cognitivo

Le regole di ottimizzazione matematica tradizionali spesso non riescono a identificare le micro-opportunità, come un target concorrente che converte sin dal primo clic o tendenze stagionali precoci.

La scheda **Cervello IA** supera questi limiti fornendo a Gemini un contesto commerciale estremamente ricco:

  • Flusso completo convertitori – L'IA analizza ogni ricerca che abbia generato almeno una vendita, catturando istantaneamente gli ASIN concorrenti (come `b0fmzkwkx9`) con un ottimo ROAS.
  • Iniezione della Cronologia – Memorizza automaticamente le ultime 5 analisi per garantire una coerenza di ottimizzazione a lungo termine ed evitare decisioni contraddittorie.
  • Diagnostica Conversione/Traffico – Sintetizza i tassi di conversione rispetto ai volumi di impression per indicarti se una campagna è limitata dal budget o dalle offerte.

Esporta Azioni in Blocco

Applica le tue ottimizzazioni sulla console Amazon Ads in pochi secondi. Cliccando su **Export Bulk Actions**, filtri la totalità delle righe per conservare solo le righe di azioni suggerite.

Il file CSV piatto utilizza un separatore di punto e virgola standard, leggibile immediatamente da Excel o Google Sheets, consentendoti di copiare e incollare le tue azioni in blocco direttamente nel gestore delle campagne di Amazon.

Buone pratiche

Consigli Pro & Strategia

📅 Seleziona il Periodo di Analisi Corretto

Quando scarichi i report, ti consigliamo di utilizzare un periodo di analisi degli **ultimi 30 giorni** (escludendo le ultime 48 ore per tenere conto del ritardo di attribuzione delle vendite di Amazon). Questo fornisce al motore un volume statistico robusto.

✍️ Ottimizza il Contesto del Prompt dell'IA

Fornisci pure al Cervello dell'IA indicazioni qualitative precise (ad esempio: *"Lanceremo un nuovo gusto la prossima settimana e dobbiamo essere aggressivi sulla conquista della concorrenza"* o *"Mancanza di stock sull'ASIN B fino a giugno, riduci il ritmo sulle campagne 3 e 4"*). L'IA adeguerà la sua roadmap di conseguenza.

⚖️ Equilibra il TACoS & i Margini Netti

Segui attentamente il tuo TACoS (Total Advertising Cost of Sales). Se le tue vendite organiche sono forti ma i tuoi margini netti soffrono, utilizza i suggerimenti di offerta di Keoxs per ridurre gradualmente la pressione pubblicitaria finché il tuo TACoS non torna al di sotto del 15% target.