Watch-IP

Peça a localização do visitante a partir de JavaScript no navegador

Este guia acrescenta uma chamada GET /v1/geo completa a uma página web: um estado de carregamento, um resultado bem-sucedido, e uma alternativa para quando o pedido falha ou um campo está em falta.

Antes de começar

  • Uma conta Watch-IP e uma chave de API de visitante publicável.
  • As origens permitidas da chave configuradas para incluir a página a partir da qual está a testar.
  • Uma página servida através de HTTP(S) — origens file:// não podem ser adicionadas a uma lista de permissões.

1. Chame o endpoint

Envie o pedido com a sua chave publicável no cabeçalho X-Api-Key. Uma vez que a chave foi concebida para ser publicável, é normal vê-la no separador de rede do navegador — o que limita a sua utilização é a origem na lista de permissões, não o sigilo.

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. Mostre um estado de carregamento e depois o resultado

Mantenha a sua interface predefinida visível até o pedido ser resolvido, e trate cada campo como possivelmente nulo. Country, city e timezone são os campos com que a maioria das integrações começa.

JavaScript

const statusEl = document.querySelector('#location-status');
statusEl.textContent = 'A detetar a sua região…';

try {
  const geo = await loadVisitorLocation();
  statusEl.textContent = geo.city && geo.country
    ? `A mostrar conteúdo para ${geo.city}, ${geo.country}`
    : 'A utilizar a região predefinida';
} catch {
  statusEl.textContent = 'A utilizar a região predefinida';
}

3. Preserve uma escolha explícita do visitante

Verifique se existe uma preferência armazenada antes de aplicar o país ou a moeda sugeridos, e só recorra ao resultado da API quando ainda não existir preferência.

JavaScript

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

Erros e casos limite

Uma origem não permitida falha na verificação CORS do navegador antes de o seu código ver uma resposta — isto normalmente surge como um erro de rede genérico, não como um corpo JSON legível, por isso verifique primeiro a configuração de origens permitidas quando um pedido falha silenciosamente. Um campo em falta não é um erro: trate um valor nulo de country, city ou timezone como "indisponível", não como um bug.

Próximo passo

Assim que o pedido básico funcionar, decida como a sua aplicação deve reagir ao resultado — consulte a página do produto de geolocalização de visitante para o padrão de localização, e a página de referência para todos os campos que a resposta pode conter.

Páginas relacionadas