브라우저 SDK (sdk-web)

@edgelinkapp/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>

커스텀 이벤트

<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시간).

허용 Origin 설정

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

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

• live 모드 키는 허용 Origin을 1개 이상 등록해야 발급되고, 허용 Origin이 비어 있는 live 키의 요청은 거부됩니다. 키가 노출되더라도 등록하지 않은 사이트에서는 이벤트를 보낼 수 없습니다.
• *, https://*.com, 스킴이 없는 값(myshop.com), 경로가 붙은 값(https://myshop.com/shop)은 등록할 수 없습니다.
• localhost / 127.0.0.1 / *.local은 test 모드 키에서 자동 허용되므로, test 모드 키는 허용 Origin을 비워 둘 수 있습니다.

다음 단계