JavaScript SDK

TRACIO JavaScript SDK (@tracio/sdk) ब्राउज़र सिग्नल एकत्र करता है और उन्हें विज़िटर पहचान तथा बॉट डिटेक्शन के लिए TRACIO क्लाउड को भेजता है। यह हल्का, non-blocking और सभी आधुनिक ब्राउज़रों के साथ संगत है।

इंस्टॉलेशन

npm install @tracio/sdk

यह पैकेज पूर्ण TypeScript टाइप्स के साथ ESM, CJS और IIFE बिल्ड प्रदान करता है।

CDN

बिना किसी bundler के CDN से TRACIO का उपयोग करने के दो तरीके हैं।

Edge स्क्रिप्ट (auto-init)

Edge स्क्रिप्ट k query parameter में मौजूद public key का उपयोग करके स्वचालित रूप से इनिशियलाइज़ हो जाती है। किसी JavaScript की आवश्यकता नहीं:

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

npm bundle (IIFE global)

आप प्रकाशित npm bundle को unpkg या jsDelivr से भी लोड कर सकते हैं। यह एक TracioSDK global उपलब्ध कराता है। किसी संस्करण को पिन करें:

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

इनिशियलाइज़ेशन

Tracio.init(config)

SDK को इनिशियलाइज़ करता है और सिंक्रोनस रूप से एक TracioInstance लौटाता है। एजेंट पृष्ठभूमि में लोड होता है; तैयार होते ही इंस्टेंस के methods resolve हो जाते हैं।

import { Tracio } from "@tracio/sdk"

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

TracioConfig

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

Tracio.init() को किसी भिन्न public key के साथ एक से अधिक बार कॉल करने पर multiple_keys त्रुटि फेंकी जाती है।

पहचान

tracio.getVisitorId()

एक Promise<string> लौटाता है जो स्थिर विज़िटर पहचानकर्ता में resolve होता है।

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

tracio.getResult()

विज़िटर ID और बॉट डिटेक्शन परिणाम के साथ एक Promise<TracioResult> लौटाता है।

const result = await tracio.getResult()

console.log(result.visitorId)

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

TracioResult

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

Lifecycle Callbacks

tracio.onReady(cb)

एजेंट के लोड होने और परिणाम उत्पन्न कर लेने पर एक बार आह्वान किया जाता है।

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

tracio.onError(cb)

SDK के किसी त्रुटि का सामना करने पर आह्वान किया जाता है।

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

tracio.destroy()

इंस्टेंस को समाप्त करता है और संसाधन मुक्त करता है। इसके बाद के कॉल destroyed त्रुटि के साथ अस्वीकृत हो जाते हैं।

tracio.destroy()

त्रुटि प्रबंधन

SDK एक typed code के साथ TracioError इंस्टेंस फेंकता है। शाखा बनाने के लिए isTracioError और isRetryableError helpers का उपयोग करें:

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

त्रुटि कोड

TracioErrorCode union में शामिल हैं:

load_failed, blocked, script_error, network, timeout और server retryable हैं; isRetryableError(error) इनके लिए true लौटाता है।

Framework इंटीग्रेशन

React, Vue, Angular और Svelte के लिए, core SDK को हाथ से जोड़ने के बजाय समर्पित framework पैकेजों का उपयोग करें:

• @tracio/react
• @tracio/vue
• @tracio/angular
• @tracio/svelte

प्रत्येक @tracio/sdk को wrap करता है और idiomatic primitives (providers, plugins, hooks, composables और services) उपलब्ध कराता है। प्रति-framework snippets के लिए SDKs अवलोकन देखें।

प्रदर्शन संबंधी विचार

• Non-blocking: Tracio.init() सिंक्रोनस रूप से लौटता है और एजेंट को पृष्ठभूमि में लोड करता है। यह पेज रेंडरिंग को ब्लॉक नहीं करता।
• एकल request: प्रति पहचान एक request की जाती है।
• Timeout: पहचान timeoutMs (डिफ़ॉल्ट 15000ms) द्वारा सीमित होती है, ताकि धीमा network आपके कोड को कभी भी अनिश्चित काल तक न रोके।