Amplitude WEB 개발 가이드

데이터 전송 프로세스

Amplitude에서의 데이터 전송 프로세스는 Native/Hybrid 영역은 각각의 SDK 탑재를 통해 진행합니다.

Hybrid 영역은 앱/웹 분기처리하지 않으며, 모든 플랫폼에 SDK를 탑재합니다.

Native·Webview 식별 정보 전달 및 Amplitude·Braze 연동 프로세스 — Native 영역의 session / device / user ID가 Webview로 전달되고, 서버를 거쳐 Amplitude·Braze로 연동되는 흐름

i

하이브리드 앱 주의

네이티브 SDK와 WEB SDK를 WebView에 동시에 탑재하면 동일 사용자가 중복 집계될 수 있습니다. WebView에서는 네이티브에서 전달한 ID로 WEB SDK만 초기화하는 패턴으로 구성되도록 개발되어야 합니다.

SDK 설치

기본적으로 SDK 설치는 다양한 방식으로 설치 가능합니다.

대시보드에서 API Key 확인

Amplitude Data → Sources → 연동 플랫폼(WEB / Android / iOS 등) Source를 선택하면 Source Settings에서 API Key를 확인할 수 있습니다.

Amplitude Source Settings — WEB Platform 및 API Key 확인 화면 — Source Settings — Platform(WEB) · API Key 확인 · Setup Instructions(설치·초기화 코드 참고)

SDK 최신 설치 링크: analytics-browser — Script Loader

CDN 연동 방식

모든 페이지에 호출되도록 <head>에 설정합니다.

CDN 연동 방식을 통해 Amplitude SDK 연동을 활성화합니다.
Amplitude 연동 진행 시 API_Key를 설정합니다. (Amplitude 대시보드에 발급되는 고유 키)

<head>
  <script src="https://cdn.amplitude.com/libs/analytics-browser-2.39.2-min.js.gz"></script>
  <script>
    amplitude.init(AMPLITUDE_API_KEY, undefined, {
      autocapture: {
        attribution: true,
        pageViews: false,
        sessions: true,
        formInteractions: false,
        fileDownloads: false,
        elementInteractions: false,
        pageUrlEnrichment: false,
        webVitals: false
      }
    });
  </script>
</head>

CDN 연동 방식의 script src SDK 라이브러리 (<script src="https://cdn.amplitude.com/libs/analytics-browser-2.39.2-min.js.gz"></script>) 는 현재 페이지에 표기된 기본값입니다. 실제 연동 시에는 위 SDK 최신 설치 링크를 확인하시어 버전을 반영해 주세요.

i

설치 직후

스크립트 로드 후 초기 설정 섹션의 옵션을 프로젝트 정책에 맞게 조정하세요.

초기 설정

amplitude.init() 호출 시 두 번째 인자에 userId(선택), 세 번째 인자에 설정 객체를 전달합니다. 이벤트를 보내기 전에 반드시 초기화가 완료되어야 하며, 사용자 ID·페이지 URL 등 필요한 값이 준비된 시점에 호출하는 것이 좋습니다.

공식 — Initialize 공식 — Configure 공식 — Autocapture

i

고객사 이해 포인트

amplitude.init(API_KEY, userId, options) 형태로 호출하며, 이벤트 전송 전 반드시 초기화합니다. Browser SDK 2는 HTTP V2 API를 사용하며, userId 또는 deviceId 중 하나는 필수(기본 최소 5자, minIdLength로 변경 가능)입니다.

1. 전송·배치 (Batching)

SDK는 메모리에 이벤트를 쌓았다가 배치로 전송합니다. 대량 전송 시 useBatch: true와 Batch API를 검토하세요.

옵션	설명	기본값
`flushIntervalMillis`	미전송 이벤트 업로드 주기(ms)	`1000`
`flushQueueSize`	한 번에 전송할 최대 이벤트 수	`30`
`flushMaxRetries`	전송 실패 시 재시도	`5`
`useBatch`	Batch API 사용	`false`

Batch URL: https://api2.amplitude.com/batch · EU: https://api.eu.amplitude.com/batch

2. 식별·세션

옵션	설명	기본값
`minIdLength`	userId·deviceId 최소 길이	`5`
`sessionTimeout`	세션 만료(ms)	`1800000`
`identityStorage`	`cookie` / `localStorage` / `none`	`cookie`
`instanceName`	다중 인스턴스 이름	default
`optOut`	전체 추적 중단	`false`

3. Autocapture

옵션	수집 내용	가이드 권장
`attribution`	UTM, referrer	`true`
`pageViews`	페이지뷰 자동 수집	`false`
`sessions`	세션	`true`
`formInteractions`	폼	`false`
`fileDownloads`	다운로드	`false`
`elementInteractions`	클릭·요소	`false`
`pageUrlEnrichment`	URL 보강	`false`
`webVitals`	LCP, CLS, FCP 등	`false`

!

자주 하는 실수

init 전 track 호출 · userId 5자 미만 · 하이브리드 이중 초기화

USER ID

Amplitude에 연동하면 SDK 연동 시 device ID가 자동 생성됩니다.
로그인 시점에는 User ID를 설정합니다.
로그인 전·후 시점에 따라 Amplitude 데이터는 머지됩니다.

중요: 로그인 전/후 시점은 고객 서비스 내 자동/간편/통합 로그인 및 회원가입 등 모든 로그인 식별자 정보가 생성되는 시점에 setUserId가 호출되도록 구성해 주세요.

중요: 일반적으로 로그인 식별자는 고객사 내부 보안 정책에 따라 운영되며, 국내 보안 정책상 일방향 암호화 방식으로 적재하는 것을 권장합니다.

사용자 식별

amplitude.setUserId('USER_ID');

Event

Amplitude SDK를 통해 전송되는 이벤트는 이벤트명과 이벤트 속성으로 구성됩니다.
이벤트 속성은 Object 형태로 전달합니다.
이벤트명·속성명은 사전 정의한 Taxonomy와 동일하게 유지하세요 (대소문자·스네이크 케이스 통일).

전송 직후 버퍼를 비우려면 amplitude.flush()를 호출합니다. 일반적으로 SDK가 배치로 자동 전송합니다.

아래 코드는 샘플 코드이며, 실제 코드는 텍소노미 기획 문서를 통해 설정된 값으로 구성해 주세요.

amplitude.track("이벤트명");

var eventProperties = {
  "이벤트 속성명": "값",              // String 타입 속성
  "이벤트 속성명": false,             // Boolean 타입 속성
  "이벤트 속성명": 42,                // Number 타입 속성
  "이벤트 속성명": new Date(),        // Date 타입 속성
  "이벤트 속성명": ["any", "array", "here"]  // Array 타입 속성
};

amplitude.track("이벤트명", eventProperties);
amplitude.flush();

User Property

Amplitude SDK를 통해 전송되는 사용자 단위 속성을 User Property라고 합니다.
identify API와 Identify 객체를 통해 User Property를 설정합니다.
Identify 연산은 set, setOnce, add, append, unset, preInsert, postInsert, remove 등 여러 기능을 제공하며, 일반적으로 set이 가장 많이 활용됩니다.

아래 코드는 샘플 코드이며, 실제 코드는 텍소노미 기획 문서를 통해 설정된 값으로 구성해 주세요.

Identify 타입 — set (가장 많이 사용)

var identify1 = new amplitude.Identify().set('설정할 사용자 속성명(String)', '저장할 사용자 속성 값');
amplitude.identify(identify1);

Identify 타입 — setOnce

var identify = new amplitude.Identify().setOnce("설정할 사용자 속성명(String)", "저장할 사용자 속성 값");
// setOnce는 최초 1회만 반영됩니다.
amplitude.identify(identify);

Identify 타입 — add

var identify = new amplitude.Identify().add("설정할 사용자 속성명(Number)", 숫자값);
// 속성 값에 숫자를 더합니다.
amplitude.identify(identify);

Ecommerce Data

Amplitude SDK를 통해 매출·구매(Revenue)와 장바구니·상품 데이터(Cart object array)를 전송할 수 있습니다. Cart Analysis 차트 활용을 위해 object array 전송과 amplitude.Revenue()를 함께 사용하는 것을 권장합니다. (공식 — Send the cart object array)

Cart object array 전송

products와 같이 상품 목록을 담는 object array를 User Property 또는 Event Property로 전송합니다. 수집 후 Amplitude Data에서 해당 속성의 Property splitting(Type: Array, Item type: Any)을 활성화해야 Cart Analysis에서 분석할 수 있습니다.

① Identify API — set() / append()

const identifyEvent = new amplitude.Identify();

// set() 또는 append() 사용
identifyEvent.append("products", [
  {
    product_id: 123,
    sku: "41245",
    name: "Sunscreen",
    category: "beauty",
    price: 12.6
  }
]);

amplitude.identify(identifyEvent);

② Event Property — track

const myCartObjectArray = {
  products: [
    {
      product_id: 123,
      sku: "41245",
      name: "Sunscreen",
      category: "beauty",
      price: 12.6
    }
  ]
};

amplitude.track("Product Viewed", myCartObjectArray);

Revenue 전송

구매 이벤트 속성 (옵션)

속성	설명
`revenueType`	매출 유형 (예: 구매, 환불, 취소 등)
`receipt`	영수증
`receiptSignature`	영수증 서명
`eventProperties`	구매 이벤트 속성 (예: 상품명, 가격, 수량, 통화 등)

var revenue = new amplitude.Revenue()
  .setProductId("설정할 상품 ID")
  .setPrice(3000)           // 가격
  .setQuantity(3)           // 수량
  .setRevenueType('purchase');

amplitude.revenue(revenue);

UTM 집계 & 예외 처리

Amplitude WEB SDK의 Attribution autocapture는 SDK 초기화 시점에 UTM·referrer 정보를 아래 순서로 판단합니다. 아래 흐름은 개발 반영 전 검토용이며, 고객사 유입 경로·세션 규칙과 맞는지 확인한 뒤 필요 시 excludeReferrers 등 예외 옵션을 설정합니다.

UTM · Referrer 집계 판단 흐름

SDK initialization 기준 · ① → ② → ③ 순서로 확인

SDK 초기화

단계	확인 조건	「예」일 때	「아니오」일 때
①	referrer 도메인이 `excludeReferrers` 제외 목록에 포함되나요?	UTM & Referrer 미집계	② 단계로 이동
②	동일 세션 내 Direct Traffic(직접 유입)인가요?	UTM & Referrer 미집계	③ 단계로 이동
③	현재 캠페인이 이전 캠페인과 동일한가요?	UTM & Referrer 미집계	UTM & Referrer 집계

미집계 — 위 조건 중 하나라도 「예」 집계 — ①·②·③ 모두 「아니오」

i

읽는 방법

①→②→③ 순서로 확인합니다. 각 단계에서 「예」이면 UTM & Referrer가 미집계되고, 모든 단계가 「아니오」일 때만 UTM & Referrer가 집계됩니다.

검토 체크리스트

내부·제휴 referrer(예: 카카오, 자사 도메인)가 UTM & Referrer를 중복 집계하지 않는지
Direct Traffic 구간에서 의도치 않게 UTM & Referrer가 바뀌지 않는지
동일 캠페인 재방문 시 UTM & Referrer가 불필요하게 재집계되지 않는지
Amplitude 기본 WEB 유입 규칙과 고객사 마케팅·유입 정의가 일치하는지

!

예외 설정 참고

검토 결과 referrer 예외가 필요하면 excludeReferrers, 내부 referrer 조건은 excludeInternalReferrers 옵션을 사용합니다.

설정 예시

<head>
  <script src="https://cdn.amplitude.com/libs/analytics-browser-2.18.0-min.js.gz"></script>
  <script>
    var options = {};
    amplitude.init(AMPLITUDE_API_KEY, {
      autocapture: {
        attribution: {
          excludeInternalReferrers: { condition: "ifEmptyCampaign" },
          excludeReferrers: [
            "katuh.kakao.com"  // 예: 카카오 유입 경로 제외
          ]
        },
        pageViews: false,
        sessions: false,
        formInteractions: false,
        fileDownloads: false,
        elementInteractions: false,
        pageUrlEnrichment: false,
        webVitals: false
      },
      options
    });
  </script>
</head>

하이브리드

하이브리드 앱 환경에서는 네이티브와 WEB SDK 연동 방식을 분기합니다. WebView에서는 네이티브에서 전달받은 deviceId, sessionId, userId를 사용해 WEB SDK를 초기화하는 패턴을 사용합니다.

SDK 활성화 전 — 플러그인 설치

amplitude.init() 호출 이전에 enrichment 플러그인을 등록합니다.

(function () {
  function getPlatform() {
    var ua = navigator.userAgent || "";
    if (/MaxonomyAndroid/i.test(ua)) return "android";
    if (/MaxonomyiOS/i.test(ua)) return "ios";
    return "web";
  }

  function applyPlatform(userProperties) {
    var props = userProperties || {};
    props.platform = getPlatform();
    return props;
  }

  var enrichPageUrlPlugin = {
    name: "enrich-page-url-and-platform",
    type: "enrichment",
    execute: function (event) {
      var platform = getPlatform();

      if (event.event_type === "$identify") {
        event.user_properties = applyPlatform(event.user_properties);
      }

      return event;
    },
  };
})();

플러그인 정의 후 amplitude.add(enrichPageUrlPlugin)을 호출한 뒤 init을 실행합니다.

WebView — SDK 초기화

try {
  if (userAgent.indexOf('MaxonomyAndroid') > -1 || userAgent.indexOf('MaxonomyiOS') > -1) {
    amplitude.init("API_KEY", {
      deviceId: UserAgent에_담긴_deviceID,
      sessionId: UserAgent에_담긴_sessionID,
      userId: UserAgent에_담긴_userID
    });
  }
} catch (e) {
  console.log("Hybrid Errror : " + e);
}

최종 반영 예시 코드

아래는 연동 완료 시 실제 서비스에 반영되어야 하는 예시 코드 패턴입니다.

SDK 초기화(Initialize)뿐 아니라 User Property·Event 태깅 예시를 함께 정리했습니다.

Initialize 예시 — PC & Mobile WEB

<head>
  <script src="https://cdn.amplitude.com/libs/analytics-browser-2.39.2-min.js.gz"></script>
  <script>
    amplitude.init(AMPLITUDE_API_KEY, {
      autocapture: {
        attribution: {
          excludeInternalReferrers: { condition: "ifEmptyCampaign" },
          excludeReferrers: ["katuh.kakao.com"]
        },
        pageViews: false,
        sessions: false,
        formInteractions: false,
        fileDownloads: false,
        elementInteractions: false,
        pageUrlEnrichment: false,
        webVitals: false
      }
    });
    amplitude.setUserId("사용자 ID");
  </script>
</head>

Initialize 예시 — Webview (하이브리드)

중요: 플러그인은 amplitude.init() 전에 등록해야 합니다. (하이브리드 섹션 참고)

<head>
  <script src="https://cdn.amplitude.com/libs/analytics-browser-2.39.2-min.js.gz"></script>
</head>
<body>
  <script>
    // [중요] 플러그인은 init 전에 등록 (하이브리드 섹션 참고)
    try {
      if (userAgent.indexOf('MaxonomyAndroid') > -1 || userAgent.indexOf('MaxonomyiOS') > -1) {
        amplitude.init("API_KEY", {
          deviceId: UserAgent에_담긴_deviceID,
          sessionId: UserAgent에_담긴_sessionID,
          userId: UserAgent에_담긴_userID,
          autocapture: false
        });
      }
    } catch (e) {
      console.log("Hybrid Errror : " + e);
    }
  </script>
</body>

User Property · Event 태깅

중요: 이벤트명·속성명·User Property 키/값은 텍소노미 기획 문서에 정의된 명세로 교체하여 적용해 주세요. (아래는 구조 참고용 예시입니다.)

Amplitude는 Event 기반으로 차트가 구성되기 때문에 User Property만 호출하면 대시보드에 반영되지 않고 Amplitude 대시보드 서버에 머무르며, 이후 이벤트 전송 시 업데이트되는 구조입니다.

이에 따라 최신 User Property 반영을 원하실 경우 Event track 이전에 User Property가 호출되도록 구조 설정이 필요합니다.

// 1. User Property — set (가장 많이 사용)
var identify = new amplitude.Identify()
  .set('membership_level', 'gold')
  .set('country_code', 'KR');
amplitude.identify(identify);

// 2. Event track
amplitude.track('login_completed', {
  login_method: 'kakao',      // 예: kakao, naver, email
  is_first_login: false
});

// 필요 시 즉시 전송
amplitude.flush();

추가 설정 항목

Amplitude에 한 번 연동된 이후, SDK 또는 API를 통해 추가 설정을 적용할 수 있습니다.

Amplitude SDK에서 연동 이후에도 옵션·이벤트 값을 변경·추가할 수 있습니다.

Device ID / Session ID

amplitude.setDeviceId("내부 DB에 저장된 고유 ID");
// Braze를 사용하는 고객사라면 크로스 분석을 위해 braze.getDeviceId()로 설정하는 것을 권장드립니다.

amplitude.getDeviceId();
amplitude.getSessionId();

페이지 이탈 시 전송

window.addEventListener('pagehide', () => {
  amplitude.setTransport('beacon');
  amplitude.flush();
});

이벤트 즉시 전송

amplitude.flush();

이벤트 전송 결과 확인

amplitude.track('이벤트명').promise.then(function (result) {
  result.event;    // Amplitude로 전송된 이벤트 object
  result.code;     // 200 (http request 상태 코드)
  result.message;  // "Event tracked successfully" 등
});

API 연동 간 세션 유지 방안

API 전송 이벤트에는 SDK session_id가 없습니다. 임의 값·빈 값으로 내면 같은 방문도 세션이 끊긴 것처럼 집계됩니다. 아래 두 방안 중 환경에 맞는 방식을 선택하세요. (HTTP API 스펙은 상단 API 탭 참고)

방안 1 — SDK Session ID를 API에 전달

Browser SDK Session ID → 내부 서버 → API body session_id

중요: session_id 값은 반드시 amplitude.getSessionId() 결과를 사용하세요. (임의 값·빈 값 금지)

SDK (브라우저)

// session_id 조회 후 내부 서버로 전달
var sessionId = amplitude.getSessionId();

API 전문 예시

{
  "api_key": "YOUR_API_KEY",
  "events": [{
    "session_id": 1716245958483,
    "user_id": "user_12345",
    "event_type": "server_side_event",
    "user_properties": {
      "source": "backend"
    },
    "time": 1396381378123
  }]
}

방안 2 — 고객사 Session ID를 Event Property로 전달

방안 1이 개발 구조와 맞지 않거나, 고객사가 직접 관리하는 세션 ID가 있을 때
SessionID 등 동일 속성을 SDK·API 모든 이벤트에 포함

중요: SDK track과 API event_properties에 같은 키·값을 넣어, 모든 이벤트에 전송하세요.

SDK 작업 사항

var eventProperties = {
  "SessionID": "backend_session_id_value"
};
amplitude.track("이벤트명", eventProperties);

API 전문 예시

기존 API 전문의 events[]에 event_properties를 추가합니다.

{
  "api_key": "YOUR_API_KEY",
  "events": [{
    "user_id": "user_12345",
    "event_type": "server_side_event",
    "time": 1396381378123,
    "event_properties": {
      "SessionID": "backend_session_id_value"
    }
  }]
}

Session Replay

Amplitude에서는 최근 최신 기능인 Session Replay 기능을 제공합니다.

Session Replay는 세션 동안 사용자가 발생시킨 이벤트를 기반으로, 대시보드에서 고객사 페이지에서의 행동을 재생해 보여줍니다.
Session Replay를 사용하려면 대시보드에서 기능을 활성화한 뒤, 아래와 같은 SDK 연동 코드가 탑재되어야 합니다.

!

Session Replay는 무료로 10,000 session까지 트래킹됩니다. 상향 트래픽이 필요하신 경우 세일즈 담당자를 통해 문의해 주세요.

Amplitude 대시보드 → Settings → Session Replay & Heatmap 경로에서 기능 활성화가 가능합니다.

<script src="https://cdn.amplitude.com/libs/plugin-session-replay-browser-1.19.3-min.js.gz"></script>
<script>
  var sessionReplayTracking = window.sessionReplay.plugin({
    sampleRate: 0.002  // 예: 샘플링 0.2%
  });
  window.amplitude.add(sessionReplayTracking);
</script>

연동 체크리스트

배포 전 아래 항목을 확인하세요. (데이터 검수 화면은 대시보드 Live View·User Lookup을 직접 사용합니다.)

프로젝트 API Key가 운영/개발 환경별로 분리되어 있는가
init이 페이지 로드 후 1회만 호출되는가
로그인 시 setUserId 및 필요 시 identify가 호출되는가
Taxonomy(이벤트·속성명)와 코드의 track 이름이 일치하는가
autocapture on/off가 기획 의도와 맞는가 (pageViews 등)
하이브리드 WebView에서 네이티브·WEB SDK 이중 수집이 없는가
UTM 집계 & 예외(excludeReferrers) 흐름을 검토·적용했는가
서버 API 사용 시 insert_id·time(ms) 형식이 올바른가 (HTTP API 가이드 참고)
API·SDK 병행 시 세션 유지 방안(API 연동 간 세션 유지)이 적용되었는가
Session Replay 사용 시 대시보드(Settings → Session Replay & Heatmap) 활성화 및 SDK 플러그인 연동이 완료되었는가