SDK JavaScript

SDK JavaScript TRACIO (@tracio/sdk) mengumpulkan sinyal browser dan mengirimkannya ke cloud TRACIO untuk identifikasi pengunjung dan deteksi bot. SDK ini ringan, non-blocking, dan kompatibel dengan semua browser modern.

Instalasi

bash

npm install @tracio/sdk

Paket ini menyediakan build ESM, CJS, dan IIFE dengan tipe TypeScript lengkap.

CDN

Ada dua cara untuk menggunakan TRACIO dari CDN tanpa bundler.

Skrip edge (auto-init)

Skrip edge melakukan inisialisasi otomatis menggunakan public key pada parameter query k. Tidak memerlukan JavaScript:

HTML

<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>

Bundle npm (global IIFE)

Anda juga dapat memuat bundle npm yang telah dipublikasikan dari unpkg atau jsDelivr. Bundle ini menyediakan global TracioSDK. Sematkan versi:

HTML

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

Inisialisasi

Tracio.init(config)

Menginisialisasi SDK dan mengembalikan TracioInstance secara sinkron. Agent dimuat di latar belakang; metode instance ter-resolve begitu agent siap.

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

TracioConfig

TypeScript

interface TracioConfig {
  publicKey: string // required
  region?: "us" | "eu"
  endpoint?: string
  scriptUrl?: string
  linkedId?: string
  tag?: string
  debug?: boolean
  timeoutMs?: number // default 15000
}

Opsi	Tipe	Default	Deskripsi
`publicKey`	`string`	wajib	Public key Anda. Salin dari dashboard Anda.
`region`	`"us" \| "eu"`	tidak ada	Region data opsional. Jika tidak diatur, SDK menggunakan endpoint generik `https://edge.tracio.ai` (tanpa residensi data US yang tersirat). Atur secara eksplisit untuk menyematkan `us` atau `eu`.
`endpoint`	`string`	auto	Endpoint API kustom (untuk endpoint yang di-proxy secara first-party).
`scriptUrl`	`string`	auto	URL kustom untuk skrip agent (untuk endpoint yang di-proxy secara first-party).
`linkedId`	`string`	tidak ada	Identifier yang menautkan pengunjung ini ke sebuah entitas dalam sistem Anda.
`tag`	`string`	tidak ada	Label bebas yang dilampirkan pada permintaan untuk pemfilteran di kemudian hari.
`debug`	`boolean`	`false`	Mencatat diagnostik terperinci ke konsol.
`timeoutMs`	`number`	`15000`	Berapa lama menunggu hasil sebelum timeout.

Memanggil Tracio.init() lebih dari sekali dengan public key yang berbeda akan memicu error multiple_keys.

Identifikasi

tracio.getVisitorId()

Mengembalikan Promise<string> yang ter-resolve menjadi identifier pengunjung yang stabil.

TypeScript

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

Mengembalikan Promise<TracioResult> berisi ID pengunjung dan hasil deteksi bot.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId)

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

TracioResult

TypeScript

interface TracioResult {
  visitorId: string
  bot: {
    detected: boolean
    confidence: number // 0-100
    reasons?: string[]
  }
}

Callback Siklus Hidup

tracio.onReady(cb)

Dipanggil begitu agent selesai dimuat dan menghasilkan sebuah hasil.

TypeScript

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

Dipanggil ketika SDK mengalami error.

TypeScript

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

Membongkar instance dan melepaskan sumber daya. Panggilan berikutnya akan ditolak dengan error destroyed.

TypeScript

tracio.destroy()

Penanganan Error

SDK memicu instance TracioError dengan code bertipe. Gunakan helper isTracioError dan isRetryableError untuk bercabang:

TypeScript

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // load_failed / blocked / script_error / network / timeout / server — safe to retry
    }
    console.error("TRACIO error:", error.code, error.message)
  } else {
    console.error("Unexpected error:", error)
  }
}

Kode Error

Union TracioErrorCode mencakup:

Kode	Deskripsi
`blocked`	Permintaan diblokir (mis. oleh ad blocker).
`destroyed`	Instance telah dihancurkan sebelum panggilan selesai.
`invalid_config`	Konfigurasi tidak valid (mis. `publicKey` tidak ada).
`load_failed`	Skrip agent gagal dimuat.
`multiple_keys`	`Tracio.init()` dipanggil dengan public key yang bertentangan.
`network`	Permintaan jaringan gagal.
`non_browser`	SDK digunakan di luar lingkungan browser.
`script_error`	Skrip agent memunculkan error saat runtime.
`server`	Server mengembalikan error.
`timeout`	Permintaan melebihi `timeoutMs`.

load_failed, blocked, script_error, network, timeout, dan server dapat dicoba ulang; isRetryableError(error) mengembalikan true untuk kode-kode tersebut.

Integrasi Framework

Untuk React, Vue, Angular, dan Svelte, gunakan paket framework khusus alih-alih merangkai core SDK secara manual:

Masing-masing membungkus @tracio/sdk dan mengekspos primitif idiomatik (provider, plugin, hook, composable, dan service). Lihat ikhtisar SDK untuk snippet per framework.

Pertimbangan Performa

Non-blocking: Tracio.init() kembali secara sinkron dan memuat agent di latar belakang. Ini tidak memblokir rendering halaman.
Permintaan tunggal: Satu permintaan dibuat per identifikasi.
Timeout: Identifikasi dibatasi oleh timeoutMs (default 15000ms), sehingga jaringan yang lambat tidak akan pernah membuat kode Anda menggantung tanpa batas.

SDK JavaScript

Instalasi

bash

npm install @tracio/sdk

Paket ini menyediakan build ESM, CJS, dan IIFE dengan tipe TypeScript lengkap.

CDN

Ada dua cara untuk menggunakan TRACIO dari CDN tanpa bundler.

Skrip edge (auto-init)

Skrip edge melakukan inisialisasi otomatis menggunakan public key pada parameter query k. Tidak memerlukan JavaScript:

HTML

<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>

Bundle npm (global IIFE)

Anda juga dapat memuat bundle npm yang telah dipublikasikan dari unpkg atau jsDelivr. Bundle ini menyediakan global TracioSDK. Sematkan versi:

HTML

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

Inisialisasi

Tracio.init(config)

Menginisialisasi SDK dan mengembalikan TracioInstance secara sinkron. Agent dimuat di latar belakang; metode instance ter-resolve begitu agent siap.

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

TracioConfig

TypeScript

interface TracioConfig {
  publicKey: string // required
  region?: "us" | "eu"
  endpoint?: string
  scriptUrl?: string
  linkedId?: string
  tag?: string
  debug?: boolean
  timeoutMs?: number // default 15000
}

Opsi	Tipe	Default	Deskripsi
`publicKey`	`string`	wajib	Public key Anda. Salin dari dashboard Anda.
`region`	`"us" \| "eu"`	tidak ada	Region data opsional. Jika tidak diatur, SDK menggunakan endpoint generik `https://edge.tracio.ai` (tanpa residensi data US yang tersirat). Atur secara eksplisit untuk menyematkan `us` atau `eu`.
`endpoint`	`string`	auto	Endpoint API kustom (untuk endpoint yang di-proxy secara first-party).
`scriptUrl`	`string`	auto	URL kustom untuk skrip agent (untuk endpoint yang di-proxy secara first-party).
`linkedId`	`string`	tidak ada	Identifier yang menautkan pengunjung ini ke sebuah entitas dalam sistem Anda.
`tag`	`string`	tidak ada	Label bebas yang dilampirkan pada permintaan untuk pemfilteran di kemudian hari.
`debug`	`boolean`	`false`	Mencatat diagnostik terperinci ke konsol.
`timeoutMs`	`number`	`15000`	Berapa lama menunggu hasil sebelum timeout.

Memanggil Tracio.init() lebih dari sekali dengan public key yang berbeda akan memicu error multiple_keys.

Identifikasi

tracio.getVisitorId()

Mengembalikan Promise<string> yang ter-resolve menjadi identifier pengunjung yang stabil.

TypeScript

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

Mengembalikan Promise<TracioResult> berisi ID pengunjung dan hasil deteksi bot.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId)

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

TracioResult

TypeScript

interface TracioResult {
  visitorId: string
  bot: {
    detected: boolean
    confidence: number // 0-100
    reasons?: string[]
  }
}

Callback Siklus Hidup

tracio.onReady(cb)

Dipanggil begitu agent selesai dimuat dan menghasilkan sebuah hasil.

TypeScript

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

Dipanggil ketika SDK mengalami error.

TypeScript

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

Membongkar instance dan melepaskan sumber daya. Panggilan berikutnya akan ditolak dengan error destroyed.

TypeScript

tracio.destroy()

Penanganan Error

SDK memicu instance TracioError dengan code bertipe. Gunakan helper isTracioError dan isRetryableError untuk bercabang:

TypeScript

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // load_failed / blocked / script_error / network / timeout / server — safe to retry
    }
    console.error("TRACIO error:", error.code, error.message)
  } else {
    console.error("Unexpected error:", error)
  }
}

Kode Error

Union TracioErrorCode mencakup:

Kode	Deskripsi
`blocked`	Permintaan diblokir (mis. oleh ad blocker).
`destroyed`	Instance telah dihancurkan sebelum panggilan selesai.
`invalid_config`	Konfigurasi tidak valid (mis. `publicKey` tidak ada).
`load_failed`	Skrip agent gagal dimuat.
`multiple_keys`	`Tracio.init()` dipanggil dengan public key yang bertentangan.
`network`	Permintaan jaringan gagal.
`non_browser`	SDK digunakan di luar lingkungan browser.
`script_error`	Skrip agent memunculkan error saat runtime.
`server`	Server mengembalikan error.
`timeout`	Permintaan melebihi `timeoutMs`.

load_failed, blocked, script_error, network, timeout, dan server dapat dicoba ulang; isRetryableError(error) mengembalikan true untuk kode-kode tersebut.

Integrasi Framework

Untuk React, Vue, Angular, dan Svelte, gunakan paket framework khusus alih-alih merangkai core SDK secara manual:

Masing-masing membungkus @tracio/sdk dan mengekspos primitif idiomatik (provider, plugin, hook, composable, dan service). Lihat ikhtisar SDK untuk snippet per framework.

Pertimbangan Performa

Non-blocking: Tracio.init() kembali secara sinkron dan memuat agent di latar belakang. Ini tidak memblokir rendering halaman.
Permintaan tunggal: Satu permintaan dibuat per identifikasi.
Timeout: Identifikasi dibatasi oleh timeoutMs (default 15000ms), sehingga jaringan yang lambat tidak akan pernah membuat kode Anda menggantung tanpa batas.