Hızlı Başlangıç

Bu kılavuz, TRACIO'yu uygulamanıza entegre etme sürecinde size yol gösterir. İstemci SDK'sını kuracak, public key'inizle başlatacak ve ilk ziyaretçi tanımlama sonucunuzu okuyacaksınız.

Adım 1: SDK'yı kurun

TRACIO SDK'sını tercih ettiğiniz paket yöneticisiyle kurun:

bash

npm install @tracio/sdk

Veya pnpm ile:

bash

pnpm add @tracio/sdk

Veya yarn ile:

bash

yarn add @tracio/sdk

Derlemesiz CDN parçacığı

Bir bundler kullanmıyorsanız, edge script etiketini sayfanıza ekleyin. k sorgu parametresindeki public key ile otomatik olarak başlatılır:

HTML

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

Adım 2: SDK'yı başlatın

Tracio'yu içe aktarın ve public key'inizle Tracio.init() çağrısını yapın. Bu, hemen bir TracioInstance döndürür — temeldeki agent arka planda yüklenir.

TypeScript

import { Tracio } from "@tracio/sdk"

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

Public key'iniz istemci tarafı kodda güvenle yayınlanabilir. Onu panonuzda API Keys altında bulabilirsiniz.

Yapılandırma Seçenekleri

Tracio.init(), bir TracioConfig nesnesi kabul eder:

Seçenek	Tür	Varsayılan	Açıklama
`publicKey`	`string`	zorunlu	Public key'iniz. Onu panonuzdan kopyalayın.
`region`	`"us" \| "eu"`	yok	İsteğe bağlı veri bölgesi. Ayarlanmadığında, SDK genel `https://edge.tracio.ai` uç noktasını kullanır (örtük US veri ikametgahı yok). `us` veya `eu`'yu sabitlemek için açıkça ayarlayın.
`endpoint`	`string`	otomatik	Özel API uç noktası (first-party proxy'lenmiş bir uç nokta için).
`scriptUrl`	`string`	otomatik	Agent script için özel URL (first-party proxy'lenmiş bir uç nokta için).
`linkedId`	`string`	yok	Bu ziyaretçiyi sisteminizdeki bir varlığa bağlayan tanımlayıcı.
`tag`	`string`	yok	Sonradan filtrelemek için isteğe eklenen serbest biçimli etiket.
`debug`	`boolean`	`false`	Ayrıntılı tanılamaları konsola kaydeder.
`timeoutMs`	`number`	`15000`	Zaman aşımına uğramadan önce sonucun ne kadar bekleneceği.

Adım 3: Bir Ziyaretçi Kimliği alın

Kararlı bir ziyaretçi tanımlayıcısı almak için tracio.getVisitorId() çağrısını yapın. Bu, eşzamansız bir işlemdir.

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Adım 4: Tam Sonucu okuyun

Bot tespiti dahil olmak üzere tam tanımlama sonucunu almak için tracio.getResult() çağrısını yapın.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr"

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

Sonuç şu biçime sahiptir:

TypeScript

{
  visitorId: "X7fh2Hg9LkMn3pQr",
  bot: {
    detected: false,
    confidence: 2,        // 0-100
    reasons: [],
  },
}

Adım 5: Yaşam döngüsü ve Hatalar

Agent hazır olduğunda veya bir şey başarısız olduğunda tepki vermek için yaşam döngüsü geri çağırmalarını, örneği yıkmak için de destroy() kullanın:

TypeScript

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

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

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

// later, when you no longer need it
tracio.destroy()

Hata kodlarının tam listesi ve yeniden deneme yardımcıları için Hata İşleme bölümüne bakın.

Yaygın Entegrasyon Kalıpları

Oturum Açma Koruması

TypeScript

import { Tracio } from "@tracio/sdk"

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

async function handleLogin(email: string, password: string) {
  const visitorId = await tracio.getVisitorId()

  const response = await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify({ email, password, visitorId }),
  })

  return response.json()
}

Ödeme Dolandırıcılığı Önleme

TypeScript

import { Tracio } from "@tracio/sdk"

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

async function processPayment(paymentData: PaymentData) {
  const result = await tracio.getResult()

  if (result.bot.detected) {
    throw new Error("Automated client detected")
  }

  const response = await fetch("/api/payment", {
    method: "POST",
    body: JSON.stringify({ ...paymentData, visitorId: result.visitorId }),
  })

  return response.json()
}

Sonraki Adımlar

Nasıl Çalışır — Sinyal toplama ve tanımlama pipeline'ını anlayın
JavaScript SDK Referansı — Tam SDK API dokümantasyonu
Webhook'lar — Tanımlama olaylarını sunucunuzda gerçek zamanlı olarak alın
Bot Tespiti — Otomasyon tespitine derinlemesine bakış

Hızlı Başlangıç

Bu kılavuz, TRACIO'yu uygulamanıza entegre etme sürecinde size yol gösterir. İstemci SDK'sını kuracak, public key'inizle başlatacak ve ilk ziyaretçi tanımlama sonucunuzu okuyacaksınız.

Adım 1: SDK'yı kurun

TRACIO SDK'sını tercih ettiğiniz paket yöneticisiyle kurun:

bash

npm install @tracio/sdk

Veya pnpm ile:

bash

pnpm add @tracio/sdk

Veya yarn ile:

bash

yarn add @tracio/sdk

Derlemesiz CDN parçacığı

Bir bundler kullanmıyorsanız, edge script etiketini sayfanıza ekleyin. k sorgu parametresindeki public key ile otomatik olarak başlatılır:

HTML

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

Adım 2: SDK'yı başlatın

Tracio'yu içe aktarın ve public key'inizle Tracio.init() çağrısını yapın. Bu, hemen bir TracioInstance döndürür — temeldeki agent arka planda yüklenir.

TypeScript

import { Tracio } from "@tracio/sdk"

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

Public key'iniz istemci tarafı kodda güvenle yayınlanabilir. Onu panonuzda API Keys altında bulabilirsiniz.

Yapılandırma Seçenekleri

Tracio.init(), bir TracioConfig nesnesi kabul eder:

Seçenek	Tür	Varsayılan	Açıklama
`publicKey`	`string`	zorunlu	Public key'iniz. Onu panonuzdan kopyalayın.
`region`	`"us" \| "eu"`	yok	İsteğe bağlı veri bölgesi. Ayarlanmadığında, SDK genel `https://edge.tracio.ai` uç noktasını kullanır (örtük US veri ikametgahı yok). `us` veya `eu`'yu sabitlemek için açıkça ayarlayın.
`endpoint`	`string`	otomatik	Özel API uç noktası (first-party proxy'lenmiş bir uç nokta için).
`scriptUrl`	`string`	otomatik	Agent script için özel URL (first-party proxy'lenmiş bir uç nokta için).
`linkedId`	`string`	yok	Bu ziyaretçiyi sisteminizdeki bir varlığa bağlayan tanımlayıcı.
`tag`	`string`	yok	Sonradan filtrelemek için isteğe eklenen serbest biçimli etiket.
`debug`	`boolean`	`false`	Ayrıntılı tanılamaları konsola kaydeder.
`timeoutMs`	`number`	`15000`	Zaman aşımına uğramadan önce sonucun ne kadar bekleneceği.

Adım 3: Bir Ziyaretçi Kimliği alın

Kararlı bir ziyaretçi tanımlayıcısı almak için tracio.getVisitorId() çağrısını yapın. Bu, eşzamansız bir işlemdir.

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Adım 4: Tam Sonucu okuyun

Bot tespiti dahil olmak üzere tam tanımlama sonucunu almak için tracio.getResult() çağrısını yapın.

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr"

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

Sonuç şu biçime sahiptir:

TypeScript

{
  visitorId: "X7fh2Hg9LkMn3pQr",
  bot: {
    detected: false,
    confidence: 2,        // 0-100
    reasons: [],
  },
}

Adım 5: Yaşam döngüsü ve Hatalar

Agent hazır olduğunda veya bir şey başarısız olduğunda tepki vermek için yaşam döngüsü geri çağırmalarını, örneği yıkmak için de destroy() kullanın:

TypeScript

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

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

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

// later, when you no longer need it
tracio.destroy()

Hata kodlarının tam listesi ve yeniden deneme yardımcıları için Hata İşleme bölümüne bakın.

Yaygın Entegrasyon Kalıpları

Oturum Açma Koruması

TypeScript

import { Tracio } from "@tracio/sdk"

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

async function handleLogin(email: string, password: string) {
  const visitorId = await tracio.getVisitorId()

  const response = await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify({ email, password, visitorId }),
  })

  return response.json()
}

Ödeme Dolandırıcılığı Önleme

TypeScript

import { Tracio } from "@tracio/sdk"

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

async function processPayment(paymentData: PaymentData) {
  const result = await tracio.getResult()

  if (result.bot.detected) {
    throw new Error("Automated client detected")
  }

  const response = await fetch("/api/payment", {
    method: "POST",
    body: JSON.stringify({ ...paymentData, visitorId: result.visitorId }),
  })

  return response.json()
}

Sonraki Adımlar

Nasıl Çalışır — Sinyal toplama ve tanımlama pipeline'ını anlayın
JavaScript SDK Referansı — Tam SDK API dokümantasyonu
Webhook'lar — Tanımlama olaylarını sunucunuzda gerçek zamanlı olarak alın
Bot Tespiti — Otomasyon tespitine derinlemesine bakış