리액트 프로젝트에서 카카오맵 API를 사용하면 사용자 친화적인 지도 기능을 쉽게 구현할 수 있어요. 네이버 지도와 함께 한국에서 가장 널리 사용되는 카카오맵은 다양한 기능과 직관적인 API 문서로 많은 개발자에게 선호돼요.
이 글에서는 리액트 프로젝트에 카카오맵을 통합하는 과정을 처음부터 끝까지 자세히 설명해드릴 거예요. HTML에 스크립트 태그로 로드하는 기본 방식부터 npm 패키지를 활용한 고급 방식까지 다양한 접근법을 살펴보겠습니다.
카카오맵 API 키 발급받기
카카오맵을 사용하려면 먼저 카카오 개발자 센터에서 API 키를 발급받아야 해요. 카카오 개발자 계정이 없다면 카카오 계정으로 로그인하거나 새로 가입하면 되는데, 이 과정은 매우 간단해요.
개발자 센터 등록
카카오 개발자 센터(https://developers.kakao.com)에 접속해서 계정을 생성한 후 로그인해요. 좌측 메뉴에서 “내 애플리케이션”을 클릭하고 “애플리케이션 추가하기” 버튼을 눌러요. 앱 이름과 사업명을 입력하고 약관에 동의한 후 생성하면 애플리케이션이 등록돼요.
REST API 키 확인
생성한 애플리케이션을 클릭하면 앱 키 목록이 나타나요. 여기서 “REST API 키”를 복사해서 보관해두세요. 이 키가 리액트 프로젝트에서 카카오맵을 초기화할 때 사용되는 중요한 인증 정보랍니다. 절대로 공개 저장소에 노출되지 않도록 환경 변수로 관리하는 것이 좋아요.
리액트 프로젝트에 카카오맵 로드하기
카카오맵을 리액트에서 사용하는 기본 방식은 HTML의 public/index.html 파일에 스크립트 태그를 추가하는 거예요. 이 방식이 가장 간단하고 안정적이라고 할 수 있어요.
HTML에 스크립트 추가
public 폴더의 index.html 파일의 head 태그 안에 다음 코드를 추가하면 되는데, 반드시 REST API 키를 여러분의 실제 키로 바꿔야 해요:
<script type=”text/javascript” src=”//dapi.kakao.com/v2/maps/sdk.js?appkey=YOUR_API_KEY”></script>
이렇게 하면 window.kakao 객체가 전역으로 사용 가능해져요. 리액트 컴포넌트에서 직접 접근할 수 있게 되는 거죠.
환경 변수 설정
.env 파일을 프로젝트 루트에 생성하고 API 키를 저장해요. REACT_APP_KAKAO_API_KEY=your_rest_api_key 형식으로 저장하면, process.env.REACT_APP_KAKAO_API_KEY로 접근할 수 있어요. 이렇게 하면 보안도 좋아지고 여러 환경에서 설정을 쉽게 바꿀 수 있어요.
기본 지도 컴포넌트 만들기
카카오맵을 표시할 기본 리액트 컴포넌트를 만들어봅시다. useEffect 훅을 사용해서 컴포넌트가 마운트될 때 지도를 초기화하는 방식이 일반적이에요.
KakaoMap 컴포넌트 구조
먼저 지도를 표시할 div 요소를 만들고, 이 요소의 크기를 CSS로 지정해야 해요. 지도 인스턴스는 반드시 정해진 크기의 컨테이너에 그려져야 하기 때문이에요. 그 다음 useEffect 내에서 window.kakao.maps.Map 객체를 생성하고 설정값을 전달하면 돼요.
const KakaoMap = () => { const mapContainer = useRef(null); const [map, setMap] = useState(null); useEffect(() => { if (!mapContainer.current) return; const mapOption = { center: new window.kakao.maps.LatLng(37.4979, 127.0276), level: 3 }; const newMap = new window.kakao.maps.Map(mapContainer.current, mapOption); setMap(newMap); }, []); return <div ref={mapContainer} style={{width: ‘100%’, height: ‘400px’}} />; };
지도 옵션 커스터마이징
mapOption 객체에서 여러 설정을 조정할 수 있어요. level은 줌 레벨로 1이 가장 근접하고 커질수록 멀어져요. center는 LatLng 객체로 표시할 중심 좌표를 지정해요. disableDoubleClick, draggable, scrollwheel 등의 옵션으로 사용자 상호작용을 제어할 수 있답니다.
마커 추가하고 관리하기
지도 위에 마커를 추가하는 것은 매우 일반적인 기능이에요. 사용자의 현재 위치나 관심 장소를 표시할 때 자주 사용됩니다.
단일 마커 추가
마커를 추가하려면 new window.kakao.maps.Marker() 객체를 생성한 후 setMap() 메서드로 지도에 올려요. 위치 정보와 함께 title, image 같은 추가 옵션을 지정할 수 있어요. 마커를 클릭할 때 인포윈도우를 표시하려면 마커의 onClick 이벤트 리스너를 등록하면 된답니다.
const marker = new window.kakao.maps.Marker({ position: new window.kakao.maps.LatLng(37.4979, 127.0276), title: ‘지점명’ }); marker.setMap(map);
여러 마커 관리
여러 마커를 추가할 때는 배열에 저장해서 관리하는 것이 좋아요. useState로 마커 배열을 유지하고, 필요할 때마다 마커를 추가하거나 제거할 수 있게 구성하세요. useRef를 사용해서 마커 배열을 참조로 유지하면 성능도 더 좋아진답니다.
인포윈도우로 상세 정보 표시
마커를 클릭했을 때 상세 정보를 보여주려면 인포윈도우를 사용해요. HTML 콘텐츠를 포함할 수 있어서 다양한 정보를 표현할 수 있어요.
인포윈도우 생성과 표시
const infowindow = new window.kakao.maps.InfoWindow({ content: ‘<div>장소명</div>’ }); infowindow.open(map, marker); 형식으로 사용하면 돼요. 인포윈도우의 content는 일반 텍스트뿐 아니라 HTML 형식의 문자열도 허용해요. 따라서 동적으로 HTML을 생성해서 다양한 형태의 정보를 표시할 수 있답니다.
인포윈도우 자동 닫기
여러 마커가 있을 때 이전 인포윈도우를 자동으로 닫고 새 마커의 인포윈도우만 보이도록 하려면, 마커 클릭 시 이전 인포윈도우의 setMap(null)을 호출하면 돼요. 이렇게 하면 사용자 경험이 더 나아진답니다.
실전 예제: 검색 결과 표시하기
실제 프로젝트에서는 외부 API로 받은 데이터를 바탕으로 마커를 표시하는 경우가 많아요. 검색 결과나 상품 목록 같은 데이터를 받아서 지도에 표시해보겠습니다.
동적 마커 생성
데이터 배열을 map()으로 순회하면서 각 항목에 대해 마커를 생성해요. useEffect 내에서 이 작업을 수행하고, 의존성 배열에 데이터를 포함시켜 데이터가 변경될 때마다 마커를 업데이트하게 하면 된답니다. 이전 마커들을 먼저 지도에서 제거한 후 새 마커를 추가하는 것이 중요해요.
성능 최적화
마커가 매우 많아지면 성능 저하가 발생할 수 있어요. 이런 경우 클러스터링 기능을 사용하거나, 현재 보이는 영역의 마커만 표시하는 방식을 고려해요. 카카오맵 라이브러리는 MarkerClusterer를 제공하는데, 이를 사용하면 가까운 마커들을 자동으로 그룹화할 수 있답니다.
자주 하는 실수와 해결책
카카오맵을 처음 사용할 때 자주 만나는 문제들을 정리했어요. 이런 것들을 미리 알면 개발 시간을 많이 절약할 수 있습니다.
window.kakao가 undefined입니다
이 오류는 보통 스크립트 태그가 제대로 로드되지 않았거나, 컴포넌트가 마운트되기 전에 kakao 객체에 접근하려고 했을 때 발생해요. index.html의 head에 스크립트 태그가 올바르게 있는지, API 키가 정확한지 확인하세요. 또한 useEffect에서 window.kakao의 존재 여부를 확인하고 진행하는 것이 안전해요.
지도가 보이지 않습니다
지도 컨테이너의 크기가 정해져 있지 않으면 지도가 나타나지 않아요. div 요소에 반드시 width와 height를 CSS로 지정해야 한답니다. 또한 display: none 상태로 초기화했다가 나중에 표시하려면 카카오맵의 relayout() 메서드를 호출해야 해요.
결론
카카오맵 API는 리액트와 함께 사용하기에 좋은 선택이에요. API 키 발급부터 기본 지도 구현, 마커 추가, 인포윈도우 표시까지 모든 단계를 거쳐봤습니다.
처음에는 단순히 지도만 표시하다가 점차 기능을 확장해나가면서 자신의 프로젝트에 맞는 지도 기능을 만들어보세요. 공식 문서와 예제 코드를 참고하면서 실험해보면 더 빨리 익숙해질 거예요. 화이팅!입니다.