Svelte SDK

@tracio/svelte 패키지는 코어 @tracio/sdk를 감싸 관용적인 Svelte 프리미티브를 제공합니다. 한 번만 호출하는 init과, 방문자 ID 및 식별 결과를 넘겨주는 readable 스토어가 그것입니다.

설치

npm install @tracio/svelte @tracio/sdk

svelte(5)는 peer dependency이며, 앱에 이미 설치되어 있다고 가정합니다.

설정

Tracio.init({ publicKey })를 앱 루트 근처에서 한 번만 호출하세요. SvelteKit에서는 +layout.svelte에서 호출하며, 서버 사이드 렌더링 중에는 절대 실행되지 않도록 browser로 감쌉니다.

<!-- +layout.svelte -->
<script>
  import { Tracio } from "@tracio/svelte"
  import { browser } from "$app/environment"
  if (browser) Tracio.init({ publicKey: import.meta.env.VITE_TRACIO_KEY })
</script>
<slot />

스토어

TRACIO 상태는 Svelte readable 스토어로 노출됩니다. 각 스토어 값은 data, isLoading, error를 담은 QueryState입니다. $ 접두사로 스토어를 소비하세요: $visitor.data, $visitor.isLoading, $visitor.error.

React에서 넘어오셨나요? Svelte의 QueryState는 React 훅의 isFetched 플래그를 생략하며, useVisitorId()는 명령형 fetch 메서드를 노출하지 않습니다 — useTracioResult()만 getData()를 가집니다.

useVisitorId()

{ data, isLoading, error }의 readable 스토어를 반환하며, 여기서 data는 안정적인 방문자 식별자입니다(string | undefined).

<script>
  import { useVisitorId } from "@tracio/svelte"
  const visitor = useVisitorId()
</script>
{$visitor.data}

useTracioResult(opts?)

전체 TracioResult(방문자 ID와 봇 탐지)를 담은 { data, isLoading, error }의 readable 스토어를 반환합니다. 반환된 스토어는 명령형 (재)fetch를 위한 getData() 메서드도 함께 가집니다(Readable을 확장합니다). opts.immediate의 기본값은 true입니다. { immediate: false }를 전달하면 getData()를 호출할 때까지 fetch를 미룰 수 있습니다 — 예를 들어 동의 게이트 뒤에서 사용할 때 유용합니다.

<script>
  import { useTracioResult } from "@tracio/svelte"
  const result = useTracioResult({ immediate: false })
  // $result.data / $result.isLoading / $result.error
  // result.getData(): Promise<void> — call to fetch on demand
</script>

useTracio()

고급 용도를 위해 내부 TracioInstance를 반환하는 이스케이프 해치입니다(현재 트리에서 Tracio.init()이 실행되지 않았다면 undefined를 반환). 인스턴스를 직접 반환하며 — 구조 분해할 스토어나 래퍼 객체는 없습니다.

<script>
  import { useTracio } from "@tracio/svelte"
  const tracio = useTracio()
</script>

전체 예제

<!-- +layout.svelte -->
<script>
  import { Tracio } from "@tracio/svelte"
  import { browser } from "$app/environment"
  if (browser) Tracio.init({ publicKey: import.meta.env.VITE_TRACIO_KEY })
</script>
<slot />

<!-- AnyComponent.svelte -->
<script>
  import { useVisitorId } from "@tracio/svelte"
  const visitor = useVisitorId()
</script>
{#if $visitor.isLoading}Loading…{:else if $visitor.error}Error: {$visitor.error.message}{:else}Visitor: {$visitor.data}{/if}

다음 단계

• JavaScript SDK 레퍼런스 — 스토어가 기반으로 삼는 코어 @tracio/sdk API
• 오류 처리 — 오류 코드와 재시도 전략
• SDK 개요 — 모든 프레임워크 패키지 한눈에 보기