ProtoPie에서 동적 지도 빌드하기: Google Places 및 Mapbox 연동 튜토리얼

설명: 이 튜토리얼에서는 ProtoPie 프로토타입 내에서 사용자 입력을 기반으로 동적으로 업데이트되는 정적 지도 이미지를 만드는 방법을 배웁니다. Google Maps Places API(New)를 통합하여 위치 좌표를 가져오고 Mapbox Static Images API를 사용하여 지도를 생성하며, 이 모든 과정은 ProtoPie Connect를 통해 원활하게 구성됩니다.

Creative Technologist인 Jubilee Mayanja가 ProtoPie로 전적으로 제작한 동적 지도 프로토타입 MapSearch입니다.

필요한 것:

• ProtoPie Studio(최신 버전 권장)

• ProtoPie Connect(최신 버전 권장)

• 프로젝트가 설정되고 결제가 활성화된 Google Cloud Platform 계정(무료 등급을 사용하더라도 API 액세스를 위해 결제 활성화가 필요한 경우가 많습니다).

• Mapbox 계정

• Google Maps Platform(특히 Places API) 및 Mapbox용 API 키

파트 1: API 키 설정하기

1.1 Google Maps Platform API 키 가져오기

1. Google Cloud Platform으로 이동: console.cloud.google.com에 접속합니다.

2. 프로젝트 생성(아직 없는 경우): 상단 바에서 프로젝트 드롭다운을 클릭하고 "새 프로젝트"를 선택한 후 안내를 따릅니다.

3. 결제 활성화: 무료 등급 사용 시에도 대부분의 Google Maps Platform API를 사용하려면 결제를 활성화해야 합니다. 왼쪽 탐색 메뉴에서 "결제"로 이동하여 결제 계정을 설정합니다.

4. API 및 서비스 활성화:

   • 왼쪽 탐색 메뉴에서 "API 및 서비스" > "사용 설정된 API 및 서비스"로 이동합니다.

   • "+ API 및 서비스 사용 설정"을 클릭합니다.

   • "Places API (New)"를 검색하고 활성화합니다.

   • 선택 사항(권장): "Geocoding API"도 검색하여 활성화합니다. Places API(New)는 일반적으로 좌표를 직접 제공하지만, 지오코딩은 특정 주소를 좌표로 변환해야 할 때 유용한 대체 수단이 됩니다.

   

5. API 사용자 인증 정보 생성:

• "API 및 서비스" > "사용자 인증 정보"로 이동합니다.

• "+ 사용자 인증 정보 만들기"를 클릭하고 "API 키"를 선택합니다.

• 생성된 키를 복사하여 안전한 곳에 보관하세요. 나중에 보안을 위해 제한할 수 있습니다. 지금은 복사만 해두세요.

  참고: API 키는 비밀로 유지하세요. 비밀번호와 동일하게 취급해야 합니다.

1.2 Mapbox 액세스 토큰 가져오기

1. Mapbox 계정으로 이동: account.mapbox.com에 접속합니다.

2. 퍼블릭 토큰 가져오기: 대시보드에 "Default public token"이 표시됩니다. 없는 경우 "Create a token"을 클릭하여 새 토큰을 생성합니다.

3. 토큰을 복사 — 이것이 여러분의 Mapbox 액세스 토큰입니다.

   

파트 2: ProtoPie 프로토타입 디자인하기

2.1 Figma 가져오기를 위한 ProtoPie Studio 준비

1. ProtoPie Studio를 열고 새 Pie 파일을 만듭니다.

2. 캔버스 크기를 Figma 프레임에 맞추기: 가져오기 전에 ProtoPie 캔버스 크기가 Figma에서 내보내는 프레임과 일치하는지 확인하세요. 이렇게 하면 가져오기 비율이 1:1로 유지되어 크기 조절 문제를 방지할 수 있습니다.

   

2.2 Figma에서 디자인 가져오기

1. Figma에서 디자인 준비하기: Figma 파일의 레이어가 단일 프레임으로 구성되어 있는지 확인하세요. 이 단계를 건너뛰려면 제공된 Figma 파일에서 시작해도 됩니다.

2. Figma에서 내보내기:

   • 하단 툴바에서 "Actions" 아이콘을 클릭합니다.

   • "Plugins and Widgets" 탭을 선택합니다.

   • "ProtoPie"를 검색하고 플러그인을 클릭합니다.

   • 플러그인 창에서 "Export"를 선택합니다. 디자인이 열려 있는 ProtoPie Studio 파일로 직접 가져와집니다.

     

2.3 기본 UI 설정

Figma에서 가져왔든 ProtoPie Studio에서 직접 UI를 빌드했든 관계없이 다음과 같이 레이어가 설정되어 있는지 확인하세요.

1. 입력 레이어 만들기:

   • "Text Input" 레이어를 추가하고 이름을 locationInput으로 지정합니다. 사용자는 여기에 검색하려는 위치를 입력합니다.

   • 선택 사항: 정리 정돈을 위해 locationInput을 Search 컨테이너 안으로 이동시킵니다.

     

   • 템플릿 프로젝트는 Text Input에 다음 설정을 사용합니다.

     • 크기: 226 x 40

     • 반경: 8

     • 플레이스홀더 색상: D0D0D0

     • 박스 채우기: FFFBFB

   2. 이미지 레이어 만들기:

      • 지도 플레이스홀더 역할을 할 "Image" 레이어를 추가하거나 찾아 이름을 mapImage로 지정합니다.

파트 3: ProtoPie를 Google Places API에 연결하기(ProtoPie Connect를 통해)

여기가 바로 ProtoPie Connect의 진가가 발휘되는 곳입니다. Connect의 API 플러그인을 사용하여 Google Places에 HTTP 요청을 보낼 것입니다.

3.1 Google Places API(New) 알아보기

설정을 시작하기 전에 왜 Google Places API(New)가 이 프로젝트의 핵심인지 이해할 필요가 있습니다. 이는 Google의 최신 위치 데이터 API로, 이전 버전보다 더 나은 성능, 향상된 데이터 품질, 유연한 요금제를 제공하며 비즈니스부터 관심 지점(POI), 일반 지리적 위치에 이르기까지 모든 것을 포함합니다.

이 튜토리얼에서는 "Text Search" 기능을 사용합니다. 이를 통해 "에펠탑"이나 "뉴욕"과 같은 일반 텍스트 쿼리를 전송하여 상세한 장소 정보를 받아볼 수 있으며, 여기에는 중요한 정밀한 latitude(위도) 및 longitude(경도) 좌표가 포함됩니다. 이는 입력된 위치를 지도 서비스가 실제로 사용할 수 있는 정보로 변환하는 데 필요한 필수적인 첫 단계입니다.

3.2 왜 ProtoPie Connect인가요?

Pie 프로토타입 자체만으로는 직접 API 호출을 할 수 없습니다. 이것이 바로 ProtoPie Connect가 메워주는 공백입니다. Connect는 프로토타입과 외부 서비스 사이의 다리 역할을 합니다. Google Places에 HTTP 요청을 보내고, 원시 응답을 받아, Pie가 이를 처리하고 표시할 수 있도록 다시 전달합니다. Connect가 없다면 프로토타입이 필요한 좌표를 가져올 방법이 없습니다.

3.3 사용자 입력 캡처하기

먼저, 프로토타입이 사용자가 입력하는 내용을 지속적으로 추적하고 이를 변수에 저장하도록 해보겠습니다.

1. 새 텍스트 변수 만들기:

• 변수 패널(ProtoPie Studio 좌측 하단)을 엽니다.

• 사용자가 입력하는 내용을 저장할 searchInput이라는 이름의 새 텍스트 변수(모든 씬 대상 / 글로벌)를 만듭니다.

• 변수의 타입이 "Number"가 아니라 "Text"로 설정되어 있는지 확인하세요.

2. Detect 트리거로 입력 캡처하기:

• "Detect" 트리거를 추가합니다.

• 대상: locationInput → Text (입력 필드의 텍스트 속성을 감시합니다).

• Detect 트리거 내에 "Assign" 응답을 추가합니다.

  • 대상: searchInput 변수

  • 공식: locationInput.text

• 작동 원리: 사용자가 타이핑하면 locationInput.text가 변경되고, Detect 트리거가 실행되며, Assign 응답이 searchInput을 최신 텍스트로 업데이트합니다. 디버그를 켜서 변수가 실시간으로 업데이트되는 모습을 확인하세요.

• 미리보기를 열고 필드에 텍스트를 입력해 보세요. 디버그 뷰에서 searchInput이 실시간으로 업데이트되는 것을 볼 수 있습니다.

1. 참고: 진행하면서 트리거와 응답에 설명이 포함된 이름을 지정하세요. 미래의 자신(그리고 프로젝트를 열어볼 다른 사람들)에게 큰 도움이 될 것입니다.

3.4 Return 키로 API 요청 트리거하기

1. 두 개의 새 글로벌 변수 추가하기:

   • googleMapsRequestBody(텍스트 변수, 모든 씬 대상): Places API(New)를 위한 전체 JSON 요청 본문을 담습니다. 이 변수를 다음 문자열로 초기화하세요.

{

"textQuery": "<INPUT QUERY>", "languageCode": "ko", "regionCode": "kr"

}

• textQuery는 사용자의 검색 쿼리가 들어갈 필드입니다.

• <INPUT QUERY>는 실제 입력값으로 교체할 플레이스홀더입니다.

• languageCode: "ko"는 응답 언어를 한국어로 설정합니다.

• regionCode: "kr"은 검색 결과를 대한민국 쪽으로 편향시킵니다 — 원하는 지역에 맞게 조정하세요.

  

• inputQuery(텍스트 변수, 모든 씬 대상): 동적으로 교체할 플레이스홀더 변수입니다. <INPUT QUERY>로 초기화하세요.

  

2. "Return" 트리거 추가하기:

• locationInput 레이어를 선택합니다.

• "Return" 트리거를 추가합니다. 이는 검색 필드의 자연스러운 패턴인 사용자가 Enter/Return 키를 누를 때 실행됩니다.

  

3. 요청 본문 준비 및 전송:

• "Return" 트리거 내에 "Assign" 응답을 추가합니다.

  • 대상: googleMapsRequestBody

  • 공식: replace(googleMapsRequestBody, inputQuery, searchInput)

  • 작동 원리: 이 공식은 googleMapsRequestBody 내에서 inputQuery(처음에는 <INPUT QUERY>)의 모든 인스턴스를 찾아 사용자가 방금 입력한 텍스트인 searchInput으로 교체합니다.

• 다음 검색을 위해 inputQuery를 재설정하는 또 다른 "Assign" 응답을 추가합니다.

  • 대상: inputQuery

  • 공식: searchInput

  • 작동 원리: 교체 작업 후, inputQuery를 현재 검색어로 업데이트합니다. 다음 검색 시 replace는 해당 검색어를 찾아 새 검색어로 교체하므로 검색 시마다 하드코딩할 필요가 없습니다.

• 요청을 발송할 "Send" 응답을 추가합니다.

  • 채널: ProtoPie Connect/Studio

  • 메시지: searchTextRequest (ProtoPie Connect가 수신 대기하는 메시지)

  • 값: 공식 → googleMapsRequestBody

    

• 이를 통해 동적으로 구성된 완전한 JSON 요청 본문이 Connect로 전송됩니다.

3.5 응답 수신 및 Mapbox URL 작성

ProtoPie Connect가 Google Places로부터 응답을 받으면 이를 Pie에 전달합니다. 여기에서 해당 데이터를 수신하고 좌표를 분석하여 Mapbox Static Images API URL을 동적으로 작성하는 데 사용합니다.

1. 필요한 변수 설정하기(모든 씬 대상):

• apiResponseRaw(텍스트 변수): ProtoPie Connect로부터 원시 JSON을 수신합니다.

• latitude(텍스트 변수): 추출된 위도를 저장합니다.

• longitude(텍스트 변수): 추출된 경도를 저장합니다.

• mapBox_URL(텍스트 변수): 위도와 경도의 플레이스홀더(<LAT> 및 <LON>)를 포함하는 기본 Mapbox URL을 담습니다.

https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/<LON>,<LAT>,14,0/1200x800?access_token=YOUR_MAPBOX_TOKEN

참고: YOUR_MAPBOX_TOKEN을 실제 Mapbox 액세스 토큰으로 교체하세요.

• currentlatitudePlaceholder(텍스트 변수): <LAT>로 초기화하여 mapBox_URL에 삽입된 마지막 위도 값을 추적합니다.

• currentLongitudePlaceholder(텍스트 변수): <LON>로 초기화하여 mapBox_URL에 삽입된 마지막 경도 값을 추적합니다.

  

2. "Receive" 트리거 추가하기:

   • 채널: ProtoPie Connect/Studio

   • 메시지: searchLocationReceived

   • 변수에 할당: 이 상자를 체크하고 apiResponseRaw(타입: Text)를 선택합니다.

     

3. apiResponseRaw에 대한 "Detect" 트리거 추가하기:

   • 대상: apiResponseRaw

   • 그 내부에 좌표를 추출할 두 개의 "Assign" 응답을 추가합니다.

     • 위도 — 대상: latitude, 공식: parseJson(apiResponseRaw, "places.0.location.latitude")

     • places.0은 places 배열의 첫 번째 결과(API는 둘 이상의 매치를 반환할 수 있음)를 가리키며, location.latitude는 원하는 값의 경로입니다.

       

     • 경도 — 대상: longitude, 공식: parseJson(apiResponseRaw, "places.0.location.longitude")

       

4. longitude에 대한 "Detect" 트리거 추가하기:

   • 대상: longitude

   • 그 내부에:

     • Assign — 대상: mapBox_URL, 공식: replace(mapBox_URL, currentLongitudePlaceholder, longitude)

       

     • Assign — 대상: currentLongitudePlaceholder, 공식: longitude

       

     • Assign — 대상: isMapReady, 공식: isMapReady + 1

       

5. latitude에 대한 "Detect" 트리거 추가하기:

• 대상: latitude

• 그 내부에:

  • Assign — 대상: mapBox_URL, 공식: replace(mapBox_URL, currentLatitudePlaceholder, latitude)

    

  • Assign — 대상: currentLatitudePlaceholder, 공식: latitude

    

  • Assign — 대상: isMapReady, 공식: isMapReady + 1

    

6. isMapReady에 대한 "Detect" 트리거 추가하기(이미지 로드용):

• 대상: isMapReady

• 조건: isMapReady = 2 — 이는 mapBox_URL에 두 좌표가 모두 입력되었음을 확인합니다.

  • "Image" 응답으로 응답 — 대상: mapImage, 소스: 공식, 공식: mapBox_URL

  • Assign — 대상: isMapReady, 공식: 0 (다음 검색을 위해 초기화)

3.6 ProtoPie Connect에서 API 플러그인 설정하기

이제 searchTextRequest를 처리하고 Google Places API(New)와 통신하도록 ProtoPie Connect를 설정해 보겠습니다.

1. ProtoPie 파일을 로컬이나 클라우드에 저장합니다.

2. 저장된 .pie 파일을 ProtoPie Connect에서 엽니다.

3. 우측 상단의 "Plugin"을 클릭합니다.

4. 플러그인 목록에서 "API"를 선택하고 "+"를 클릭합니다.

5. API 플러그인 설정:

   • 메서드: POST

   • URL: https://places.googleapis.com/v1/places:searchText

   • 헤더: { "Content-Type": "application/json", "X-Goog-Api-Key": "YOUR_GOOGLE_API_KEY", "X-Goog-FieldMask": "places.location" }

     (YOUR_GOOGLE_API_KEY를 실제 Google API 키로 교체하세요.)

• 본문(Body): 비워 둡니다 — Pie에서 동적으로 생성됩니다.

• Pie에서 보내는 메시지(Message From Pie): searchTextRequest

• Override를 체크하고 BODY를 Message Value로 설정합니다.

• Pie로 보내는 메시지(Message To Pie): searchLocationReceived

• "Activate"를 클릭합니다.

  

파트 4: 프로토타입 테스트하기

1. 처음 로드한 이후 변경 사항이 있는 경우, ProtoPie Connect에서 Pie가 업데이트되었는지 확인하세요.

2. ProtoPie Connect가 실행 중이고, Pie가 로드되었으며, API 플러그인이 활성화되었는지 확인합니다.

3. ProtoPie Connect의 미리보기 링크를 통해 웹 브라우저에서 프로토타입을 실행합니다.

4. 입력 필드에 "에펠탑" 또는 "타임스 스퀘어"와 같은 위치를 입력하고 Enter 키를 누릅니다.

5. 지도가 새 위치를 중심으로 다시 로드되어야 합니다.

   

   팁: 정적 지도는 항상 검색된 위치를 중심으로 로드되므로, ProtoPie 캔버스의 중심에 마커를 배치하면 사용자가 어디를 검색하든 항상 지도의 올바른 지점을 가리키게 됩니다.

   

추가 개선 사항

핵심 흐름이 작동하면 지도를 가져오는 동안 로딩 화면을 표시하거나, 더 정교한 느낌을 주기 위해 지도 드래그 인터랙션을 추가하는 것을 고려해 보세요.

직접 시도해 볼 준비가 되셨나요?

Google Places와 Mapbox만이 ProtoPie 프로토타입에 가져올 수 있는 유일한 API는 아닙니다. 이제 기본 패턴(Connect로 데이터 가져오기, 공식에 입력하기, UI 업데이트하기)을 알았으니 동일한 방식으로 다른 위치, 데이터 또는 미디어 서비스를 연결할 준비가 되었습니다.

ProtoPie Studio와 Connect를 다운로드하고 빌드를 시작해 보세요.