React에서 “API 키 없이” 인터랙티브 지도 넣기 (카카오 지도 퍼가기 RoughMap)

웹 페이지에 줌/이동 가능한 지도(인터랙티브 지도) 를 넣고 싶은데,
카카오 지도 JS SDK(키 발급) 방식이 부담스럽고  “간단히 지도만” 넣고 싶어서

카카오 RoughMap을 React에서 안정적으로 렌더하는 방법을 정리

---

1) 정식 API(JS SDK) vs 지도 퍼가기(RoughMap) 차이

✅ 정식 지도 API (JS SDK / REST API)

• 카카오 Developers에서 앱 생성 → JS 키 발급 필요
• 지도에 마커/오버레이/이벤트/좌표 검색/동적 제어 등 커스터마이징 가능
• 대신 초기 셋업(키/도메인 등록/CORS 등)이 필요하고 구현 난이도가 올라감

✅ 지도 퍼가기 (RoughMap / embed)

• 카카오맵에서 “공유/퍼가기”로 생성된 코드를 넣으면 끝
• 보통 키 발급 없이도 동작하는 케이스가 많음
• 장점: 구현이 매우 쉽고 빠름 (홍보/오시는 길 페이지에 최적)
• 한계: 지도 내부를 동적으로 제어(마커 추가/이벤트 바인딩 등)하기는 어렵다

 

결론: 오시는 길 같은 페이지는 RoughMap이 거의 정답이고,
서비스 기능으로 지도 제어가 필요하면 JS SDK로 가는 게 맞다.

 

 

---

 

2) 카카오 RoughMap 코드 얻는 법 (PC 기준)

1. 카카오맵 접속: map.kakao.com
2. 검색창에 주소/장소 검색
   예: 서울시 마포구 신촌로 176 그린대학교
3. 검색 결과에서 원하는 항목 클릭 → 상세 정보 열기
4. “공유” 아이콘(↗) 또는 “…” 메뉴 찾기
5. “지도 퍼가기 / 퍼가기 / HTML” 같은 항목 선택
6. 나오는 코드를 복사

 

이 값은 카카오맵 UI에서 생성되는 고유 값이라, “주소만”으로 바로 만들어주긴 어렵다.

---

 

3) RoughMap 퍼가기 코드 예시 (원본 형태)

<!-- 1. 지도 노드 -->
<div id="daumRoughmapContainer1766540249816" class="root_daum_roughmap root_daum_roughmap_landing"></div>

<!-- 2. 설치 스크립트 (페이지에 1회만) -->
<script charset="UTF-8" class="daum_roughmap_loader_script"
  src="https://ssl.daumcdn.net/dmaps/map_js_init/roughmapLoader.js"></script>

<!-- 3. 실행 스크립트 -->
<script charset="UTF-8">
  new daum.roughmap.Lander({
    "timestamp" : "1766540249816",
    "key" : "eet3ec4pfvt",
    "mapWidth" : "640",
    "mapHeight" : "360"
  }).render();
</script>

 

# 여기서 필요한 건 보통:

• timestamp
• key

 

---

4) React(Vite)에서 RoughMap을 “컴포넌트로” 렌더하기

• roughmapLoader.js는 내부적으로 document.write()를 쓰는 구간이 있어
  React에서 동적으로 script를 append하는 방식으로 로드하면 브라우저가 막아서 지도 렌더가 실패할 수 있다.
• 따라서 Vite의 index.html에 스크립트를 “정적으로 1회” 박아두는 게 가장 안전하다.

 

* index.html에 loader 스크립트 1회 추가 

/index.html (Vite 루트)에 아래를 추가

<!-- Kakao roughmap loader (지도 퍼가기): 반드시 정적으로 1회 삽입 -->
<script charset="UTF-8" src="https://ssl.daumcdn.net/dmaps/map_js_init/roughmapLoader.js"></script>

RoughMap을 여러 곳에서 쓰더라도 이 스크립트는 딱 1번만 넣는다.

 

 

KakaoRoughMap.jsx 컴포넌트

import React, { useEffect, useMemo } from 'react';

/**
 * Kakao Map "RoughMap(지도 퍼가기)" 렌더 컴포넌트
 * - loader 스크립트는 index.html에 1회 삽입해야 함
 * - 지도 위치가 바뀌면 timestamp / mapKey만 바꾸면 됨
 */
export default function KakaoRoughMap({ timestamp, mapKey, height = 360 }) {
  const containerId = useMemo(() => `daumRoughmapContainer${timestamp}`, [timestamp]);

  useEffect(() => {
    let canceled = false;
    let timer = null;

    const render = () => {
      if (canceled) return;

      const el = document.getElementById(containerId);
      if (!el) return;

      // loader 준비될 때까지 대기
      if (!window.daum?.roughmap?.Lander) {
        timer = setTimeout(render, 100);
        return;
      }

      // React StrictMode(개발) / 재렌더 대응: 항상 비우고 렌더
      el.innerHTML = '';

      new window.daum.roughmap.Lander({
        timestamp: String(timestamp),
        key: String(mapKey),
        mapWidth: '100%',
        mapHeight: String(height),
      }).render();
    };

    render();

    return () => {
      canceled = true;
      if (timer) clearTimeout(timer);
    };
  }, [containerId, timestamp, mapKey, height]);

  return <div id={containerId} className="root_daum_roughmap root_daum_roughmap_landing" />;
}

 

Direction.jsx에서 사용

import React from 'react';
import KakaoRoughMap from './KakaoRoughMap';

export default function Direction() {
  return (
    <div className="direction-page">
      <div className="direction-container">
        <div className="direction-card">
          <div className="direction-card-title">🗺️ 찾아오시는 길</div>

          <div className="kakao-roughmap-wrap">
            <KakaoRoughMap
              timestamp="1766540249816"
              mapKey="eet3ec4pfvt"
              height={360}
            />
          </div>
        </div>
      </div>
    </div>
  );
}

 

---

자주 터지는 문제 & 해결 

❌ 파일만 만들었는데 지도 안 뜨는오류

 

원인:
roughmapLoader.js를 React에서 동적으로 로드하거나, 컴포넌트 내부에서 script 태그를 넣으면
브라우저가 document.write()를 차단해서 로더가 정상 동작을 못하는 경우가 있다.

해결:
✅ index.html에 loader 스크립트를 정적으로 1회 삽입한다.

<!-- Kakao roughmap loader (퍼가기) : 반드시 정적으로 넣기 -->
<script charset="UTF-8" src="https://ssl.daumcdn.net/dmaps/map_js_init/roughmapLoader.js"></script>

 

⚠️ React StrictMode에서 “두 번 렌더”되는 현상

개발 모드에서 StrictMode가 effect를 2번 실행시키면서
지도 DOM이 꼬일 수 있다.

해결:
위 컴포넌트처럼 el.innerHTML = ''로 컨테이너를 비우고 다시 render하면 안정적이다.

 

 

⚠️ 페이지에 RoughMap을 2개 이상 넣고 싶다면?

• index.html의 loader 스크립트는 여전히 1번
• 각 지도마다 timestamp가 다르니, 컨테이너 id도 자동으로 달라져서 충돌이 줄어든다.

 

---

 

7) 이 방식의 특징 

✅ 장점

• 키 발급 없이도 구현 가능한 경우가 많음
• “오시는 길” 같은 페이지에 빠르고 안정적으로 적용 가능
• React에서도 컴포넌트화해서 재사용 가능

⚠️ 한계

• 지도 내부를 동적으로 제어(마커 추가/좌표 변경/클릭 이벤트 등)하기 어려움
• 그런 기능이 필요하면 정식 JS SDK로 전환해야 함

 

 

---

API 없이 지도 넣기 다른 선택지

 

✅ (A) 구글 지도 iframe embed

• Google 지도에서 공유 → 지도 퍼가기
• 보통 iframe만으로 끝, 설정이 쉬움
• 단, 서비스 정책/표시/추적 이슈는 케이스마다 점검 필요

✅ (B) 네이버 지도 퍼가기(가능한 경우)

• 케이스에 따라 퍼가기 제공이 제한될 수 있음
• 제공되는 형태가 iframe/링크 중심인 경우도 있음