Watch-IP

Richiedere la posizione del visitatore dal JavaScript del browser

Questa guida aggiunge a una pagina web una chiamata completa a GET /v1/geo: uno stato di caricamento, un risultato riuscito e un fallback per quando la richiesta fallisce o un campo è mancante.

Prima di iniziare

  • Un account Watch-IP e una chiave API visitatore pubblicabile.
  • Le origini consentite della chiave configurate in modo da includere la pagina da cui stai testando.
  • Una pagina servita via HTTP(S) — le origini file:// non possono essere aggiunte a un elenco di origini consentite.

1. Chiama l'endpoint

Invia la richiesta con la tua chiave pubblicabile nell'header X-Api-Key. Poiché la chiave è pensata per essere pubblicabile, vederla nella scheda di rete del browser è normale — a limitarne l'uso è l'origine inclusa nell'elenco consentito, non la segretezza.

JavaScript

async function loadVisitorLocation() {
  const response = await fetch('https://api.watch-ip.com/v1/geo', {
    headers: { 'X-Api-Key': 'YOUR_PUBLISHABLE_KEY' },
  });

  if (!response.ok) {
    throw new Error(`Visitor geolocation failed (${response.status})`);
  }

  return response.json();
}

2. Mostra uno stato di caricamento, poi il risultato

Mantieni visibile la tua UI predefinita finché la richiesta non si risolve, e tratta ogni campo come potenzialmente null. Country, city e timezone sono i campi da cui partono la maggior parte delle integrazioni.

JavaScript

const statusEl = document.querySelector('#location-status');
statusEl.textContent = 'Rilevamento della tua regione…';

try {
  const geo = await loadVisitorLocation();
  statusEl.textContent = geo.city && geo.country
    ? `Contenuti mostrati per ${geo.city}, ${geo.country}`
    : 'Uso della regione predefinita';
} catch {
  statusEl.textContent = 'Uso della regione predefinita';
}

3. Rispetta una scelta esplicita del visitatore

Verifica se esiste una preferenza memorizzata prima di applicare il paese o la valuta suggeriti, e ricorri al risultato dell'API solo quando non esiste ancora alcuna preferenza.

JavaScript

const preferred = localStorage.getItem('preferredCountry');
const country = preferred ?? geo.country ?? 'US';

Errori e casi limite

Un'origine non consentita fallisce il controllo CORS del browser prima che il tuo codice veda una risposta — questo si manifesta tipicamente come un errore di rete generico, non come un corpo JSON leggibile, quindi controlla prima la configurazione delle origini consentite quando una richiesta fallisce silenziosamente. Un campo mancante non è un errore: tratta un valore null di country, city o timezone come 'non disponibile', non come un bug.

Passo successivo

Una volta che la richiesta di base funziona, decidi come la tua applicazione debba reagire al risultato — consulta la pagina prodotto della geolocalizzazione del visitatore per lo schema di localizzazione, e la pagina di riferimento per ogni campo che la risposta può contenere.

Pagine correlate