Ampli

Ampli는 Amplitude 데이터의 분석 추적 계획을 기반으로 Amplitude SDK용 경량 래퍼를 동적으로 생성하므로 이벤트 트래킹을 더 쉽고 오류가 덜 발생하게 합니다.

이 문서는 Ampli에 대한 요약을 제공합니다. 자세한 내용은 Amplitude 아카데미를 방문하십시오.

주요 기사

추적 계획에서 타입이 지정된 래퍼를 생성하는 Ampli 다이어그램

Ampli Wrapper는 이벤트 이름과 속성 값을 엄격하게 적용함으로써 사람의 실수를 방지하는 유형과 메서드를 제공합니다. 래퍼 코드는 트래킹 플랜의 모든 이벤트와 속성에 대한 자동 완성을 가능하게 하며, 개발 및 컴파일 시 정적 유형 검사를 가능하게 합니다.

typescript
import { ampli, SongPlayed } from "./ampli";
// Ampli tracks these 2 events as expected.
ampli.songPlayed({ title: "Happy Birthday" });
ampli.track(new SongPlayed({ title: "Song 2" }));
// The following 2 events don't track due to data quality issues.
// Instead, they generate type errors at build time with information
// about the expected property names and types.
// Error: Event 'Song Played' is missing required property 'title'
ampli.songPlayed({ name: "I Knew You Were Trouble" });
// Error: Property 'title' received 'boolean' expected type 'String'
ampli.songPlayed({ title: true });

이를 범용 Amplitude SDK와 비교해 보십시오. 수동으로 입력한 값을 사용하여 이벤트를 전송하면 데이터 품질 문제가 발생할 수 있으며 데이터 관리자와 엔지니어 간의 긴밀한 협력이 필요합니다.

typescript
import * as amplitude from "@amplitude/analytics-browser";
// Amplitude tracks these 2 events as expected
amplitude.track("Song Played", { title: "Happy Birthday" });
amplitude.track({
  event_type: "Song Played",
  event_properties: { title: "Song 2" },
});
// Amplitude tracks the following 2 events, but they have data quality issues
// that make them difficult to include in analysis. Typos and type errors are
// easy to create and hard to find and fix.
// Charts based on 'title' don't include this event, which sets 'name' instead.
amplitude.track("Song Played", { name: "I Knew You Were Trouble" });
// Charts based on event_type='Song Played' don't include this event.
// It also sets 'title' to boolean 'true' instead of the expected type 'String'.
amplitude.track("sonG Playd", { title: true });

Ampli CLI는 Ampli Wrapper를 생성하고 이벤트의 계측 상태를 확인할 수 있습니다. 이를 통해 이벤트 트래킹 호출을 놓친 것이 있는지 쉽게 알 수 있으므로 구현이 완료되었음을 확신할 수 있습니다.

shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
✔ All events tracked: 1 found, 1 total

Amplitude 데이터

Amplitude 데이터를 사용하면 애플리케이션에서 추적하려는 이벤트와 속성을 정의하여 분석을 계획할 수 있습니다. Ampli를 사용하려면 Amplitude 데이터에 SDK 소스에 추가된 이벤트가 포함된 추적 계획이 필요합니다.

다음 예제에서는 이 추적 계획을 사용합니다.

  • 이름이 web인 브라우저 SDK 소스입니다.
  • 이벤트 Song Played는 String 유형의 필수 속성인 title을 가지고 실행됩니다.
  • 이벤트 Song Played가 소스 web에 추가되었습니다.
  • 이름이 production인 환경입니다.

Ampli CLI

Ampli CLI는 Amplitude 데이터에 연결되어 주어진 소스의 스키마 정보를 사용하여 프로젝트에서 Ampli Wrapper를 생성하고 확인합니다.

Ampli CLI 설치

brew tap amplitude/ampli
brew install ampli

Ampli 래퍼 생성

ampli pull을 실행하면 Amplitude 데이터에 연결되어 추적 플랜에 맞는 Ampli Wrapper를 다운로드합니다.

shell
ampli pull [source-name] [--path ./path/for/generated/ampli/wrapper]

Ampli Wrapper는 Amplitude 데이터의 특정 소스에 연결됩니다. 소스 이름을 매개변수로 제공할 수도 있습니다(선택적). 그렇지 않은 경우 Ampli는 이를 선택하라는 메시지를 표시합니다.

shell
? Select a Source: web

소스에서 ampli pull을 처음 실행할 때, Ampli는 개발 언어와 기본 Amplitude SDK를 선택하라는 메시지를 표시합니다. 나중에 소스 구성을 변경하려면 ampli configure를 실행하여 다른 플랫폼, 언어 또는 Amplitude SDK를 선택하십시오.

shell
? Select a platform: Browser
? Select a language: TypeScript
? Select a SDK: @amplitude/analytics-browser@^1.0 (recommended)

그런 다음 Ampli는 생성된 Ampli Wrapper를 제공된 경로에서 사용할 수 있게 합니다. 경로를 제공하지 않을 경우 Ampli CLI는 소스의 플랫폼에 따라 기본값을 선택합니다.

shell
✔ Tracking library generated successfully.
  ↳ Path: ./ampli

이벤트 계측 확인

ampli status를 실행하면 프로젝트 디렉토리의 소스 코드를 검사하고 ampli.songPlayed({ ... })와 같은 이벤트 트래킹 호출이 있는지 확인합니다. 각 이벤트를 감지한 횟수를 출력합니다.

shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
✔ All events tracked: 1 found, 1 total

추적 계획에 프로젝트에서 구현하지 않는 이벤트가 포함되어 있는 경우 ampli status에서는 오류를 반환합니다. 예를 들어, 이 문제는 새 이벤트인 Song Favorited를 추적 계획에 추가했지만 프로젝트에 이를 계측하지 않을 때 발생합니다.

shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
  ✘ Song Favorited
✘ ERROR Event tracking incomplete: 1 missed, 2 total

Ampli 래퍼

추적 계획을 위해 생성된 SDK

Ampli Wrapper는 Amplitude SDK를 기반으로 하는 얇은 패사드로, 추적 계획의 모든 이벤트에 대해 편리한 메서드(예: ampli.songPlayed())와 클래스(예: new SongPlayed())를 제공합니다.

typescript
import { ampli, SongPlayed } from "./ampli";
ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
ampli.client.setUserId("ampli@amplitude.com");
ampli.songPlayed({ title: "Happy Birthday" });
ampli.track(new SongPlayed({ title: "Song 2" }));
ampli.flush();

Amplitude SDK 래핑

Ampli Wrapper는 ampli.client를 통해 기본 Amplitude SDK 인스턴스의 모든 메소드에 대한 액세스를 제공합니다. 인스턴스를 직접 구성하거나 기존 인스턴스를 제공할 수 있습니다. 이를 제공하지 않을 경우, Ampli는 기본 Amplitude SDK 인스턴스를 사용합니다.

typescript
import * as amplitude from "@amplitude/analytics-browser";
import { ampli } from "./ampli";
import { CustomPlugin } from "./plugins";
// Initialize the Amplitude SDK instance
amplitude.init(AMPLITUDE_API_KEY);
// Provide the Amplitude SDK instance to Ampli
ampli.load({ client: { instance: amplitude } });
assertEqual(ampli.client, amplitude);
// Call methods directly on the Amplitude SDK
ampli.client.add(CustomPlugin);
ampli.client.setUserId("ampli@amplitude.com");
ampli.client.setGroup("team", "awesome");

직접 생성하지 않고 기본 Amplitude SDK 인스턴스를 구성하려면 client.configuration을 ampli.load()에 제공하십시오. Ampli는 기본 Amplitude SDK에 대한 모든 구성 옵션을 지원합니다.

typescript
ampli.load({
  client: { apiKey: AMPLITUDE_API_KEY, configuration: { serverZone: "EU" } },
});

Ampli Wrapper를 프로젝트에 추가하고 이벤트를 추적하십시오

Ampli CLI를 사용하여 Ampli Wrapper를 다운로드하십시오.

shell
ampli pull [--path ./ampli]

path 및 ampli.json에 있는 다운로드한 소스 코드를 귀하의 저장소 및 소스 제어에 추가하십시오.

shell
git add ./ampli ampli.json
git commit -m "Added Ampli wrapper"

소스에 대해 선택한 Amplitude SDK에 따라 해당 종속성을 설치하십시오.

shell
npm install @amplitude/analytics-browser

ampli pull가 포함된 Ampli Wrapper를 다운로드하고 종속성을 설치한 후, 이를 사용하여 코드의 이벤트를 추적하십시오.

typescript
import { ampli, SongPlayed } from "./ampli";
ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
ampli.songPlayed({ title: "Happy Birthday" });
ampli.flush();

Ampli CLI를 사용하여 프로젝트에서 Ampli Wrapper의 계측 상태를 확인하십시오.

shell
ampli status

이 내용이 도움이 되었나요?

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

이 페이지에서