Overview
🔎 들어가기 전에
본 문서는 Amplitude의 Ampli 기능을 활용해 데이터를 수집하는 방법에 대해 안내합니다. 아래 내용을 포함합니다.
Ampli 기능 소개
Ampli 활용 목적 및 효과
Ampli 세팅 방법
자주 묻는 질문
1. Ampli 기능 소개
1-1. Ampli가 무엇인가요?
Ampli는 앰플리튜드 프로젝트에 데이터를 오류없이 쉽게 수집하기 위한 기능입니다. Ampli를 활용하면 이벤트, 이벤트 프로퍼티, 유저 프로퍼티 수집을 더 엄격하게 관리할 수 있습니다. Ampli는 Ampli CLI와 Ampli Wrapper로 구성되어 있습니다.
1-2. Ampli가 작동하는 구조
앰플리튜드 프로젝트 > Data > Events/Properties 메뉴(이하 Tracking Plan)에서 설정한 정보를 Ampli CLI로 가져옵니다.
해당 정보를 Ampli Wrapper로 전송하여 수집합니다.
(1) Ampli CLI
Ampli CLI는 앰플리튜드 프로젝트 내 Tracking Plan에서 설정한 정보를 가져와 Wrapper로 전달하는 역할을 합니다.
Tracking Plan에서 미리 생성한 이벤트 예시입니다.
(2) Ampli Wrapper
Ampli Wrapper는 Ampli를 활용하여 코드를 쉽게 작성할 수 있도록 도와주는 역할을 합니다.
Ampli Wrapper를 사용하기 위해서는 사전에 반드시 Amplitude SDK가 먼저 설치되어있어야 합니다.
2. Ampli 활용 목적 및 효과
(1) Tracking Plan을 관리하는 담당자가 이벤트 구조를 직접 제어할 수 있습니다.
(2) 이벤트를 수집할 때 발생할 수 있는 휴먼 에러를 방지합니다.
이벤트 이름
이벤트 프로퍼티 이름
이벤트 프로퍼티 타입
유저 프로퍼티 이름
유저 프로퍼티 타입
(3) 이를 통해 아래와 같은 문제를 사전에 방지할 수 있습니다.
동일한 이벤트이나 Android와 iOS에서의 이벤트 명이 서로 다르게 수집됩니다.
Boolean 타입으로 수집되어야 하는 데이터가 String으로 수집되고 있습니다.
이벤트 명을 잘못 입력해서 수집 의도와 다른 데이터가 수집되고 있습니다.
이벤트 명을 잘못 수집한 적이 있어 같은 의미를 가진 여러 개의 이벤트명이 수집되고 있습니다.
3. Ampli 세팅 방법
Ampli 사용을 위한 세팅은 아래와 같이 세 단계로 진행됩니다. 더 구체적인 내용은 Ampli 가이드를 참고해주세요.
(1) Tracking Plan에 데이터 추가하기
(2) Ampli CLI 설치 및 설정하기
(3) Client에서 Ampli Wrapper 적용하기
일부 SDK에서는 Ampli를 지원하고 있지 않습니다. 꼭 확인해주세요! (가이드)
지원하지 않는 SDK 목록
Flutter SDK
게임 SDK - Unity SDK, Unreal SDK
네이티브 Android, iOS 레거시(Legacy) SDK
(1) Tracking Plan에 데이터 추가하기
Tracking Plan에 이벤트와 프로퍼티를 추가하는 과정입니다. Ampli CLI, Ampli Wrapper를 활용하기 전 반드시 먼저 진행되어야 하는 과정입니다.
Data > Sources에서 서비스의 개발 플랫폼을 등록합니다. 이미 등록한 경우 Source의
Name을 확인합니다.Tracking Plan에서 이벤트 및 이벤트 프로퍼티를 추가합니다.
Event Status에 대한 설명
기존에 수집한 이력이 없고 Tracking Plan에서 새롭게 생성한 이벤트의 경우 Status가
Planned로 나타납니다.이미 데이터가 수집되었고 정상적인 데이터인 경우 Status를
Live로 변경합니다.
각 이벤트의 탭에서
+Add source를 클릭하여 위에서 등록한 Source(플랫폼)를 추가합니다. 이미 데이터를 수집하고 있어 Source가 등록되어 있다면 다음 단계로 넘어갑니다.
이벤트 프로퍼티를 생성하고, 타입을 선택한 후,
+Add property를 클릭하여 이벤트에 추가합니다. 이벤트와 동일하게 이미 수집 중인 데이터이고, 타입이 정확하다면 Status를Live로 변경합니다.
(2) Ampli CLI 설치 및 설정하기
개발 환경에 Ampli를 설치합니다.
Homebrew또는npm으로 설치
ampli login을 실행한 다음, CLI에서 Amplitude 계정에 로그인합니다.브라우저에서 Authorize 선택 → 로그인 완료 → CLI에서 계정 및 org 확인
터미널에서 내 서비스의 프로젝트의 루트(root) 경로로 이동합니다.
ampli pull을 실행합니다.User 선택 → Workspace 선택 → SDK 설치하라는 문구가 나오면 완료
개발 프로젝트에 아래 데이터가 추가되었는지 확인합니다.
Ampli 폴더와 Ampli 파일
ampli.json파일
만약 Tracking Plan에서 이벤트가 추가, 삭제 또는 변경됐다면,
ampli pull명령어로 최신 정보를 불러옵니다.
(3) Client에서 Ampli Wrapper 적용하기
Amplitude SDK를 설치합니다.
Ampli 파일과
ampli.json파일을 확인합니다.ampli.json: Amplitude 프로젝트 정보
Ampli 파일: Tracking Plan에서 생성했던 이벤트 정보 확인
Ampli를 init 합니다.
Ampli를 활용하면 Amplitude SDK가 아닌 Ampli로 init할 수 있습니다.
Amplitude SDK가 아니라 Ampli로 이벤트를 수집합니다. 이미 등록해둔 이벤트는 코드가 자동완성됩니다.
작업 중인 개발자가 이벤트 이름, 이벤트 프로퍼티 이름, 이벤트 프로퍼티 타입 등을 잘못 입력했을 때, 예를 들어 아래와 같이 에러 메시지가 노출됩니다.
“Double 타입을 기대했는데 String이 들어왔습니다.”
기존 Amplitude SDK에서 직접 수집할 때는 이런 부분을 잘못 입력해도 별도 에러 메시지 없이 수집이 진행됩니다.
자주 묻는 질문
Q) Amplitude SDK 없이 Ampli만 설치해서 사용할 수 있나요?
A) 불가능합니다. 플랫폼에 맞는 Amplitude SDK 설치는 반드시 필요합니다.
Q) Tracking Plan에서 이벤트 및 이벤트 프로퍼티가 추가되면 자동으로 반영되나요?
A) 자동으로 반영되지 않습니다.
ampli pull을 통한 최신정보 업데이트가 필요합니다.
Q) Ampli에서 먼저 코드를 작성하고 Tracking Plan에 이를 반영할 수는 없나요?
A) 불가능합니다. Tracking Plan에서 설정한 데이터를 가져오는(
pull) 기능만 제공합니다.
관련 자료
앰플리튜드 Ampli에 대해 더 알아보고자 하신다면, 아래 유저 가이드 및 Github을 참고해 주세요.