앰플리튜드도 codegen 되는 시대

Tech
2023-10-05

배경

동아리에서 만들고 있는 프로덕트에 앰플리튜드를 도입할 일이 있었습니다. 회사에서도 한 번 도입한 경험이 있어 자신 있게 기존 방식대로 구현했는데, 팀원에게 Ampli라는 더 좋은 방법을 추천받게 되었습니다. 타입 안정성이 확실하게 올라갔다는 점에서 Ampli의 장점을 깨달았고 앞으로도 계속 활용하고자 관련 내용을 정리해두고자 합니다.

준비

앰플리튜드를 codegen을 위해 2가지 준비가 필요합니다.

  • Events와 Properties가 Amplitude Data에 이미 세팅되어 있어야 합니다. Events의 source에 Browser SDK(web)가 없으면 codegen이 안 되기 때문에 꼭 source를 아래 스크린샷처럼 추가해야 합니다.

  • 프로젝트를 생성할 때 발급받은 API key는 .env 파일을 만들어 넣어둡니다. 저는 Next.js 환경에서 개발했기 때문에 _app.tsx에서 process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY 형태로 API key 값에 접근했습니다.

설치

$ yarn add @amplitude/analytics-browser
$ npm install -g @amplitude/ampli

패키지가 잘 설치되었다고 뜨면 pull command를 실행합니다.

$ ampli pull

아래 스크린샷처럼 로그인 이후 옵션을 선택합니다.

선택을 완료하면 프로젝트 설정에 맞게 2가지 파일이 자동으로 추가됩니다.
(1) src/ampli/index.ts (예시)
(2) ampli.json (예시)

적용

여기서부터는 친절한 공식 문서를 보면서 자신의 프로젝트에 알맞게 코드를 추가하면 됩니다.
혹은 ampli-examples를 참고해도 좋습니다.

제 경우에는 우선 _app.tsx에 load()로 Ampli Wrapper를 initialize 했습니다.

ampli.load({
  client: {
    apiKey: process.env.NEXT_PUBLIC_AMPLITUDE_API_KEY,
    configuration: {
      defaultTracking: true,
      minIdLength: 1,
    },
  },
});

유저 정보를 얻기 위해서는 ampli.identify(user.data.orgId)와 같은 세팅이 필요했습니다.

Ampli wrapper는 이벤트를 큐에 넣어두고, 간격에 따라 이벤트를 전송하는 방식으로 동작합니다. pending event까지 모두 전송하기 위해 ampli.flush()를 useEffect의 cleanup 함수에서 호출했습니다.

이후에는 컴포넌트에서 트래킹하고자 하는 이벤트의 function을 호출했습니다. import { ampli } from '@/ampli';가 된 상태에서 ampli.까지만 입력해도 미리 정의한 이벤트명이 주르륵 뜹니다.

clickFeedCard라는 이벤트를 선택하고, 해당 이벤트에 마우스를 호버했을 때 이벤트에 관한 정보를 확인할 수 있습니다.

properties까지 세팅한 코드는 아래와 같습니다.

<FeedItem
  onClick={() =>
    ampli.clickFeedCard({
      feed_id: id,
      feed_upload: updatedDate,
      feed_title: title,
      feed_image_total: images ? images.length : 0,
      feed_comment_total: commentCount,
      feed_like_total: likeCount,
      group_id: Number(meetingId),
      crew_status: meeting?.approved,
      platform_type: isMobile ? 'MO' : 'PC',
    })
  }
>

The Ampli Wrapper is a generated, strongly typed API for tracking Analytics events based on your Tracking Plan in Amplitude Data. The tracking library exposes a function for every event in your team’s tracking plan. The function’s arguments correspond to the event’s properties. Ampli can benefit your app by providing autocompletion for events & properties defined in Data and enforce your event schemas in code to prevent bad instrumentation.

공식 문서 Overview에 적힌 Ampli의 장점을 실감할 수 있는 순간이었습니다. type safety가 보장된다는 점이 마음에 들어 앞으로도 이벤트 로깅에 Ampli를 자주 활용할 것 같습니다.