Watch-IP

从浏览器 JavaScript 请求访问者位置

本指南将在网页中添加一个完整的 GET /v1/geo 调用:加载状态、成功结果,以及请求失败或字段缺失时的回退处理。

开始之前

  • 一个 Watch-IP 账户,以及一个公开可用的访问者 API 密钥。
  • 该密钥的允许来源已配置为包含您测试所用的页面。
  • 一个通过 HTTP(S) 提供服务的页面——file:// 来源无法被加入允许来源列表。

1. 调用端点

在 X-Api-Key 请求头中携带您的公开可用密钥发起请求。由于该密钥本就设计为可公开使用,在浏览器网络面板中看到它是预期行为——真正限制其使用的是配置的允许来源,而不是保密性。

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. 先渲染加载状态,再渲染结果

在请求完成之前,请保持默认 UI 可见,并将每个字段都视为可能为 null。country、city 与 timezone 是大多数集成最先用到的字段。

JavaScript

const statusEl = document.querySelector('#location-status');
statusEl.textContent = '正在检测您的地区…';

try {
  const geo = await loadVisitorLocation();
  statusEl.textContent = geo.city && geo.country
    ? `为 ${geo.city}、${geo.country} 显示内容`
    : '使用默认地区';
} catch {
  statusEl.textContent = '使用默认地区';
}

3. 保留访问者的明确选择

在应用建议的国家或货币之前,请先检查是否存在已保存的偏好设置,只有在尚不存在偏好设置时,才回退使用 API 的结果。

JavaScript

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

错误与边界情况

不被允许的来源会在您的代码看到响应之前就未能通过浏览器的 CORS 校验——这通常表现为一个通用的网络错误,而不是可读的 JSON 响应体,因此当请求静默失败时,请首先检查允许来源的配置。字段缺失并不是错误:请将 country、city 或 timezone 的 null 值视为“不可用”,而不是缺陷。

下一步

在基本请求可用之后,请决定您的应用应如何响应该结果——本地化模式请参阅访问者地理位置产品页面,响应可包含的每个字段请参阅参考页面。

相关页面