Intlayer Analytics 문서

@intlayer/analytics는 방문자에게 어떤 콘텐츠가 실제로 노출되었는지(어떤 페이지, 어떤 로케일에서, 번역된 콘텐츠 중 어떤 특정 항목이 노출되었는지)를 알려주는 선택적 보조 패키지입니다. 이를 통해 오디언스를 이해하고 콘텐츠를 대상으로 A/B 테스트를 실행할 수 있습니다.

목차

추적 대상

@intlayer/analytics는 다음 세 가지 종류의 익명 이벤트를 일괄 처리(batch)하여 수집합니다:

이벤트는 메모리에 수집되어 키 입력이나 렌더링마다 전송되지 않고 약 20초마다 한 번씩 일괄 요청(batch request)으로 전송됩니다. 따라서 분석은 첫 렌더링 시간에 영향을 주지 않으며 사용자 상호작용마다 요청을 추가하지 않습니다.

콘텐츠 A/B 테스트를 지원하는 방법

Intlayer에서는 이미 콘텐츠 변형(Variants)을 선언할 수 있습니다(예: control 및 black_friday 변형이 포함된 hero-banner 사전). @intlayer/analytics는 다음을 통해 사이클을 완성합니다:

1. getVariant(experimentKey, variants)는 결정론적(deterministically)으로 각 익명 세션을 변형에 할당합니다 — 이는 세션 ID와 실험 키의 순수 함수이므로 할당은 세션 전체에 걸쳐 안정적이며 첫 렌더링 전에 서버 왕복이 필요 없습니다(깜빡임, 레이아웃 변경 없음).
2. 모든 content_exposure 이벤트에는 화면에 표시된 variant 정보가 포함됩니다.
3. useConversion()을 사용하면 해당 변형에 목표(예: "cta_click")를 기여(attribute)시킬 수 있습니다.
4. 대시보드의 실험 결과 엔드포인트는 통계적 유의성(z-test)을 포함하여 각 변형의 전환율을 비교합니다.

설치

@intlayer/analytics는 선택적 피어 의존성(peer, optional dependency)으로, 프레임워크 패키지에 의해 자동으로 설치되지 않습니다. intlayer와 함께 설치하세요:

npm install @intlayer/analytics

패키지를 설치하지 않으면 모든 통합 지점이 아무 동작도 수행하지 않는(no-op) 상태로 해석됩니다 — 아래의 미설치 시 제로 비용을 참고하세요.

구성

Analytics는 기존 editor 구성 블록을 재사용합니다. 채워야 할 별도의 analytics 구성 스키마는 없습니다:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // Analytics 이벤트 수집 엔드포인트로도 사용됨
    clientId: "your-client-id", // Analytics 프로젝트 키로도 사용됨
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — 분석 이벤트가 전송되는 기본 URL (POST {backendURL}/api/analytics/events).
• editor.clientId — 수집되는 모든 이벤트에 기여하는 퍼블릭 프로젝트 키. 이는 활성화 스위치의 역할도 합니다: clientId가 구성될 때까지 분석 기능은 완전히 비활성화(tree-shake 됨) 상태로 유지됩니다.

직접 Intlayer를 호스팅(self-host)하는 경우, editor.backendURL을 공유하므로 분석은 자동으로 사용자 자체 인스턴스를 가리킵니다.

프레임워크 지원

Analytics는 react-intlayer의 공유된 IntlayerProvider와 연결되어 있으므로, 이 Provider가 사용되는 곳이라면 어디서든 바로 사용할 수 있습니다:

사용법

자동 프로바이더 레벨 추적

코드를 변경할 필요가 없습니다. @intlayer/analytics가 설치되고 editor.clientId가 구성되면, IntlayerProvider는 자동으로 다음을 수행합니다:

• 마운트 시 Analytics 클라이언트를 초기화,
• 초기 로드 시 page_view를 기록,
• 로케일 변경 시마다 page_view를 기록,
• 약 20초의 플러시 루프(flush loop)를 시작하고, 언마운트 / 탭 닫기 시 남은 이벤트를 플러시합니다 (navigator.sendBeacon을 사용하며, fetch(..., { keepalive: true })로 폴백).

자동 노드 레벨 추적

useIntlayer가 표시할 콘텐츠 조각을 해석할 때마다, 해석기(interpreter)는 해당 정확한 dictionaryKey + 키 경로 + 로케일에 대해 content_exposure 이벤트를 보고합니다 — 이 역시 코드를 변경할 필요가 없습니다. 플러시 창(flush window) 내에 같은 노드가 반복해서 노출되면 이벤트는 count 속성을 포함한 단일 이벤트로 병합(coalesced)되므로, 리스트가 50번 리렌더링된다고 해서 50개의 이벤트가 전송되지 않습니다.

A/B 테스트를 위한 전환(Conversion) 추적

useConversion()을 사용하여 세션이 본 변형에 목표를 연결(attribute)하세요:

클라이언트 측에서 변형 해결(Resolving a variant)

프라이버시 & 성능

• 설계상 익명(Anonymous by design): 세션은 회전하는(rotating) ID로 식별되며, 백엔드는 해당 ID의 SHA-256 해시만 저장합니다 — 원시 ID나 IP 주소는 절대 저장하지 않습니다.
• 대략적인 위치 정보: CDN 지리적 위치 헤더(cf-ipcountry, x-vercel-ip-country 등)에서 도출된 국가 코드만 포함되며 — IP를 읽거나 저장하지 않습니다.
• URL은 쿼리 매개변수 제외: 쿼리 문자열은 절대 캡처되지 않도록 기본 설정되어 있습니다.
• 샘플링: 트래픽이 높은 앱의 경우 sampleRate를 사용하여 콘텐츠 노출 이벤트의 일부만 유지할 수 있습니다.
• 일괄 처리(Batched): 약 20초마다 한 번씩 요청(flushInterval)하거나 버퍼가 가득 찼을 때(maxBufferSize) 요청을 보냅니다 — 이벤트별로 단일 요청을 보내는 일은 없습니다.

미설치 시 제로 비용

@intlayer/analytics는 @intlayer/editor와 완전히 동일한 선택적 의존성 패턴을 따릅니다:

• 모든 통합 지점은 try/catch로 래핑된 동적 import()를 통해 패키지를 로드합니다 — @intlayer/analytics를 아예 설치하지 않는 앱은 번들 크기나 런타임 비용을 지불하지 않으며, 오류가 발생하지 않습니다.
• editor.clientId가 구성되지 않은 경우 @intlayer/config에 의해 'false'로 자동 설정되는 컴파일 타임 환경 변수(INTLAYER_ANALYTICS_ENABLED)는, 번들러가 통합된 코드 전체를 데드 코드 제거(dead-code-eliminate)할 수 있게 해줍니다.
• Intlayer 에디터/CMS 미리보기 iframe 내부에서는 Analytics 기능이 비활성화되므로 에디터 세션이 실제 트래픽으로 계산되지 않습니다.

대시보드: Analytics 페이지

프로젝트에 이벤트가 수집되기 시작하면, Intlayer 대시보드의 Analytics 페이지(프로젝트 선택 후 사이드바에 표시됨)에서 다음을 확인할 수 있습니다:

• 활성 사용자(Active users) — 선택된 롤링 창(7 / 30 / 90일) 동안의 순 방문자.
• 오늘의 사용자 및 지난 7일간 사용자.
• 선택된 기간 동안의 페이지 뷰.
• 일별 순 방문자의 변화 추이 그래프.
• 로케일(Locales) 및 위치(Location) 분석 탭을 통해 로케일 및 국가별 오디언스 순위를 제공.

백엔드 API 참조

모든 읽기 엔드포인트는 인증이 필요합니다; 이벤트 수집(ingestion) 엔드포인트는 퍼블릭하며 본문의 clientId로 기여(attributed)를 수행합니다.

CMS SDK를 사용하여 프로그래밍 방식으로 호출할 수도 있습니다:

import { createIntlayerCMS } from "@intlayer/api";import { analyticsEndpoint } from "@intlayer/api/analytics";const cms = createIntlayerCMS();const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

유용한 링크

• Dynamic Dictionaries - Collections & Variants
• Intlayer CMS - CMS SDK
• Intlayer Visual Editor
• Configuration Reference
• Self-Hosting Guide