위치 플랫폼인 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를 사용하면 앱에서 다음과 같은 작업이 가능합니다.
- public token으로 Mapbox GL JS 인터랙티브 지도 임베드
- Geocoding API로 주소 geocoding과 장소 검색
- 경로와 turn-by-turn 길안내 계산
- 미리보기와 썸네일을 위한 정적 지도 이미지 렌더링
일반 지도, geocoding, 길안내가 필요한 빠른 프로토타입에는 Google Maps Platform이 설정이 더 빠를 수 있습니다.
주요 활용 사례 및 예시 앱
| 예시 앱 | 프롬프트 예시 | 설명 |
|---|---|---|
| 매장 위치 찾기 | Mapbox를 사용해서 클러스터링된 핀, 주소 검색, 가까운 위치를 나열하는 사이드바가 있는 매장 위치 찾기를 만들어줘. | 방문자가 지도에서 가장 가까운 위치를 찾도록 돕습니다. 앱이 검색을 geocoding하고 Mapbox GL JS로 핀을 렌더링하며 지도 이동에 따라 목록을 갱신합니다. |
| 배송 디스패치 보드 | Mapbox를 사용해서 오늘의 정차 지점을 지도에 보여주고 픽업과 드롭오프 사이 경로 거리를 계산하며 ETA로 작업을 정렬하는 디스패치 보드를 만들어줘. | 현장 운영을 위한 경로와 ETA를 계획합니다. 앱이 Mapbox routing을 서버 측에서 호출하고 인터랙티브 지도에 정차 지점과 경로를 렌더링합니다. |
| 부동산 매물 | Mapbox를 사용해서 사용자가 지도에서 집을 둘러보고 동네별로 필터링하며 각 핀에서 상세 페이지를 여는 매물 앱을 만들어줘. | 지도 중심 경험으로 매물을 둘러봅니다. 앱이 검색 결과로 지도를 중심 정렬하고 매물 핀을 렌더링하며 각 핀을 상세 페이지에 연결합니다. |
| 여행 일정 플래너 | Mapbox를 사용해서 사용자가 정차 지점을 추가하고 지도에서 확인하며 각 구간의 운전 거리와 시간을 보는 여행 플래너를 만들어줘. | 다중 정차 여행을 거리·시간과 함께 시각화합니다. 앱이 정차 지점을 geocoding하고 Mapbox 지도에 경로를 그리며 구간별 요약을 보여줍니다. |
| 이벤트 장소 파인더 | Mapbox를 사용해서 사용자가 도시로 검색하고 지도에서 장소를 보며 수용 인원이나 이벤트 유형으로 필터링하는 이벤트 파인더를 만들어줘. | 지도 검색과 필터로 장소를 발견합니다. 앱이 장소 주소를 geocoding하고 핀으로 렌더링하며 지도와 목록을 함께 필터링합니다. |
| 정적 지도 미리보기 | Mapbox를 사용해서 Static Images API로 저장된 각 위치의 썸네일 지도 이미지를 보여주는 admin 페이지를 만들어줘. | 전체 인터랙티브 지도를 불러오지 않고 지도 미리보기를 생성합니다. 앱이 정적 지도 이미지를 서버 측에서 요청하여 목록이나 카드 뷰에 표시합니다. |
Mapbox 연결 방법
누가 Mapbox 연결을 만들 수 있는지는 플랜과 워크스페이스 설정에 따라 달라집니다. 연결을 만들 수 있는 사람을 참고하세요.
다른 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.): 브라우저 전용. 프런트엔드의 Mapbox GL JS와 지도 타일에 사용합니다. - Secret token(
sk.): 백엔드 전용. geocoding, 길안내, 정적 이미지를 비롯해 Lovable 커넥터 게이트웨이로 호출하는 모든 서버 측 Mapbox API에 사용합니다.
연결할 때 token을 최소 하나 제공하세요. 지도만 사용하는 앱은 public token만으로 연결할 수 있습니다. 서버 측 Mapbox 기능은 연결에 secret token이 필요합니다.
Mapbox access token을 만들려면 다음을 진행합니다.
Mapbox 계정 열기
Mapbox에 로그인합니다.
access token 열기
Access tokens로 이동합니다.
token 만들기 또는 복사
앱이 필요로 하는 token을 만듭니다.
- Public token:
pk.으로 시작하는 기본 public token을 만들거나 복사합니다. 프로덕션으로 넘어갈 때 앱 도메인으로 제한하세요. - Secret token(geocoding, 길안내, 그 밖의 서버 측 API가 필요한 경우): Create a token을 클릭하고 설명이 담긴 이름(예:
Lovable integration)을 지정한 다음 앱이 필요로 하는 스코프를 선택하고sk.으로 시작하는 token을 복사합니다.
token을 안전하게 보관
각 token을 복사하여 안전하게 보관합니다. 다음 단계에서 Lovable에 붙여 넣습니다.
secret token은 비밀번호처럼 작동합니다. 안전하게 보관하고 프런트엔드 코드에 절대 임베드하지 말며 공개적으로 공유하지 마세요.
자세한 내용은 Mapbox 문서를 참고하세요: Access tokens.
2단계: Mapbox를 Lovable에 연결
다른 token을 사용하여 여러 연결을 만들 수 있습니다.
Connectors에서 Mapbox 열기
Connectors → App connectors로 이동한 다음 Mapbox를 선택합니다.
연결 추가
Add connection을 클릭합니다.
연결 구성
- Display name: 연결의 이름을 지정합니다(예:
Mapbox Prod). 이 이름은 Lovable 내부에서 연결을 식별하는 데만 사용됩니다. - Secret token(선택): 앱이 서버 측 geocoding, 길안내, 정적 이미지, 그 밖의 백엔드 Mapbox API가 필요하면 secret token(
sk.)을 붙여 넣습니다. - Public token(선택): 앱이 브라우저에서 Mapbox GL JS 지도를 렌더링하면 public token(
pk.)을 붙여 넣습니다. 이 값은 연결을 프로젝트에 연결한 후 게시된 앱에서 공개적으로 노출됩니다.
이 연결을 사용할 수 있는 사람 선택
Who can use this connection에서 워크스페이스의 누가 연결을 사용할 수 있는지 결정합니다. 처음에는 본인만 접근 권한을 가집니다.
- Only you(기본값): 접근 목록을 그대로 두면 본인만 연결과 관련 데이터를 사용할 수 있습니다.
- Invite specific people: 이메일로 워크스페이스 멤버를 추가하면 본인과 추가한 사람만 연결과 관련 데이터를 사용할 수 있습니다.
- Invite entire workspace: Invite entire workspace를 클릭하면 Lovable 워크스페이스의 모든 사람이 연결을 사용할 수 있습니다.
자세한 내용은 연결을 관리할 수 있는 사람을 참고하세요.
연결
Connect를 클릭합니다. Lovable이 연결을 저장하기 전에 제공한 각 token을 Mapbox를 상대로 검증합니다.
연결되면 프로젝트에서 빌드하는 누구나 채팅에서 Lovable에게 프로젝트를 Mapbox에 연결해 달라고 요청할 수 있습니다(구성된 연결 수준 접근에 따라). 그러면 Lovable 앱이 public token으로 Mapbox GL JS 지도를 렌더링하고 secret token으로 Lovable 커넥터 게이트웨이를 통해 서버 측 Mapbox API를 호출할 수 있습니다.
Public token과 secret token
커넥터는 역할이 다른 두 token을 받습니다.
- **Secret token(
sk.)**은 서버 측 Mapbox API 호출에 사용됩니다. Lovable이 이 요청을 커넥터 게이트웨이로 라우팅하고 연결을 프로젝트에 연결한 후 token을 백엔드에MAPBOX_API_KEY로 노출합니다. secret token을 프런트엔드 코드에 절대 사용하지 마세요. - **Public token(
pk.)**은 브라우저의 Mapbox GL JS에 사용됩니다. 연결을 연결한 후 Lovable이 이를VITE_LOVABLE_CONNECTOR_MAPBOX_PUBLIC_TOKEN으로 노출합니다. Mapbox 계정 대시보드에서 이 token을 앱 도메인으로 제한하세요.
연결을 만들 때 token을 최소 하나 제공해야 합니다. 브라우저 전용 지도 앱은 public token만으로 연결할 수 있습니다. Geocoding, 길안내, 그 밖의 백엔드 Mapbox 기능은 연결에 secret token이 필요합니다.
서버 측 호출은 Lovable 커넥터 게이트웨이를 거쳐야 합니다. 생성된 앱의 백엔드 코드에서 https://api.mapbox.com을 직접 호출하지 마세요.
제한 사항
Mapbox 커넥터는 다음을 할 수 없습니다.
- public token(
pk.)을 서버 측 Mapbox API 호출이나 커넥터 게이트웨이에 사용 - secret token(
sk.)을 프런트엔드 코드나 Mapbox GL JS에 사용 - public token의 도메인 제한을 대체. 프로덕션 도메인을 위해 Mapbox 계정 대시보드에서 허용 URL을 직접 구성해야 합니다
- 최종 사용자별 Mapbox 인증 지원. 각 연결은 연결된 모든 프로젝트에서 공유되는 단일 Mapbox 계정을 나타냅니다
- token 자동 갱신이나 rotation. rotation하려면 Mapbox에서 새 token을 만들고 Lovable 연결을 업데이트하세요
Mapbox에서 token이 취소되거나 삭제되면 API 호출이 다시 성공하기 전에 유효한 token으로 Lovable에서 통합을 다시 연결해야 합니다.
Mapbox 연결에서 프로젝트 연결 해제하는 방법
Editor 이상은 연결을 완전히 삭제하지 않고 특정 프로젝트를 연결에서 제거할 수 있습니다. 연결은 다른 프로젝트에서 계속 사용 가능합니다.
프로젝트 연결을 해제하려면 다음을 진행합니다.
Connectors 열기
Connectors를 열고 App connectors로 이동한 다음 **Mapbox**을 선택합니다.
연결 열기
관리하려는 연결을 엽니다.
프로젝트 선택
Linked projects에서 연결 해제하려는 프로젝트를 체크합니다.
확인
Unlink projects를 클릭하고 확인합니다.
연결이 해제되면 해당 프로젝트는 이 연결을 통해 더 이상 Mapbox에 접근할 수 없습니다. 프로젝트가 다시 Mapbox이 필요하면 사용 가능한 연결에 연결할 수 있습니다.
Mapbox 연결 삭제 방법
워크스페이스 admin과 owner는 Mapbox 연결을 삭제할 수 있습니다. 다른 멤버는 자신이 만든 연결이거나 명시적으로 접근 권한을 부여받은 경우 연결을 삭제할 수 있습니다.
연결 삭제는 영구적이며 취소할 수 없습니다. 연결된 모든 프로젝트에서 자격증명이 제거되며 이 연결을 사용하는 앱은 새 연결이 추가될 때까지 작동을 멈춥니다.
삭제하기 전에 Linked projects 섹션을 검토하여 현재 어떤 프로젝트가 연결을 사용하고 있는지 확인하세요.
연결을 삭제하려면 다음을 진행합니다.
Connectors 열기
Connectors를 열고 App connectors로 이동한 다음 **Mapbox**을 선택합니다.
연결 열기
제거할 연결을 엽니다.
연결된 프로젝트 검토
Linked projects 섹션을 검토합니다.
삭제
Delete this connection에서 Delete를 클릭하고 확인합니다.