JavaScript SDK 가이드

SolapiCRM.init({
trackingKey: 'tk_live_xxxxxxxxxxxxxxxx',
entityId: 'CRMRC1_contacts',
autoPageView: true
});

<h3>NPM 방식npmyarnpnpm

yarn add @solapi/crm-browser

pnpm add @solapi/crm-browser

import SolapiCRM from '@solapi/crm-browser';
SolapiCRM.init({
  trackingKey: 'tk_live_xxxxxxxxxxxxxxxx',
  entityId: 'CRMRC1_contacts',
  autoPageView: true
});

<h3>전체 설정 예시

// 권장: 기본 개체 ID
entityId: 'CRMRC1_contacts',

// 선택: 페이지뷰 자동 추적
autoPageView: true,

// 선택: 배치 설정
batchSize: 20,
flushInterval: 5000,
maxQueueSize: 200,

// 선택: 디버그 모드 (개발 환경에서만)
debug: process.env.NODE_ENV === 'development'
});

3. 이벤트 추적 — track(eventType, properties?, options?)사용자 행동을 추적하여 CRM 레코드에 연결합니다. 이벤트는 큐에 저장되었다가 배치로 전송됩니다.

<h3>기본 이벤트 추적

// 버튼 클릭 이벤트
document.getElementById('cta-button').addEventListener('click', () => {
SolapiCRM.track('BUTTON_CLICK', {
buttonId: 'cta-button',
buttonText: '무료로 시작하기',
page: window.location.pathname
});
});

<h3>속성과 함께 추적

<h3>특정 레코드에 연결

<h3>배치 처리 동작이벤트는 다음 조건 중 하나가 충족될 때 서버로 전송됩니다:</h3>
큐 크기: batchSize에 도달하면 자동 전송 (기본값: 10개)

시간 간격: flushInterval 시간이 지나면 전송 (기본값: 10초)

탭 닫기: 브라우저 탭이 닫히거나 페이지를 떠날 때 visibilitychange 이벤트로 자동 전송

재시도: 네트워크 오류 시 최대 3회까지 재시도 (지수 백오프)
큐 오버플로: maxQueueSize를 초과하면 가장 오래된 이벤트부터 삭제

이벤트가 큐에 저장되므로 즉시 서버에 전송되지 않습니다. 실시간 처리가 필요한 경우 SolapiCRM.flush()를 호출하여 강제로 전송하세요.
<h2>4. 페이지뷰 추적 — trackPageView()### 수동 페이지뷰 추적

// React Router 예시
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
const location = useLocation();

useEffect(() => {
SolapiCRM.trackPageView();
}, [location]);

return ...;
}

<h3>자동 페이지뷰 추적 (권장)autoPageView: true로 초기화하면 SDK가 자동으로 페이지뷰를 추적합니다. SPA 프레임워크(React, Vue, Angular)에서도 별도 코드 없이 모든 라우팅이 자동 추적됩니다.</h3>
자동 감지 이벤트:
history.pushState: React Router, Vue Router 등의 라우팅

history.replaceState: URL 변경 없이 상태만 변경하는 경우

popstate: 브라우저 뒤로 가기/앞으로 가기


<h3>자동 수집 속성

<h2>5. 전환 추적 — 표준 이벤트 프리셋자주 사용되는 이벤트를 표준화된 메서드로 간편하게 추적할 수 있습니다. 프리셋 메서드는 내부적으로 track()을 호출하며, 적절한 카테고리·레이블·값이 자동 설정됩니다.</h2>
<h3>일반 전환 이벤트

// 로그인 추적 (LOGIN)
SolapiCRM.trackLogin({
method: 'kakao' // 필수: 로그인 방식
});

// 폼 제출 추적 (FORM_SUBMIT)
SolapiCRM.trackFormSubmit({
formId: 'contact-form', // 필수: 폼 ID
formName: '문의하기' // 선택: 폼 이름 (레이블로 사용)
});

<h3>이커머스 전환 이벤트

// 장바구니 추가 (CART_ADD)
SolapiCRM.trackAddToCart({
productId: 'PROD_001', // 필수
name: '프리미엄 요금제', // 필수
quantity: 1, // 선택 (기본: 1)
price: 79000 // 선택 (value = price × quantity)
});

// 결제 시작 (CHECKOUT_START)
SolapiCRM.trackCheckoutStart({
totalAmount: 79000, // 필수 (value로 사용)
itemCount: 1, // 필수
cartId: 'CART_001', // 선택
currency: 'KRW' // 선택
});

// 구매 완료 (PURCHASE)
SolapiCRM.trackPurchase({
orderId: 'ORD_001', // 필수
totalAmount: 79000, // 필수 (value로 사용)
items: [{ // 선택
productId: 'PROD_001',
name: '프리미엄 요금제',
quantity: 1,
price: 79000
}],
currency: 'KRW' // 선택
});

// 환불 (REFUND)
SolapiCRM.trackRefund({
orderId: 'ORD_001', // 필수
refundAmount: 79000 // 필수 (value로 사용)
});

<h3>퍼널 분석 예시프리셋 이벤트를 조합하여 전환 퍼널을 구성할 수 있습니다:</h3>

6. 사용자 식별 — identify(recordId, traits?)로그인한 사용자를 CRM 레코드에 연결합니다. 익명 사용자의 이벤트를 알려진 레코드로 병합하는 핵심 기능입니다.

// 이후 이벤트는 자동으로 이 레코드에 연결됨
SolapiCRM.track('VIEW_DASHBOARD');

<h3>속성과 함께 식별

<h3>익명 사용자 → 알려진 사용자 전환 흐름- 첫 방문 (익명 상태): SDK가 자동으로 익명 ID를 생성합니다 (anon_1234567890abcdef)</h3>
익명 이벤트 수집: 로그인 전 이벤트는 익명 ID로 추적됩니다
사용자 로그인: identify()를 호출하여 레코드 ID와 연결합니다

서버 측 이벤트 병합: 서버가 자동으로 익명 ID의 모든 이벤트를 알려진 레코드로 병합합니다
이후 이벤트: 모든 이벤트가 알려진 레코드에 직접 연결됩니다
익명 ID는 로컬스토리지에 저장되어 브라우저를 닫아도 유지됩니다. 사용자가 로그인하지 않아도 여러 세션에 걸쳐 행동을 추적할 수 있습니다.
<h2>7. 레코드 생성 — createRecord(data)클라이언트에서 직접 새로운 CRM 레코드를 생성할 수 있습니다.</h2>
<h3>파라미터

// 이후 모든 track()에 자동 포함됨
SolapiCRM.track('VIEW_PAGE');
// → properties: { plan: 'premium', region: 'ko-KR', appVersion: '2.1.0' }

<h3>registerOnce(properties) — 한 번만 등록이미 존재하는 속성은 덮어쓰지 않습니다. 첫 방문 시점의 정보를 보존하는 데 유용합니다.</h3>

<h3>unregister(propertyName) — 속성 제거

<h2>9. 프라이버시 제어GDPR, CCPA 등의 개인정보 보호 규정을 준수하기 위한 추적 거부 기능을 제공합니다.</h2>

// 추적 허용 (다시 활성화)
SolapiCRM.optInTracking();

// 추적 거부 상태 확인
if (SolapiCRM.hasOptedOut()) {
console.log('사용자가 추적을 거부했습니다.');
}

10. 세션 관리### reset() — 세션 초기화새로운 익명 ID를 생성하고 모든 슈퍼 프로퍼티를 초기화합니다. 로그아웃 시 사용하세요.

function handleLogout() {
  SolapiCRM.reset();
  window.location.href = '/login';
}

flush() — 이벤트 즉시 전송큐에 있는 모든 이벤트를 즉시 서버로 전송합니다.

// 구매 완료 후 즉시 전송
SolapiCRM.track('PURCHASE', { orderId: 'ORD_123', amount: 159000 });
await SolapiCRM.flush();
window.location.href = '/order-complete';

destroy() — SDK 완전 정리SDK를 완전히 정리합니다. 이벤트 전송, 타이머 정지, History API 복원, 이벤트 리스너 제거 등 모든 작업을 수행합니다.

await SolapiCRM.destroy();

// 콘솔 출력 예시:
// [SolapiCRM] Initialized with trackingKey: tk_test_
// [SolapiCRM] Track event: BUTTON_CLICK
// [SolapiCRM] Flushing 1 events...
// [SolapiCRM] Events sent successfully