위치 플랫폼인 Mapbox에 앱을 연결하여 Mapbox GL JS로 인터랙티브 지도를 임베드하고, 주소를 geocoding하고, 경로와 길안내를 계산합니다.

Mapbox에 앱 연결하기

위치 플랫폼인 Mapbox에 앱을 연결하여 Mapbox GL JS로 인터랙티브 지도를 임베드하고, 주소를 geocoding하고, Lovable 앱에서 경로와 길안내를 계산하세요.

Mapbox는 인터랙티브 지도, geocoding, routing을 위한 위치 플랫폼입니다. Mapbox 커넥터를 사용하면 Lovable 앱이 Mapbox GL JS로 브라우저에서 지도를 렌더링하고 Lovable 커넥터 게이트웨이를 통해 Mapbox 위치 API를 호출할 수 있습니다. Mapbox 지도 스타일과 Mapbox GL JS가 필요하거나 이미 위치 기능을 Mapbox에서 운영하는 앱에 적합합니다.

이 통합은 앱 + 채팅 커넥터로 제공됩니다. 하나의 공유 연결이 빌드 중 채팅과 게시된 앱 모두에서 작동합니다.

Mapbox를 사용하면 앱에서 다음과 같은 작업이 가능합니다.

Mapbox GL JS와 커스텀 Mapbox 스타일로 인터랙티브 지도 표시
주소를 좌표로 바꾸고 장소 검색
경로와 turn-by-turn 길안내 계산
여러 지점 사이의 이동 시간 영역과 거리 행렬 계산
미리보기와 썸네일을 위한 정적 지도 이미지 렌더링

Mapbox라는 이름을 직접 요청하거나 Mapbox에 특화된 기능이 필요할 때 적합합니다. 일반 지도, geocoding, 길안내가 필요한 빠른 프로토타입이라면 관리형 Google Maps Platform 연결은 계정이나 키가 필요 없습니다. 앱 하나에는 공급자 하나만 선택하세요. Google 약관은 geocoding, 장소, 경로 같은 Google Maps Platform 데이터를 Mapbox 지도처럼 Google이 아닌 지도에 표시하는 것을 허용하지 않습니다.

주요 활용 사례 및 예시 앱

다음 예시는 Mapbox로 만들 수 있는 앱과 시작 프롬프트를 보여줍니다.

예시 앱	프롬프트 예시	설명
매장 위치 찾기	Mapbox를 사용해서 클러스터링된 핀, 주소 검색, 가까운 위치를 나열하는 사이드바가 있는 매장 위치 찾기를 만들어줘.	방문자가 지도에서 가장 가까운 위치를 찾도록 돕습니다. 앱이 검색을 geocoding하고 Mapbox GL JS로 핀을 렌더링하며 지도 이동에 따라 목록을 갱신합니다.
배송 디스패치 보드	Mapbox를 사용해서 오늘의 정차 지점을 지도에 보여주고 픽업과 드롭오프 사이 경로 거리를 계산하며 ETA로 작업을 정렬하는 디스패치 보드를 만들어줘.	현장 운영을 위한 경로와 ETA를 계획합니다. 앱이 Mapbox routing을 서버 측에서 호출하고 인터랙티브 지도에 정차 지점과 경로를 렌더링합니다.
부동산 매물	Mapbox를 사용해서 사용자가 지도에서 집을 둘러보고 동네별로 필터링하며 각 핀에서 상세 페이지를 여는 매물 앱을 만들어줘.	지도 중심 경험으로 매물을 둘러봅니다. 앱이 검색 결과로 지도를 중심 정렬하고 매물 핀을 렌더링하며 각 핀을 상세 페이지에 연결합니다.
여행 일정 플래너	Mapbox를 사용해서 사용자가 정차 지점을 추가하고 지도에서 확인하며 각 구간의 운전 거리와 시간을 보는 여행 플래너를 만들어줘.	다중 정차 여행을 거리·시간과 함께 시각화합니다. 앱이 정차 지점을 geocoding하고 Mapbox 지도에 경로를 그리며 구간별 요약을 보여줍니다.
이벤트 장소 파인더	Mapbox를 사용해서 사용자가 도시로 검색하고 지도에서 장소를 보며 수용 인원이나 이벤트 유형으로 필터링하는 이벤트 파인더를 만들어줘.	지도 검색과 필터로 장소를 발견합니다. 앱이 장소 주소를 geocoding하고 핀으로 렌더링하며 지도와 목록을 함께 필터링합니다.
배송 구역 플래너	Mapbox를 사용해서 각 물류 거점에서 15분, 30분, 45분 안에 이동할 수 있는 범위를 보여주는 도구를 만들어줘.	위치 주변의 이동 시간 영역을 그립니다. 앱이 서버에서 Mapbox isochrone을 요청하고 도달 가능한 영역을 지도에 음영으로 표시합니다.
정적 지도 미리보기	Mapbox를 사용해서 저장된 각 위치의 썸네일 지도 이미지를 보여주는 admin 페이지를 만들어줘.	전체 인터랙티브 지도를 불러오지 않고 지도 미리보기를 생성합니다. 앱이 정적 지도 이미지를 서버 측에서 요청하여 목록이나 카드 뷰에 표시합니다.

Mapbox 연결 방법

누가 Mapbox 연결을 만들 수 있는지는 플랜과 워크스페이스 설정에 따라 달라집니다. 앱 + 채팅 커넥터는 Free, Pro, Business 플랜에서 기본 제공됩니다. Enterprise 플랜에서는 처음에 사실상 비활성화되어 있습니다. Admin이 Connectors → Admin settings → App + chat connectors에서 변경하기 전까지 연결 및 클라이언트를 만들 수 있는 사용자의 기본값이 No one이기 때문입니다.

다른 token을 사용하여 여러 Mapbox 연결을 만들 수 있습니다. 환경 분리(예: 개발과 프로덕션)나 다른 Mapbox 계정 사용에 유용합니다.

연결이 만들어지면 사용하려는 프로젝트에 연결을 링크할 수 있습니다. 프로젝트에서 빌드하는 사람은 누구나 채팅에서 Lovable에게 프로젝트를 이 연결에 링크해 달라고 요청할 수 있습니다.

사전 요구사항

Mapbox를 연결하기 전에 다음을 준비하세요.

Mapbox 계정
Mapbox access token 하나 이상: 브라우저 지도용 public token(pk.), 서버 측 API용 secret token(sk.), 또는 둘 다
Lovable 워크스페이스에서 연결을 만들 권한(연결 및 클라이언트를 만들 수 있는 사용자 참고)

모든 Mapbox API 사용량은 Mapbox 플랜에 포함되며 Lovable이 아닌 Mapbox에서 청구합니다.

1단계: Mapbox access token 발급

Mapbox는 두 가지 token 유형을 사용하며 서로 바꿔 쓸 수 없습니다. Public token(pk.)은 브라우저에서 지도를 불러옵니다. Secret token(sk.)은 서버에서 실행되는 모든 작업, 즉 geocoding, directions, matrix, isochrone, 정적 지도 이미지에 사용되며 모두 Lovable 커넥터 게이트웨이를 통해 호출됩니다. 지도만 쓰는 앱은 public token만으로 연결할 수 있습니다. 서버 측 기능에는 연결에 secret token이 필요합니다.

Mapbox access token을 만들려면 다음을 진행합니다.

Mapbox 계정 열기

Mapbox에 로그인합니다.

access token 열기

Access tokens로 이동합니다.

public token 가져오기

기본 public token(pk.으로 시작)을 복사하거나 새로 만듭니다. 게시하기 전에 token 설정에서 앱 URL로 제한하세요.

secret token 만들기(서버 측 기능이 필요한 경우)

Create a token을 클릭하고 설명적인 이름(예: Lovable integration)을 지정한 다음 앱에 필요한 스코프를 선택하고 sk.으로 시작하는 token을 복사합니다. Mapbox는 secret token을 한 번만 표시합니다.

token을 안전하게 보관

각 token을 복사하여 안전하게 보관합니다. 다음 단계에서 Lovable에 붙여 넣습니다.

secret token은 비밀번호처럼 작동합니다. 안전하게 보관하고 절대 공개적으로 공유하지 마세요. 다음 단계에서 token이 필요합니다.

자세한 내용은 Mapbox 문서를 참고하세요: Access tokens.

2단계: Mapbox를 Lovable에 연결

다른 token을 사용하여 여러 연결을 만들 수 있습니다.

Connectors에서 Mapbox 열기

Connectors를 열고 Mapbox를 선택합니다. 카탈로그를 여는 다른 위치는 커넥터를 찾을 수 있는 위치를 참고하세요.

연결 추가

Add connection을 클릭합니다.

연결 구성

Display name: 연결의 이름을 지정합니다(예: Mapbox Prod). 이 이름은 Lovable 내부에서 연결을 식별하는 데만 사용됩니다.
Secret token(선택): 앱에 geocoding, directions, 또는 다른 서버 측 Mapbox 기능이 필요하면 sk. token을 붙여 넣습니다.
Public token(선택): 앱이 브라우저에 Mapbox 지도를 표시하면 pk. token을 붙여 넣습니다. 이 필드는 값이 게시된 앱에 나타나기 때문에 Public으로 표시됩니다.

두 필드는 모두 선택 사항이지만 최소 하나는 필요합니다. 각 필드 옆의 Create token은 Mapbox access tokens 페이지를 엽니다.

이 연결을 사용할 수 있는 사람 선택

Sharing 아래에서 연결은 기본적으로 본인에게만 공개되며 Private 라벨이 표시됩니다. 공유하려면 Share with others를 클릭합니다. 그런 다음 이메일로 워크스페이스 멤버를 추가하거나 Invite entire workspace를 클릭해 Lovable 워크스페이스의 모든 사용자가 연결을 사용할 수 있게 합니다.

자세한 내용은 연결 및 클라이언트를 사용할 수 있는 사용자를 참고하세요.

연결

Connect를 클릭합니다. Lovable이 연결을 저장하기 전에 제공한 각 token을 Mapbox를 상대로 검증합니다.

연결되면 프로젝트에서 빌드하는 누구나 채팅에서 Lovable에게 프로젝트를 Mapbox에 연결해 달라고 요청할 수 있습니다(구성된 연결 수준 접근 권한에 따라). 그러면 Lovable 앱이 public token으로 Mapbox 지도를 표시하고 secret token으로 geocoding, routing, search를 수행할 수 있습니다.

Public token과 secret token

커넥터는 두 token을 서로 다른 작업에 사용합니다.

Secret token은 서버 측 Mapbox 호출에 사용됩니다. Lovable은 이 요청을 커넥터 게이트웨이를 통해 라우팅하고 token을 대신 추가하므로 token이 앱 코드나 브라우저에 나타나지 않습니다. 연결에 secret token이 없으면 서버 측 호출은 secret_token_required 오류로 실패합니다.
Public token은 브라우저의 Mapbox GL JS에서 사용됩니다. Lovable은 이 값을 앱 프런트엔드에 VITE_LOVABLE_CONNECTOR_MAPBOX_PUBLIC_TOKEN 환경 변수로 노출합니다. 다른 사이트가 이 token을 사용하지 못하도록 Mapbox 계정에서 앱 URL로 제한하세요.

public token만 연결하면 앱은 지도를 표시할 수 있지만 geocoding이나 routing은 수행할 수 없습니다. 해당 기능이 필요하면 연결에 secret token을 추가하세요.

제한 사항

Mapbox 커넥터는 다음을 할 수 없습니다.

token 자동 갱신. rotation하려면 Mapbox에서 새 token을 만들고 Lovable 연결을 업데이트하세요.
최종 사용자별 Mapbox 로그인 지원. 각 연결은 연결된 모든 프로젝트에서 공유되는 단일 Mapbox 계정을 나타냅니다.

Mapbox에서 token이 취소되거나 삭제되면 API 호출이 다시 성공하기 전에 유효한 token으로 Lovable 연결을 업데이트하세요.

Mapbox 연결 관리

연결은 Connectors에서 관리합니다. **Mapbox**을 선택한 다음 연결을 여세요.

Unlink projects를 사용하면 다른 프로젝트에서 연결을 계속 사용할 수 있도록 유지하면서 특정 프로젝트의 Mapbox 접근 권한만 제거할 수 있습니다. 단계별 절차는 연결에서 프로젝트 연결 해제를 참고하세요.
Delete the connection을 사용하면 워크스페이스에서 연결을 완전히 제거할 수 있습니다. 삭제는 영구적이며 연결된 모든 프로젝트에서 자격 증명이 제거되고, Mapbox을 사용하는 앱 기능은 새 연결을 추가할 때까지 작동하지 않습니다. 단계와 삭제 권한은 연결 삭제를 참고하세요.