38. 카카오맵 도메인 인증 + SPA에서 외부 SDK 쓰기¶

2026-05-15 우리집 CRM 예약 페이지(booking.medinterior.com) 카카오맵 임베드하며 시간 많이 끌었던 사건 정리. 핵심 두 가지 — 도메인 인증 + 동적 렌더링 페이지에서 SDK 로드.

한 줄 요약¶

401 Unauthorized = 카카오 서버가 "당신 도메인 등록 안 됨" 답. 도메인 등록은 카카오 디벨로퍼스의 "JavaScript SDK 도메인" 필드 (별도 위치). SPA(동적 렌더링) 페이지에서 카카오 SDK 쓸 땐 autoload=false 옵션 필수.

1. 외부 API 도메인 인증이 뭐야 (비유)¶

회사 출입 카드 같은 거. 카카오한테 "내 사이트가 이 도메인이야, 여기서 너희 SDK 쓸 거야"라고 미리 신청·등록해야, 그 도메인에서 호출 시 카카오 서버가 통과시켜.

등록 안 하면? 401 Unauthorized = "당신 등록 안 됨, 출입 거부".

비슷한 패턴 — 거의 모든 외부 API가 이런 도메인 인증 방식 씀: - 카카오 (지도·로그인·SDK 전반) - 네이버 (지도·로그인) - Google Maps - 페이스북·인스타그램 (Graph API)

각 서비스 콘솔에서 "내 사이트 도메인 등록" 항목 찾으면 됨.

2. 카카오 디벨로퍼스 — 헷갈리는 도메인 필드 3종¶

새 UI 기준. 이름이 비슷해서 자주 혼동.

필드	위치	용도
앱 대표 도메인	앱 → 일반 (앱 기본 정보)	비즈니스 정보 메타데이터. 검색·소개용. ❌ SDK 인증 X
JavaScript SDK 도메인	앱 → 플랫폼 키 → JS Key 클릭 후 상세 화면	✅ JS SDK 도메인 인증 (401 막는 거)
카카오 로그인 리다이렉트 URI	JS Key 상세 화면 같은 위치	카카오 로그인 OAuth 콜백 (SDK 무관)

핵심 함정: "앱 대표 도메인"이 등록돼 있어도 JS SDK는 401. 두 번째 필드("JavaScript SDK 도메인")에 별도 등록 필수.

등록하는 법 (새 UI)¶

카카오 디벨로퍼스 → 내 애플리케이션 → 해당 앱
좌측 메뉴 앱 → 플랫폼 키
Default JS Key 카드 클릭 (또는 점 3개 메뉴)
상세 화면에서 "JavaScript SDK 도메인" 입력란 (빨간 "도메인 입력 권장" 경고 떠 있음)
https://yoursite.com 입력 → + 버튼 → 저장

옛 UI ("플랫폼 → Web") 안내는 더 이상 통하지 않음¶

새 UI엔 좌측 "플랫폼" 메뉴 없음. "플랫폼 키"가 그 역할 통합한 메뉴.

3. SPA에서 외부 SDK — `document.write` 함정¶

문제 상황¶

카카오맵 SDK 코드(2026-05 기준)는 내부적으로 이렇게 동작:

if ("false" !== l.autoload) {
  document.write('<script src="kakao.js">...</script>');  // ← 이게 핵심
}

document.write는 페이지 파싱 중(DOM 만들고 있는 시점)에만 동작. 페이지 로드가 끝난 뒤 호출하면 무시되거나 페이지 전체를 덮어씀.

정적 vs 동적 페이지 차이¶

정적 페이지 (intro.medinterior.com 같은 일반 HTML): - script가 페이지 끝에 박힘 → DOM 파싱 중 실행 → document.write OK ✅ - 그래서 옵션 없이 그냥 <script src="...sdk.js?appkey=KEY"> 박으면 동작

SPA (booking.medinterior.com 같은 동적 렌더링): - 페이지 로드 후 JS가 화면 그림 → 그 시점에 SDK init 호출 → document.write 실패 ❌

비유¶

옛날 우편함 같은 거. 정적 페이지는 우편함이 열려 있을 때 (페이지 파싱 중) "지금 당장 종이에 쓱쓱 써서 박음"(document.write) 가능. SPA는 이미 우편함 닫힌 상태(페이지 로드 완료) → 박을 곳 없음.

해결 — `autoload=false`¶

<!-- 정적 페이지 (괜찮음) -->
<script src="//dapi.kakao.com/v2/maps/sdk.js?appkey=KEY"></script>

<!-- SPA (반드시 autoload=false) -->
<script src="//dapi.kakao.com/v2/maps/sdk.js?appkey=KEY&autoload=false"></script>
<script>
  // 화면 그린 후 명시적으로 호출
  kakao.maps.load(() => {
    const map = new kakao.maps.Map(/* ... */);
  });
</script>

autoload=false 박으면 SDK가 document.write 대신 appendChild(우편함 옆에 손으로 넣는 방식)로 추가 모듈 로드. 시점 무관 동작.

4. 비슷한 패턴 — 다른 외부 SDK도 의심¶

네이버 지도, 다음 지도 (둘 다 카카오 계열 다른 버전) — 같은 함정
구글 애즈, 페이스북 픽셀 등 추적 스크립트 — 일부는 document.write 사용
유튜브 iframe API — 동적 추가는 OK 패턴

전수 검사 팁: 외부 SDK가 SPA에서 안 뜨면, 그 SDK가 내부에서 document.write 쓰는지 의심. SDK 파일 직접 fetch해서 코드 검색하면 보임.

5. 진단 흐름 (다음에 401 만나면)¶

개발자 도구 Network 탭 → sdk.js 검색
상태가 (failed) net::ERR_FAILED 또는 401 이면 도메인 인증 실패
카카오 디벨로퍼스 → 앱 → 플랫폼 키 → JS Key 상세 들어가서 "JavaScript SDK 도메인" 필드 확인
정확한 도메인 등록 (https:// 포함, 경로 X)
새로고침

net::ERR_BLOCKED_BY_CLIENT이면 광고 차단기 차단 — 다른 문제.

6. 실전 사례¶

우리집 CRM 예약 페이지 (booking.medinterior.com): - 카카오 디벨로퍼스에 새 앱 "우리집 미팅 예약" 생성 - JS Key 5f0c0d1c4c2f82824c155a1409ca22a0 - JavaScript SDK 도메인: https://booking.medinterior.com - 코드: autoload=false 박고 kakao.maps.load() 호출

intro 사이트 (intro.medinterior.com): 정적 페이지라 autoload 옵션 없이 그냥 박음. 같은 코드 패턴 SPA에 그대로 적용하면 ❌.

7. 다음에 또 이런 상황 만나면¶

새 도메인에 카카오 기능 추가 → "JS Key 상세 → JavaScript SDK 도메인" 즉시 체크 (5분 안 걸려)
SPA에 외부 SDK 임베드 → autoload=false 옵션 또는 동적 추가 방식 가능한지 SDK 문서 확인
기록 안 보고 추측부터 시작하지 말 것 (이건 진짜 시간 낭비)

메모리 참조¶

~/.claude/projects/D--woorijipinterior/memory/kakao-map-sdk-domain-setup.md — 우리집 CRM용 빠른 참조
~/.claude/projects/D--woorijipinterior/memory/feedback-check-records-first.md — 같은 함정 반복 안 빠지는 행동 패턴