Integration PROMIUM GEO AI → PROMIUM

PROMIUM GEO AI – Documentazione Tecnica per Webmaster

Panoramica Tecnica

PROMIUM GEO AI è un plugin WordPress avanzato progettato per ottimizzare i contenuti web per i motori di ricerca basati su intelligenza artificiale attraverso tecniche di Generative Engine Optimization (GEO).

Caratteristiche Tecniche Principali:

Rilevamento Crawler AI: Identifica automaticamente oltre 20 crawler AI (GPTBot, ChatGPT-User, ClaudeBot, Perplexity, ecc.)
Sistema di Prompt Intelligente: Editor rich text per contenuti AI-specifici
Logging Avanzato: Sistema di debug condizionale con filtri per livello
Gestione Licenze: Sistema di validazione licenze integrato
Localizzazione: Supporto multilingua (IT/EN)
Metabox Personalizzati: Interfaccia per contenuti post-specifici

Requisiti di Sistema

WordPress: Versione 5.0 o superiore
PHP: Versione 7.2 o superiore
MySQL: Versione 5.6 o superiore
Memoria PHP: Minimo 128MB (raccomandati 256MB)
Permessi File: Scrittura nella directory wp-content/uploads

Installazione

1. Download e Upload

# Via FTP o File Manager
1. Scarica il file promium-ai-geo.zip
2. Estrai nella directory /wp-content/plugins/
3. Assicurati che la struttura sia: /wp-content/plugins/promium-ai-geo/

2. Attivazione Plugin

# Via WordPress Admin
1. Accedi a WordPress Admin → Plugin
2. Trova "PROMIUM AI GEO" nella lista
3. Clicca "Attiva"

3. Configurazione Iniziale

# Percorso: WordPress Admin → PROMIUM GEO → Impostazioni
1. Configura i crawler AI da rilevare
2. Imposta prompt globali (pre-prompt e post-prompt)
3. Configura sistema di logging (se necessario)
4. Salva le impostazioni

Configurazione Avanzata

Gestione Prompt

Prompt Globali: Contenuti che vengono aggiunti automaticamente a tutti i post

Pre-prompt: Contenuto inserito prima del contenuto principale
Post-prompt: Contenuto inserito dopo il contenuto principale

Prompt Specifici: Configurabili per singolo post tramite metabox

// Esempio di utilizzo programmatico
$post_id = 123;
$ai_content = get_post_meta($post_id, '_promium_ai_content', true);
$selected_crawlers = get_post_meta($post_id, '_promium_selected_crawlers', true);

Configurazione Crawler

Il plugin rileva automaticamente i seguenti user-agent e token di controllo. Elenco basato sul file di riferimento fornito.

Nome	User-Agent (pattern)	Categoria	Descrizione
AI2Bot	AI2Bot	ai_training	Crawler dell'Allen Institute for AI (Semantic Scholar).
Aleph Alpha Bot	AlephAlpha, AlephAlphaBot	ai_training	Raccoglie dati per l'addestramento dei modelli Aleph Alpha.
Applebot	Applebot	search_engine	Crawler per Siri e Suggerimenti Spotlight.
Applebot-Extended (Token)	Applebot-Extended	control_token	Token di controllo sull'uso dei contenuti per il training; non è un crawler.
Baiduspider	Baiduspider	search_engine	Crawler del motore di ricerca Baidu.
Bingbot	Bingbot, AdIdxBot	search_engine	Crawler di Microsoft Bing.
Bytespider	Bytespider	ai_training	Crawler di ByteDance per raccolta dati e motori interni.
ChatGPT-User	ChatGPT-User	ai_search	Fetcher on-demand attivato dagli utenti; non è un crawler autonomo.
ClaudeBot	ClaudeBot	ai_training	Raccolta dati pubblici per i modelli Claude.
Cohere-ai	cohere-ai	ai_training	Crawler di Cohere per l'addestramento dei LLM.
Common Crawl Bot	CCBot	data_provider	Dataset aperti del web ampiamente usati per il training.
Diffbot	Diffbot	ai_training	Estrazione dati strutturati e knowledge graph.
DuckAssistBot	DuckAssistBot	ai_search	Recupera contenuti per risposte istantanee; non usato per training.
DuckDuckBot	DuckDuckBot	search_engine	Crawler del motore di ricerca DuckDuckGo.
Facebook External Hit	facebookexternalhit	social	Genera anteprime link su piattaforme Meta.
Gemini / Google AI	Google-Extended, Google-Gemini, Gemini	ai_training	Servizi/agent legati a Gemini e Vertex AI (incluso token di controllo).
Google-Extended (Token)	Google-Extended	control_token	Esclude i contenuti dall'uso per il training di modelli Google; non è un crawler.
Googlebot	Googlebot	search_engine	Crawler principale di Google Search.
GPTBot	GPTBot	ai_training	Crawler di OpenAI per raccolta dati pubblici.
Hugging Face Bot	HuggingFace, HuggingFaceBot	data_provider	Scanner della piattaforma per dataset/modelli.
Internet Archive Bot	archive.org_bot	web_archiver	Archiviazioni Wayback Machine, utili anche alla ricerca.
Meta-ExternalAgent	Meta-ExternalAgent	ai_training	Raccolta dati a supporto dei modelli generativi di Meta.
PerplexityBot	PerplexityBot	ai_search	Indicizza il web per risposte aggiornate con citazioni.
YandexBot	YandexBot	search_engine	Crawler del motore di ricerca Yandex.
YouBot	YouBot	ai_search	Crawler del motore conversazionale You.com.

Sistema di Logging

Configurazione Debug:

// In wp-config.php per abilitare logging completo
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('PROMIUM_AI_GEO_DEBUG', true);

Livelli di Log:

ERROR: Errori critici del plugin
WARNING: Avvisi e problemi non critici
INFO: Informazioni generali
DEBUG: Informazioni dettagliate per sviluppatori

Gestione Licenze

Il plugin include un sistema di validazione licenze:

// Percorso: WordPress Admin → PROMIUM GEO → Licenza
1. Inserisci la chiave di licenza
2. Clicca "Attiva Licenza"
3. Verifica lo stato di attivazione

Importante: Una licenza valida è necessaria per ricevere aggiornamenti automatici e supporto tecnico.

Personalizzazioni Avanzate

Utilizzi Avanzati

Sistema di Hook e Filtri Enterprise

PROMIUM GEO AI offre un sistema completo di hook e filtri per integrazioni avanzate e personalizzazioni enterprise-level. Questa sezione fornisce esempi di codice dettagliati e scenari d'uso professionali.

Hook Principali Disponibili

1. Filtro Contenuto AI (promium_ai_geo_content)

Descrizione: Permette di modificare dinamicamente il contenuto mostrato ai crawler AI prima della visualizzazione.

Parametri: $content (string), $post_id (int), $crawler_type (string)

// Esempio: Personalizzazione contenuto per crawler AI
add_filter('promium_ai_geo_content', function($content, $post_id, $crawler_type) {
    // Personalizzazione basata sul tipo di crawler
    if (strpos($crawler_type, 'GPTBot') !== false) {
        $content = "[OTTIMIZZATO PER CHATGPT] " . $content;
    }
    elseif (strpos($crawler_type, 'PerplexityBot') !== false) {
        $content = "[FONTE VERIFICATA] " . $content;
    }
    
    return $content;
}, 10, 3);

2. Filtro Crawler Personalizzati (promium_ai_geo_crawlers)

Descrizione: Estende la lista dei crawler AI riconosciuti dal sistema.

Parametri: $crawlers (array)

// Esempio: Aggiunta crawler personalizzati
add_filter('promium_ai_geo_crawlers', function($crawlers) {
    $new_crawlers = array(
        'CustomBot' => array(
            'name' => 'Custom AI Bot',
            'user_agent_patterns' => array('CustomBot')
        )
    );
    
    return array_merge($crawlers, $new_crawlers);
});

3. Action Post-Rilevamento (promium_ai_geo_crawler_detected)

Descrizione: Eseguita dopo il rilevamento di un crawler AI, permette azioni personalizzate.

Parametri: $crawler_info (array), $post_id (int), $request_data (array)

// Esempio: Tracking visite crawler AI
add_action('promium_ai_geo_crawler_detected', function($crawler_info, $post_id, $request_data) {
    // Aggiorna contatore visite
    $current_count = get_post_meta($post_id, '_ai_crawler_visits', true) ?: 0;
    update_post_meta($post_id, '_ai_crawler_visits', $current_count + 1);
    
    // Log della visita
    error_log("PROMIUM GEO: Crawler  su post ");
}, 10, 3);

Integrazione Avanzata con Temi

1. Classe Helper per Temi

Descrizione: Classe utility per semplificare l'integrazione nei temi WordPress.

// Classe helper semplificata per integrazione tema
class PromiumGeoThemeHelper {
    private $detector;
    
    public function __construct() {
        if (class_exists('Promium_AI_GEO_Crawler_Detection')) {
            $this->detector = new Promium_AI_GEO_Crawler_Detection();
        }
    }
    
    public function isAICrawler() {
        return $this->detector ? $this->detector->is_ai_crawler() : false;
    }
    
    public function getAIContent($post_id = null) {
        if (!$post_id) $post_id = get_the_ID();
        if (!$this->isAICrawler()) return '';
        
        return get_post_meta($post_id, '_promium_ai_content', true);
    }
}

// Funzioni helper globali
function promium_is_ai_crawler() {
    static $helper = null;
    if (!$helper) $helper = new PromiumGeoThemeHelper();
    return $helper->isAICrawler();
}

function promium_get_ai_content($post_id = null) {
    static $helper = null;
    if (!$helper) $helper = new PromiumGeoThemeHelper();
    return $helper->getAIContent($post_id);
}

2. Implementazione nei Template

Descrizione: Esempi pratici di utilizzo nei file template del tema.

// Esempio: Modifica template single.php
// Nel loop principale, sostituire the_content() con:
if (promium_is_ai_crawler()) {
    $ai_content = promium_get_ai_content();
    if (!empty($ai_content)) {
        echo wp_kses_post($ai_content);
    } else {
        the_content();
    }
} else {
    the_content();
}

// Esempio: Widget statistiche AI semplificato
class PromiumAIStatsWidget extends WP_Widget {
    public function __construct() {
        parent::__construct('promium_ai_stats', 'PROMIUM AI Stats');
    }
    
    public function widget($args, $instance) {
        if (!is_single()) return;
        
        $post_id = get_the_ID();
        $visits = get_post_meta($post_id, '_ai_crawler_visits', true) ?: 0;
        
        echo $args['before_widget'];
        echo '

Visite AI: ' . $visits . '

'; echo $args['after_widget']; } } add_action('widgets_init', function() );

3. Scenari d'Uso Enterprise

A. E-commerce: Ottimizzazione Prodotti

add_filter('promium_ai_geo_content', function($content, $post_id) {
    if (get_post_type($post_id) !== 'product') return $content;
    
    $product = wc_get_product($post_id);
    if (!$product) return $content;
    
    $ai_content = $product->get_name() . "n";
    $ai_content .= "Prezzo: " . $product->get_price_html() . "n";
    $ai_content .= "Disponibilità: " . ($product->is_in_stock() ? 'Disponibile' : 'Non disponibile') . "n";
    $ai_content .= $product->get_description();
    
    return $ai_content;
}, 10, 2);

B. Blog: Ottimizzazione Articoli

add_filter('promium_ai_geo_content', function($content, $post_id) {
    if (get_post_type($post_id) !== 'post') return $content;
    
    $post = get_post($post_id);
    if (!$post) return $content;
    
    $ai_content = $post->post_title . "n";
    $ai_content .= "Data: " . get_the_date('d/m/Y', $post_id) . "n";
    $ai_content .= "Autore: " . get_the_author_meta('display_name', $post->post_author) . "n";
    $ai_content .= wp_strip_all_tags($post->post_content);
    
    return $ai_content;
}, 10, 2);

Limitazioni Provider di Hosting

Politiche Hosting e Accesso AI

IMPORTANTE: Alcuni provider di hosting possono limitare l'accesso dei crawler AI. Questa sezione fornisce informazioni per gestire queste limitazioni.

Tipologie di Blocchi Comuni

1. Blocchi Firewall

I firewall possono bloccare i crawler AI identificandoli come bot non autorizzati.
Sintomi: Errori 403/503, rilevamento corretto ma contenuto non mostrato.

2. Rate Limiting

Limitazioni sul numero di richieste per IP.
Sintomi: Errori 429, accesso intermittente dei crawler.

3. Blocchi User-Agent

Liste nere che includono specifici user agent dei crawler AI.
Sintomi: Alcuni crawler funzionano, altri no.

Come Verificare i Blocchi

Test con cURL

curl -H "User-Agent: GPTBot/1.0" -I https://tuosito.com/
curl -H "User-Agent: PerplexityBot/1.0" -I https://tuosito.com/

Analisi Log

grep -i "gptbot|perplexity" /var/log/access.log | grep -E "403|503"

Soluzioni

1. Contatto Provider

Contatta il supporto tecnico del provider di hosting per richiedere la whitelist dei crawler AI.
Template Email:

Oggetto: Richiesta Whitelist Crawler AI

Gentile Supporto,

Sto utilizzando PROMIUM GEO AI per ottimizzare il sito per i motori AI.
I crawler AI vengono bloccati dalle vostre politiche.

Potreste aggiungere alla whitelist:
- GPTBot
- PerplexityBot
- ClaudeBot

Grazie.

Cordiali saluti,
[NOME]
[DETTAGLI ACCOUNT HOSTING]

2. Configurazione .htaccess

# Whitelist crawler AI
SetEnvIf User-Agent "GPTBot" ai_crawler
SetEnvIf User-Agent "PerplexityBot" ai_crawler

3. Configurazione Cloudflare

Crea regola firewall per permettere crawler AI:

Campo: User Agent
Valore: GPTBot, PerplexityBot
Azione: Allow

Disclaimer

IMPORTANTE: PROMIUM GEO AI non è responsabile per blocchi implementati dai provider di hosting o servizi CDN.

In caso di problemi:

Verifica se il problema è legato al provider di hosting
Contatta il supporto del provider
Richiedi la whitelist dei crawler AI

Supporto e Assistenza

Per problemi di hosting:

Contatta il provider di hosting
Utilizza i template email forniti

Per problemi del plugin:

Verifica prima che non ci siano blocchi di hosting
Consulta la sezione Troubleshooting

Troubleshooting

Problemi Comuni

Plugin non si attiva: Verifica requisiti PHP e WordPress
Metabox non appare: Controlla permessi utente
Logging non funziona: Abilita WP_DEBUG
Licenza non valida: Verifica connessione e chiave licenza

Verifica Installazione

Vai su PROMIUM GEO → Dashboard
Controlla lo stato del sistema
Verifica i log se abilitati

Supporto Tecnico

Per assistenza:

Email: support@promiumai.com
Documentazione: https://promiumai.com/docs

Informazioni da fornire:

Versione WordPress e PHP
Versione del plugin
Descrizione del problema

Crawler coperti attualmente da PROMIUM GEO AI

Crawler	User-Agent	Brand	AI/Prodotto
AI2Bot	`AI2Bot`	allenai.org	semanticscholar.org
Aleph Alpha Bot	`AlephAlpha, AlephAlphaBot`	aleph-alpha.com	aleph-alpha.com
Applebot	`Applebot`	apple.com	apple.com
Applebot-Extended (Control Token)	`Applebot-Extended`	apple.com	apple.com
Baiduspider	`Baiduspider`	baidu.com	baidu.com
Bingbot	`Bingbot, AdIdxBot`	microsoft.com	bing.com
Bytespider	`Bytespider`	bytedance.com	bytedance.com
ChatGPT-User	`ChatGPT-User`	openai.com	chatgpt.com
ClaudeBot	`ClaudeBot`	anthropic.com	anthropic.com
Cohere-ai	`cohere-ai`	cohere.com	cohere.com
Common Crawl Bot	`CCBot`	commoncrawl.org	commoncrawl.org
Diffbot	`Diffbot`	diffbot.com	diffbot.com
DuckAssistBot	`DuckAssistBot`	duckduckgo.com	duckduckgo.com
DuckDuckBot	`DuckDuckBot`	duckduckgo.com	duckduckgo.com
Facebook External Hit	`facebookexternalhit`	meta.com	facebook.com