Configurare IndexNow: chiave, primo invio e lettura della risposta

IndexNow è un ping di una sola richiesta che avvisa i motori partecipanti che un URL è stato aggiunto, modificato o rimosso. La configurazione richiede tre cose: una chiave, quella chiave ospitata come file di testo sul tuo host e una richiesta HTTP per pubblicazione. Il percorso è gratuito, richiede circa venti minuti e funziona allo stesso modo su un sito statico e su un CMS.

Questo capitolo presuppone che la pagina sia già raggiungibile e già nella sitemap. Se non l’hai confermato, fallo prima di inviare qualcosa: un ping per un URL che restituisce 404 va sprecato. La routine di pubblicazione in tre passi della checklist di lancio prodotto copre quel terreno, e questo capitolo è la versione dettagliata del suo terzo passo.

Quali motori ascoltano davvero

IndexNow è un protocollo condiviso: una richiesta raggiunge tutti i partecipanti. L’elenco è pubblicato su indexnow.org ed è breve.

Bing paga per gli altri. Il suo indice alimenta la ricerca di ChatGPT e Copilot, quindi entrare presto in Bing è la via più breve al pool di fonti di una risposta IA. Google ha la sua strada, ed è per questo che il passo precedente te le fa fare entrambe.

Passo 1 — creare una chiave e ospitarla

La chiave dimostra al motore che l’invio viene da chi controlla l’host. È una stringa che inventi, con regole strette: da 8 a 128 caratteri, solo a-z, A-Z, 0-9 e trattini. Un UUID senza parentesi soddisfa tutto ed è facile da rigenerare.

KEY=$(uuidgen | tr 'A-Z' 'a-z' | tr -d '{}')
echo -n "$KEY" > public/$KEY.txt
echo "https://example.com/$KEY.txt"

Il file deve essere UTF-8, chiamarsi come la chiave e contenere la chiave e nient’altro. Pubblicalo, poi apri l’URL in un browser. Se non restituisce la chiave come testo semplice, fermati qui: tutti i passi successivi falliranno con un 403 che non spiega il motivo.

Puoi ospitare il file fuori dalla radice, ma la chiave copre solo gli URL sotto quella cartella. Una chiave in /catalog/key.txt può inviare /catalog/anything e non può inviare /help/anything. La radice evita tutta la questione.

Un punto che molti invertono: la chiave non è un segreto come un token API. Devi pubblicarla a un URL che chiunque possa leggere, perché quel file pubblico è la prova del controllo. Metterla nel repository non è un problema. Conta che il file e il valore inviato restino sincronizzati.

Passo 2 — inviare un URL a mano

Prima di automatizzare, dimostra il cablaggio con un solo GET. È la forma documentata per un URL alla volta.

curl -s -o /dev/null -w '%{http_code}\n' \
  "https://api.indexnow.org/indexnow?url=https://example.com/your-page&key=$KEY"

Un 200 significa che il file della chiave è stato trovato e letto. Non significa che la pagina verrà indicizzata. La documentazione del protocollo lo dice chiaramente: 200 indica solo che il motore ha ricevuto il tuo URL.

Passo 3 — passare all’endpoint in batch

Un URL per richiesta va bene per un test manuale e non va bene per una catena di pubblicazione. La forma in batch accetta fino a 10.000 URL in un solo POST, più di quanto la maggior parte dei siti userà mai in un invio.

POST /indexnow HTTP/1.1
Host: api.indexnow.org
Content-Type: application/json; charset=utf-8

{
  "host": "example.com",
  "key": "your-key",
  "keyLocation": "https://example.com/your-key.txt",
  "urlList": [
    "https://example.com/page-a",
    "https://example.com/page-b"
  ]
}

Il valore host deve corrispondere all’host di ogni URL dell’elenco. Mescolare due nomi host in un unico payload è la causa più frequente di un 422 su un batch che sembra corretto.

Leggere i codici di risposta

Cinque codici coprono tutto ciò che l’endpoint restituisce, e ognuno indica un errore diverso. Tieni questa tabella aperta mentre costruisci.

Il 403 è dove finisce quasi ogni primo tentativo, e ha due cause: il file non è dove hai detto, oppure c’è e la chiave dentro non corrisponde a quella inviata. Recupera il file con curl e confrontalo con il valore nello script prima di cambiare altro. Un 422 su un batch che funzionava come URL singolo punta al campo host, non alla chiave.

Il deliverable: un invio da inserire nella pubblicazione

Prendi questo script, cambia due righe ed eseguilo alla fine di ciò che pubblica i tuoi contenuti. Legge la sitemap, invia tutto in un batch e stampa il codice, così un errore è visibile invece che silenzioso.

#!/usr/bin/env bash
set -euo pipefail
HOST="example.com"
KEY="your-key"

URLS=$(curl -s "https://$HOST/sitemap.xml" \
  | grep -o '<loc>[^<]*</loc>' \
  | sed 's/<[^>]*>//g' \
  | python3 -c 'import json,sys; print(json.dumps([l.strip() for l in sys.stdin if l.strip()]))')

curl -s -o /dev/null -w 'indexnow: %{http_code}\n' \
  -X POST "https://api.indexnow.org/indexnow" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d "{\"host\":\"$HOST\",\"key\":\"$KEY\",\"keyLocation\":\"https://$HOST/$KEY.txt\",\"urlList\":$URLS}"

Due abitudini tengono in piedi tutto nel tempo. Registra cosa hai inviato e quando, così un invio ripetuto viene saltato invece che ripetuto. E invia quando cambia qualcosa, non secondo un calendario: un invio notturno di una sitemap invariata è ciò che guadagna un 429.

Tre modi per rovinare la configurazione

Tutti e tre restituiscono un codice visibile, ed è per questo che la tabella delle risposte è la prima cosa da controllare.

1. Il file della chiave viene servito con un Content-Type sbagliato o un ritorno a capo in più. Nel browser sembra ancora corretto. Recuperalo con curl e confrontalo byte per byte.
2. L’invio parte prima che il deploy finisca. Il motore arriva a un URL che l’host non ha ancora pubblicato e il ping viene speso su un 404.
3. Ogni build invia tutta la sitemap. All’inizio non si rompe nulla, poi gli invii restituiscono 429 e i ping utili si perdono nel rumore.

Cosa IndexNow non farà

Non farà indicizzare una pagina. Anticipa la scoperta; il motore continua a decidere se la pagina merita di restare, e una pagina debole scoperta prima resta una pagina debole. Non raggiunge Google, che non è nell’elenco dei partecipanti, quindi non sostituisce mai la parte Search Console della tua routine.

Non possiamo nemmeno dirti quanto tempo faccia risparmiare. Misurarlo bene richiede un gruppo di controllo di URL non inviati seguito per settimane, e non abbiamo ancora fatto quel test sui nostri siti. Chi ti cita un numero preciso di ore dovrebbe essere interrogato sul suo gruppo di controllo.

Quello che vale la pena controllare accanto a IndexNow è il resto della catena. Se la tua sitemap timbra ogni URL con l’ora della build, inviare con più forza non corregge il segnale; la nostra indagine sul lastmod nelle sitemap ha trovato 13 siti su 24 in quello stato. Il flusso di promozione del prodotto serve a controllare l’intera catena, non un solo endpoint. L’area sviluppatori di API e MCP mostra come collegare l’invio alla tua pubblicazione.

Domande frequenti

IndexNow funziona per Google?

Google non compare tra i partecipanti elencati su indexnow.org. Non abbiamo testato se Google legga questi invii per un’altra via, quindi non affermiamo né una cosa né l’altra.

Con che frequenza posso inviare?

Il protocollo non pubblica un limite orario, ma il 429 esiste proprio per l’eccesso di invii. Per i contenuti generati dagli utenti, l’indicazione ufficiale è ridurre in modo graduale: ogni elemento fino a 20, poi uno ogni cinque fino a 100, poi uno ogni dieci fino a 1.000.

Serve Bing Webmaster Tools?

Non per inviare. Serve per verificare: è lì che vedi se i tuoi URL sono stati ricevuti, ed è l’unica conferma gratuita del protocollo.

Si può cambiare la chiave dopo?

Sì. Ospita il nuovo file, cambia il valore nello script e mantieni il vecchio file per un po’. I motori rileggono il file della chiave a ogni invio, quindi non c’è una registrazione da rifare.