Svelte SDK

Пакет @tracio/svelte оборачивает базовый @tracio/sdk и предоставляет идиоматичные примитивы Svelte: однократный вызов init и readable-хранилища (stores), которые отдают вам ID посетителя и результат идентификации.

Установка

npm install @tracio/svelte @tracio/sdk

svelte (5) — это peer-зависимость, которая, как предполагается, уже установлена в вашем приложении.

Настройка

Вызовите Tracio.init({ publicKey }) один раз, рядом с корнем вашего приложения — в +layout.svelte для SvelteKit — с защитой через 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 />

Хранилища (stores)

Состояние TRACIO предоставляется в виде readable-хранилищ Svelte. Значение каждого хранилища — это QueryState, несущий data, isLoading и error. Обращайтесь к хранилищу с префиксом $: $visitor.data, $visitor.isLoading, $visitor.error.

Переходите с React? У Svelte в QueryState отсутствует флаг isFetched из React-хуков, а useVisitorId() не предоставляет императивного метода загрузки — только useTracioResult() несёт getData().

useVisitorId()

Возвращает readable-хранилище { data, isLoading, error }, где data — стабильный идентификатор посетителя (string | undefined).

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

useTracioResult(opts?)

Возвращает readable-хранилище { data, isLoading, error }, содержащее полный TracioResult (ID посетителя плюс обнаружение ботов). Возвращаемое хранилище также несёт метод getData() (оно расширяет Readable) для императивной (повторной) загрузки. opts.immediate по умолчанию равен true; передайте { immediate: false }, чтобы отложить загрузку до вызова getData() — например, за барьером согласия (consent gate).

<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()

Аварийный выход (escape hatch), который возвращает базовый TracioInstance (или undefined, когда Tracio.init() не был выполнен для текущего дерева) для продвинутого использования. Он возвращает экземпляр напрямую — здесь нет хранилища или объекта-обёртки для деструктуризации.

<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 — базовый API @tracio/sdk, на котором строятся хранилища
• Обработка ошибок — коды ошибок и стратегии повторных попыток
• Обзор SDK — каждый пакет для фреймворка с одного взгляда