Amplitude 사용법을 직접 익히면서 웹 애플리케이션의 사용자 행동을 분석해 봤습니다. 방문자 수보다 더 궁금한 것이 생겼기 때문입니다. 사용자는 어떤 기능을 실제로 사용하고, 어디에서 이탈할까요? 이번 글에서는 제가 개발한 지도 기반 가맹점 탐색 서비스 ‘인지도’에 Amplitude Analytics를 직접 연동한 과정을 정리했습니다. AI 코딩 도구를 활용한 SDK 설치부터 커스텀 이벤트, 퍼널 분석, 개발·운영 데이터 분리까지 실제로 확인한 화면과 함께 소개합니다.
이 글에서 다루는 범위: Amplitude 최초 연동 → 이벤트 수신 확인 → Autocapture와 커스텀 이벤트 비교 → 가맹점 선택 이벤트 구현 → 첫 퍼널 구성 → 이벤트 측정 계획 → Live Events 검증 → Development/Production 분리. 실제 검증 결과와 앞으로 분석할 지표는 구분해서 설명합니다.
참고: 이 글의 화면과 결과는 작성 당시의 테스트 환경을 기준으로 합니다. Amplitude의 메뉴와 SDK 옵션은 버전에 따라 달라질 수 있습니다. 실제 프로젝트에 적용할 때는 공식 문서와 설치된 SDK 버전을 함께 확인하세요.
1. Amplitude 사용법을 익히게 된 이유
Amplitude는 사용자가 서비스 안에서 수행하는 행동을 이벤트 단위로 수집하고 분석하는 제품 분석(Product Analytics) 도구입니다. Google Analytics 4도 이벤트 기반 분석을 지원하지만, 이번에는 서비스 내부 기능 사용과 사용자 여정을 체계적으로 살펴보기 위해 Amplitude를 추가했습니다.
인지도 앱에서는 지도 방문, 검색, 가맹점 선택, 전화·길찾기, 공유가 하나의 사용자 여정으로 연결됩니다. 특히 지도 방문자 중 실제 가맹점을 선택한 사용자가 얼마나 되는지 확인하는 것이 첫 번째 목표였습니다.
지도 진입 → 검색·필터 → 가맹점 선택 → 전화·길찾기·공유 → 재방문2. Amplitude 사용법: AI 프롬프트로 SDK 연동하기
Amplitude 프로젝트를 만들고 초기 설정 화면으로 이동하니 ‘데이터 입력을 시작해 봅시다’라는 안내와 함께 AI 코딩 도구에 전달할 설치 프롬프트가 제공됐습니다. 저는 이를 Claude에 전달해 기존 앱 구조를 살펴보고 연동하도록 요청했습니다. 원본 프롬프트에 포함된 실제 키는 공개하지 않고, 아래에는 핵심 설정만 정리했습니다.
2.1 SDK 설치와 환경변수 설정
초기 설정 프롬프트는 브라우저 측 JavaScript에 Unified SDK를 설치하고, 프로젝트 API Key를 환경변수로 관리하도록 안내했습니다. 이번 앱은 Vite를 사용하므로 공개 클라이언트 변수 접두사인 VITE_를 적용했습니다.
npm install @amplitude/unified@^1
# web/.env (예시 — 실제 키는 기재하지 않음)
VITE_AMPLITUDE_API_KEY=<YOUR_DEVELOPMENT_API_KEY>주의: VITE_ 변수는 브라우저 번들에 포함될 수 있습니다. 브라우저 이벤트 수집용 키와 서버 측 비밀 인증정보를 구분하고, 비밀키는 절대로 프런트엔드 환경변수에 넣지 않아야 합니다.
2.2 초기화와 첫 이벤트 전송
초기 설정에서는 initAll()을 통해 분석 및 Session Replay 기능을 초기화하고, 첫 이벤트가 실제로 수신되는지 확인하도록 했습니다. 다음은 당시 설정 의도를 설명하기 위한 간략화된 참고 코드입니다. 실제 앱에서는 중복 초기화가 일어나지 않도록 초기화 위치를 한 곳으로 제한해야 합니다.
import * as amplitude from '@amplitude/unified';
const apiKey = import.meta.env.VITE_AMPLITUDE_API_KEY;
if (!apiKey) {
console.warn('Amplitude API key missing — analytics disabled');
} else {
amplitude.initAll(apiKey, {
analytics: { autocapture: true },
sessionReplay: { sampleRate: 1 },
});
}
// 최초 연동 검증용 이벤트: 실제 페이지 진입 시점에 한 번만 실행
// amplitude.track('Viewed Map Page');sampleRate: 1은 Session Replay를 100% 수집하도록 요청하는 설정으로, 초기 테스트에는 편리하지만 운영에서는 개인정보 보호·수집량·비용을 고려해 재검토해야 합니다. 실제 동작은 SDK 버전 및 프로젝트 설정에도 영향을 받습니다.
2.3 첫 번째 이벤트는 왜 Viewed Map Page였을까?
Claude가 코드베이스를 분석한 뒤 최초 검증용 이벤트 후보를 제시했습니다. 저는 가장 중요한 비즈니스 이벤트를 곧바로 설계하기보다, 우선 SDK가 연결되어 실제 이벤트가 도착하는지 확인하는 것이 목적이었기 때문에 지도 진입 이벤트인 Viewed Map Page를 선택했습니다.
로컬에서 인지도 앱을 실행하니 Amplitude에 Viewed Map Page가 들어왔습니다. 이 시점에 확인한 것은 인지도 앱 → SDK → Amplitude 프로젝트로 이벤트 전송이 성공했다는 사실입니다. 화면에는 Engagement Booted, [Amplitude] Viewport Content Updated, Replay Captured, Web Vitals 등 다른 이벤트도 보였지만, 각 기능의 완전한 동작 여부는 별도로 검증해야 합니다.
3. Live Events에서 실제 행동 확인하기
Amplitude의 Live Events로 이동해 실시간 이벤트 업데이트를 켠 다음, 지도에 표시된 가맹점을 직접 선택해 보았습니다. 이벤트 수집이 실제 사용자 행동과 연결되는지 확인하는 과정입니다.
처음에는 가맹점을 클릭해도 Selected Merchant가 보이지 않았습니다. 대신 Clicked div나 Clicked "10%"처럼 화면 요소를 클릭했다는 자동 수집 이벤트가 나타났습니다. 이는 Autocapture가 클릭 자체를 기록한 것이지, 사용자가 어떤 가맹점을 왜 선택했는지 알려주는 이벤트는 아니었습니다.
3.1 Autocapture와 커스텀 이벤트는 어떻게 다를까?
| 구분 | Autocapture | 커스텀 이벤트 |
|---|---|---|
| 수집 방식 | SDK가 지원하는 클릭·페이지 조회 등을 자동 수집 | 개발자가 제품 행동의 의미와 발생 시점을 정의 |
| 예시 | Clicked div | Selected Merchant |
| 장점 | 빠른 초기 수집 | 분석 목적에 맞는 의미와 속성 부여 |
| 주의점 | DOM 변화에 따라 해석이 어려울 수 있음 | 이벤트 설계와 중복 방지 필요 |
제가 궁금했던 것은 단순 클릭 수가 아니라 가맹점 선택이라는 핵심 행동이었습니다. 그래서 기존 Google Analytics의 select_merchant 로직을 참고해 Amplitude 커스텀 이벤트를 추가하기로 했습니다.
4. Selected Merchant 이벤트 직접 구현하기
AI 코딩 도구에는 기존 기능을 유지하면서, 사용자가 지도에서 가맹점을 선택해 하단 상세 카드가 열리는 시점에 이벤트를 기록하도록 요청했습니다. 또한 동일한 사용자 행동으로 이벤트가 중복 전송되지 않도록 확인하도록 했습니다.
Amplitude 연동은 정상적으로 완료되었습니다.
사용자가 지도에서 가맹점을 선택하여 하단 상세 카드가 열릴 때
Selected Merchant 이벤트가 발생하도록 구현해줘.
기존 GA select_merchant 이벤트가 있다면 동일한 로직을 참고해줘.
이벤트명: Selected Merchant
속성: merchant_id, merchant_name, category, region,
benefit_rate, selection_source
선택 경로 예시: map_marker, search, building_list
기존 기능 및 GA 이벤트는 유지하고, 동일 행동에서 중복 발생하지 않게 해줘.이벤트 속성(Event Properties)은 이벤트가 발생한 맥락을 설명하는 데이터입니다. 예를 들어 region은 지역별 선택 현황을, selection_source는 지도 마커·검색·목록 중 어떤 경로로 선택했는지를 분석하는 데 활용할 수 있습니다.
코드를 수정하고 앱에서 가맹점을 다시 선택하자 Selected Merchant가 실제로 들어왔습니다. 이제 최소한의 핵심 흐름인 Viewed Map Page → Selected Merchant를 이벤트로 확인할 수 있게 됐습니다.
5. Amplitude 사용법: 첫 번째 전환 퍼널(Funnel) 구성하기
퍼널 분석은 사용자가 정해진 순서의 행동을 얼마나 완료했는지 확인하는 방법입니다. 인지도 앱에서는 ‘지도에 방문한 사용자 중 실제로 가맹점을 선택한 사용자는 몇 %인가?’라는 질문에 답하기 위해 두 단계의 퍼널을 구성했습니다.
1단계: Viewed Map Page — 지도 화면에 진입
↓
2단계: Selected Merchant — 가맹점을 선택
예를 들어 같은 기간·동일한 퍼널 조건에서 1,000명이 지도를 방문하고 그중 620명이 정해진 전환 시간 내에 가맹점을 선택했다면 전환율은 62%입니다. 이 숫자는 계산을 설명하기 위한 가상 예시이며 실제 서비스의 측정 결과가 아닙니다. Amplitude에서는 이벤트 순서, 전환 제한 시간, 사용자 집계 방식에 따라 값이 달라질 수 있습니다.
6. 이벤트 속성과 사용자 타임라인 확인하기
퍼널이 만들어졌다면 이벤트 속성도 제대로 들어오는지 확인해야 합니다. Live Events에서 Selected Merchant를 열어 가맹점 ID, 이름, 업종, 지역, 혜택 비율, 선택 경로가 수집되는지 점검했습니다.
| 속성 | 예시 | 분석 목적 |
|---|---|---|
| merchant_id | 가맹점 식별자 | 가맹점별 선택 집계 |
| merchant_name | 가맹점명 | 어떤 가맹점을 선택했는지 확인 |
| category | 음식점 | 업종별 분석 |
| region | 계양구 | 지역별 분석 |
| benefit_rate | 10 | 혜택 비율별 비교 |
| selection_source | map_marker | 지도·검색·목록 등 선택 경로 비교 |
특히 selection_source=map_marker처럼 선택 경로가 기록되면 검색 결과에서 발견한 가맹점과 지도에서 직접 발견한 가맹점을 구분할 수 있습니다. 다만 공개 글에 사용자의 개인 식별 정보나 불필요한 위치정보를 포함하지 않도록 주의해야 합니다.
실제 타임라인에서는 Start Session → Viewed Map Page → 약 11초 후 Selected Merchant 흐름을 확인했습니다. 단순한 이벤트 개수뿐 아니라 한 세션에서 행동이 어떤 순서로 일어났는지 볼 수 있게 된 것입니다. Session Replay는 개인정보 마스킹과 수집 비율을 검토한 후 운영에 적용하는 것이 안전합니다.
7. 이벤트를 무작정 추가하지 않고 Measurement Plan 만들기
초기 연동과 첫 퍼널을 만들고 나니 이벤트를 더 많이 수집하는 것보다 제품에서 어떤 행동이 의미 있는지 먼저 정의하는 일이 중요하다는 것을 느꼈습니다. 그래서 사용자 여정을 기준으로 이벤트 측정 계획(Measurement Plan)을 정리했습니다. 아래는 구현 상태가 모두 동일한 것은 아니며, 실제 확인한 이벤트와 추가 분석을 위한 계획을 함께 정리한 표입니다.
| 단계 | 이벤트 | 목적 |
|---|---|---|
| 진입 | Viewed Map Page | 지도 방문 |
| 탐색 | Searched Merchant | 가맹점 검색 |
| 탐색 | Applied Filter | 지역·업종·혜택 필터 사용 |
| 발견 | Selected Merchant | 가맹점 선택 |
| 행동 | Clicked Call | 전화 연결 시도 |
| 행동 | Clicked Navigation | 지도 앱 이동 시도 |
| 공유 | Shared Merchant | 공유 행동 |
| 공유 유입 | Opened Shared Merchant | 공유 링크 방문 |
| 보조 | Used Current Location | 현재 위치 기능 사용 |
| 문제 | Search No Results | 검색 결과가 없는 상황 |
| 문제 | Reported Merchant | 가맹점 정보 오류 제보 |
특히 Searched Merchant는 타이핑할 때마다 전송하면 이벤트가 과도하게 늘어날 수 있습니다. 검색어 입력 후 일정 시간(이번 테스트 계획에서는 1초) 정지하거나 검색 결과를 선택했을 때 전송하는 식으로 발생 조건을 정해야 합니다. 필터 이벤트 역시 값이 실제로 변경된 경우에만 전송하는 것이 좋습니다.
7.1 어떤 지표를 볼 것인가?
| 지표 | 예시 정의 | 해석 시 주의점 |
|---|---|---|
| Activation | Viewed Map Page → Selected Merchant | 핵심 기능 경험의 초기 후보 지표 |
| Intent | 가맹점 선택 → 전화 또는 길찾기 클릭 | 실제 방문·구매가 아니라 이용 의도 신호 |
| Retention | 첫 탐색 후 7일·30일 이내 다시 탐색 | 동일 사용자 식별과 코호트 조건 필요 |
| Referral | 공유 → 공유 링크 유입 | 공유 횟수와 실제 유입은 구분 |
장기적으로는 WAU(주간 활성 사용자), 가맹점 탐색 사용자, 가맹점 선택률, 후속 행동률, 7일·30일 Retention, 공유 유입을 대시보드로 확인하려고 합니다. 이는 앞으로 분석할 목표 지표이며, 아직 실측 성과를 의미하지 않습니다.
8. Live Events 수동 검증 체크리스트
이벤트 코드를 작성한 다음에는 실제 사용자 행동을 재현하면서 이벤트가 의도대로 발생하는지 확인해야 합니다. 이번에 정리한 테스트 시나리오는 다음과 같습니다.
| 행동 | 기대 이벤트 | 확인 사항 |
|---|---|---|
| 앱 진입 | Viewed Map Page | 진입 시 중복 없이 기록 |
| 검색 후 1초 대기 | Searched Merchant | query·result_count 확인 |
| 결과 없는 검색 | Search No Results | result_count=0 |
| 지역·업종·혜택 필터 변경 | Applied Filter | filter_type·filter_value 확인 |
| 지도 마커 선택 | Selected Merchant | selection_source=map_marker |
| 검색 결과 선택 | Selected Merchant | selection_source=search |
| 건물 내 목록에서 선택 | Selected Merchant | selection_source=building_list |
| 전화 클릭 | Clicked Call | 전화번호를 속성으로 전송하지 않음 |
| 지도 앱 이동 | Clicked Navigation | provider=naver/kakao/tmap |
| 공유·링크 방문 | Shared Merchant / Opened Shared Merchant | 공유 방식·진입 경로 확인 |
| 현재 위치 기능 | Used Current Location | 정확한 좌표 수집 여부 확인 |
| 오류 제보 성공 | Reported Merchant | 성공 시에만 기록 |
실제 테스트 타임라인에서는 Applied Filter → Selected Merchant → Shared Merchant → Viewed Map Page → Opened Shared Merchant → Selected Merchant 흐름을 확인했습니다. 이렇게 이벤트가 연결되면 공유 기능이 신규 방문으로 이어지는지 추적할 기반을 마련할 수 있습니다. 다만 몇 건의 테스트만으로 공유 효과를 입증할 수는 없습니다.
9. Development와 Production 프로젝트 분리하기
개발자가 로컬에서 수십 번 클릭한 이벤트가 운영 지표에 섞이면 실제 사용자 전환율이나 유지율이 왜곡될 수 있습니다. 이를 방지하려고 Amplitude 프로젝트를 개발용과 운영용으로 분리했습니다.
Amplitude
├── Ingdo Production
│ └── 실제 서비스 사용자 이벤트
└── Ingdo Development
└── localhost 및 개발·테스트 이벤트Amplitude 프로젝트별로 API Key가 발급되므로 환경에 따라 다른 프로젝트로 이벤트를 전송할 수 있습니다. 한 프로젝트에서 environment 속성으로 구분하는 방식도 가능하지만, 분석할 때 필터를 누락하는 실수를 줄이기 위해 별도 프로젝트를 선택했습니다.
# web/.env — 개발 환경
VITE_AMPLITUDE_API_KEY=<YOUR_DEVELOPMENT_API_KEY>
# web/.env.production — 운영 환경
VITE_AMPLITUDE_API_KEY=<YOUR_PRODUCTION_API_KEY>Vite는 빌드 모드에 따라 환경변수를 로드하므로 실제 배포 파이프라인이 어떤 모드로 빌드하는지 확인해야 합니다. 브라우저용 수집 키만 이 방식으로 사용하고, 서버 비밀키는 별도로 보관해야 합니다.
개발 프로젝트에서 Viewed Map Page, Applied Filter, Selected Merchant, Shared Merchant, Opened Shared Merchant 등이 수집되는 것을 확인했고, 이후 운영 환경에도 변경 사항을 배포했습니다. 다만 운영 환경의 모든 이벤트와 장기 분석 지표가 검증 완료되었다고 단정할 수는 없으므로 이후 별도 모니터링이 필요합니다.
10. 운영 환경에서 놓치기 쉬운 주의사항
- 중복 초기화·중복 전송: SPA 재렌더링이나 이벤트 핸들러 중복 등록으로 실제 행동보다 많은 이벤트가 수집되지 않는지 확인합니다.
- 개인정보 보호: 전화번호, 정확한 위치 좌표, 민감한 입력값을 불필요하게 이벤트 속성으로 보내지 않습니다.
- Session Replay: 마스킹, 제외 대상, 수집 비율과 비용을 검토합니다.
- 이벤트 명명 규칙: 같은 의미의 행동을 여러 이름으로 기록하지 않고 이벤트명과 속성을 일관되게 관리합니다.
- 환경 분리: 배포 후 운영 프로젝트에 실제 운영 이벤트가 도착하는지, 개발 이벤트가 혼입되지 않는지 확인합니다.
11. 적용 결과와 앞으로의 계획
| 항목 | 이번 작업에서 확인한 상태 |
|---|---|
| SDK 연동 | 최초 이벤트 수신 확인 |
| Viewed Map Page | Live Events 수신 확인 |
| Selected Merchant | 수신 및 속성 확인 |
| 첫 전환 퍼널 | 지도 방문 → 가맹점 선택 구성 |
| 추가 이벤트 | 개발 환경에서 필터·공유 관련 흐름 검증 |
| 개발/운영 분리 | 별도 프로젝트 및 환경변수 구성 |
| 운영 배포 | 배포 완료 기록 |
| 실제 사용자 전환율·Retention | 향후 데이터 축적 후 분석 |
이번 경험에서 가장 큰 변화는 단순히 ‘사용자가 들어왔다’를 확인하는 데서 벗어나, 어떤 기능을 사용했고 다음 행동으로 이어졌는지 확인할 기반을 만든 것입니다. 앞으로는 실제 운영 데이터로 지역·업종별 탐색, 전화·길찾기 전환, 재방문, 공유 유입을 분석해 제품 개선에 연결해 볼 계획입니다.
마무리: 이벤트를 많이 모으는 것보다 중요한 것
Amplitude를 처음 연결할 때는 SDK 설치와 이벤트 전송이 목표였습니다. 하지만 실제로 퍼널을 만들고 이벤트 속성을 검증해 보니, 더 중요한 것은 제품에서 어떤 사용자 행동을 성공으로 볼지 정의하는 일이었습니다. Autocapture는 출발점이 될 수 있지만, 제품의 핵심 경험을 이해하려면 의미 있는 커스텀 이벤트와 일관된 측정 계획이 필요합니다.
이번 글이 Amplitude를 처음 도입하는 개발자나 PM에게, 단순한 설치 안내를 넘어 작은 이벤트 하나부터 실제 제품 분석으로 확장하는 과정을 이해하는 데 도움이 되길 바랍니다.
자주 묻는 질문
Amplitude와 Google Analytics를 함께 사용할 수 있나요?
네. 이번 사례처럼 기존 GA 이벤트를 유지하면서 Amplitude 이벤트를 추가할 수 있습니다. 다만 두 도구에서 이벤트 발생 조건이 다르면 수치가 달라질 수 있으므로 정의를 문서화하는 것이 좋습니다.
Autocapture만으로 충분하지 않나요?
기본 클릭·페이지 조회 파악에는 유용하지만, 가맹점 선택이나 공유 완료처럼 제품의 의미가 중요한 행동은 커스텀 이벤트로 정의하는 편이 좋습니다.
개발 환경과 운영 환경을 꼭 분리해야 하나요?
반드시 별도 프로젝트를 만들어야 하는 것은 아닙니다. 다만 테스트 이벤트가 실제 전환율과 유지율에 섞이는 위험을 줄이려면 프로젝트 분리가 편리합니다.