브라우저 JavaScript에서 방문자 위치 요청하기

시작하기 전에

• Watch-IP 계정과 공개 가능한 방문자용 API 키.
• 테스트 중인 페이지가 키의 오리진 허용 목록에 포함되도록 설정.
• HTTP(S)로 제공되는 페이지 — file:// 오리진은 허용 목록에 추가할 수 없습니다.

1. 엔드포인트 호출하기

X-Api-Key 헤더에 공개 가능 키를 담아 요청을 보내세요. 이 키는 공개 가능하도록 설계되었으므로 브라우저의 네트워크 탭에 노출되는 것이 정상입니다 — 사용을 제한하는 것은 비밀성이 아니라 허용 목록에 등록된 오리진입니다.

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은 대부분의 통합이 가장 먼저 사용하는 필드입니다.

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. 방문자가 명시적으로 선택한 값 유지하기

제안된 country나 currency를 적용하기 전에 저장된 선호값이 있는지 먼저 확인하고, 선호값이 아직 없을 때만 API 결과로 대체하세요.

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

오류 및 예외 상황

허용되지 않은 오리진은 코드가 응답을 받기도 전에 브라우저의 CORS 검사에서 실패합니다 — 대개 읽을 수 있는 JSON 본문이 아니라 일반적인 네트워크 오류로 나타나므로, 요청이 조용히 실패한다면 먼저 오리진 허용 목록 설정을 확인하세요. 필드 누락은 오류가 아닙니다 — country, city, timezone 값이 null인 것은 버그가 아니라 '이용 불가'로 처리하세요.

다음 단계

기본 요청이 동작하면, 애플리케이션이 결과에 어떻게 반응할지 결정하세요 — 로컬라이제이션 패턴은 방문자 지오로케이션 제품 페이지를, 응답에 포함될 수 있는 모든 필드는 레퍼런스 페이지를 참고하세요.