SDK Svelte

Il pacchetto @tracio/svelte incapsula il core @tracio/sdk ed espone primitive Svelte idiomatiche: una chiamata init una tantum e store leggibili che restituiscono l'ID visitatore e il risultato dell'identificazione.

Installazione

npm install @tracio/svelte @tracio/sdk

svelte (5) è una peer dependency e si presume sia già installato nell'app.

Setup

Chiami Tracio.init({ publicKey }) una sola volta, vicino alla radice dell'app — in +layout.svelte per SvelteKit — protetta da browser in modo che non venga mai eseguita durante il rendering lato server.

<!-- +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 />

Store

Lo stato di TRACIO è esposto come store leggibili Svelte. Il valore di ciascuno store è un QueryState che trasporta data, isLoading ed error. Consumi lo store con il prefisso $: $visitor.data, $visitor.isLoading, $visitor.error.

Arriva da React? Il QueryState di Svelte omette il flag isFetched degli hook React e useVisitorId() non espone un metodo di recupero imperativo — solo useTracioResult() trasporta un getData().

useVisitorId()

Restituisce uno store leggibile di { data, isLoading, error }, dove data è l'identificatore stabile del visitatore (string | undefined).

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

useTracioResult(opts?)

Restituisce uno store leggibile di { data, isLoading, error } che contiene il TracioResult completo (ID visitatore più rilevamento dei bot). Lo store restituito trasporta anche un metodo getData() (estende Readable) per il (ri)recupero imperativo. opts.immediate ha come default true; passi { immediate: false } per rimandare il recupero fino a quando non chiama getData() — ad esempio dietro un gate di consenso.

<script>
  import { useTracioResult } from "@tracio/svelte"
  const result = useTracioResult({ immediate: false })
  // $result.data / $result.isLoading / $result.error
  // result.getData(): Promise<void> — chiamare per recuperare su richiesta
</script>

useTracio()

Escape hatch che restituisce il TracioInstance sottostante (o undefined quando Tracio.init() non è stato eseguito per l'albero corrente) per usi avanzati. Restituisce l'istanza direttamente — non c'è alcuno store o oggetto wrapper da destrutturare.

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

Esempio completo

<!-- +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}

Prossimi passi

• Riferimento SDK JavaScript — l'API core @tracio/sdk su cui si basano gli store
• Gestione degli errori — codici di errore e strategie di retry
• Panoramica degli SDK — tutti i pacchetti per framework a colpo d'occhio