Edgelink
Docs전환 추적브라우저 SDK (sdk-web)

브라우저 SDK (sdk-web)

브라우저에서 회원가입·리드·커스텀 전환 이벤트를 전송하는 @edgelink/sdk-web 사용법

브라우저 SDK (@edgelink/sdk-web)

@edgelink/sdk-web은 고객 사이트의 브라우저에서 회원가입·리드·커스텀 이벤트를 Edgelink로 전송하는 5KB(gzip) 미만의 경량 SDK입니다.

설치

CDN 스크립트 태그가 표준 설치 방식입니다. 별도 npm 설치는 필요하지 않습니다.

<script
  async
  src="https://cdn.edgelink.me/sdk/v1/edgelink.iife.js"
  data-publishable-key="pk_live_xxxxxxxxxxxx"
></script>

data-publishable-key 속성에 발급받은 publishable 키(pk_live_* 또는 pk_test_*)를 넣습니다. live와 test를 분리해 발급받아 스테이징·프로덕션에서 각각 사용하세요.

주요 동작

스크립트가 로드되면 SDK는 자동으로 다음 작업을 수행합니다:

  1. URL의 ?el_cid= 파라미터를 감지하여 _el_cid 쿠키에 저장 (90일, SameSite=Lax)
  2. GPC/DNT 신호 감지 — 신호가 있으면 모든 이벤트를 no-op 처리
  3. window.edgelink 함수 노출 — 스니펫보다 먼저 호출된 큐(stub)는 자동 drain

이벤트 전송

회원가입 추적

<script>
  edgelink('track', 'signup', {
    externalUserId: 'user-1234',
    customerEmailHash: 'hashed-email-or-null',
  })
</script>
필드타입설명
이벤트명string자유 식별자. 예: signup, subscribe
externalUserIdstring?고객사 측 user ID — 후속 이벤트와 동일 사용자 매칭에 사용
customerEmailHashstring?이메일 SHA-256 해시(lowercase) — 평문 금지
externalEventIdstring?멱등키 — 동일 키 재전송 시 중복 저장 안 됨

커스텀 이벤트

<script>
  edgelink('track', 'video-completed', { videoId: 'intro-2026' })
</script>

metadata는 자동 분리되어 저장됩니다. 8KB를 초과하면 거부됩니다.

사용자 식별 (identify)

회원가입 직후 클릭과 사용자를 묶어 두면, 사용자가 다른 기기로 로그인해도 매칭이 유지됩니다(후속 spec).

<script>
  edgelink('identify', 'user-1234', { plan: 'pro' })
</script>

에러 처리

SDK는 4xx 응답을 즉시 폐기하고 console에 경고만 표시합니다. 5xx·network 에러는 localStorage 큐로 백오프 재시도합니다(최대 24시간).

응답동작
200정상 처리
400 INVALID_PAYLOAD즉시 폐기 + console.warn
401 INVALID_KEY즉시 폐기 + console.error
401 ORIGIN_NOT_ALLOWED즉시 폐기 + console.error (allowedOrigins 점검 필요)
403 CONVERSION_TRACKING_NOT_ENABLED즉시 폐기 + console.error (Pro 플랜 활성 필요)
410 CLICK_EXPIRED즉시 폐기
429 RATE_LIMITEDRetry-After 헤더 존중하여 재큐잉
5xx지수 백오프 재시도

허용 Origin 설정

publishable 키 발급 시 허용 Origin 목록을 설정합니다. Origin 헤더가 일치하지 않으면 ORIGIN_NOT_ALLOWED 에러로 거부됩니다.

https://myshop.com
https://*.myshop.com   (단일 서브도메인)

localhost / 127.0.0.1 / *.local은 test 모드 키에서 자동 허용됩니다.

다음 단계