טפלו בשגיאות בצורה נאותה בסביבת הייצור כדי למנוע כשלים שקטים. כאשר קריאה כמו getResult() נכשלת, ה-SDK זורק TracioError — תת-מחלקה של Error עם שדה code הקריא למכונה.
עטפו את await tracio.getResult() ב-try/catch וצמצמו את הערך הנזרק באמצעות isTracioError(), ואז הסתעפו לפי error.code:
import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"
const tracio = Tracio.init({ publicKey: "5ca175fc..." })
try { const result = await tracio.getResult() console.log(result.visitorId, result.bot.detected)} catch (error) { if (isTracioError(error)) { if (isRetryableError(error)) { // Transient failure (network, timeout, blocked script, upstream) — // a fresh attempt may succeed. console.warn(`Retryable TRACIO error: ${error.code}`) } else { // Terminal failure (bad config, misuse, destroyed instance) — // fix the caller; retrying the same call will not help. console.error(`Terminal TRACIO error: ${error.code} — ${error.message}`) } } else { console.error("Unexpected error:", error) }}הסוכן נטען אסינכרונית ברקע. אם הטעינה נכשלת עוד לפני שקראתם ל-getResult(), הכשל מועבר דרך ה-callback בשם onError. רשמו אותו מיד לאחר init():
const tracio = Tracio.init({ publicKey: "5ca175fc..." })
tracio.onError((error) => { // Same TracioError instance you would catch from getResult(). console.warn(`TRACIO failed to initialize: ${error.code}`)})
tracio.onReady((result) => { console.log("Visitor identified:", result.visitorId)})אותה שגיאה נותרת ניתנת לצפייה דרך getResult() — תוכלו להשתמש בכל אחד מהערוצים.
כל TracioError נושא code מהטיפוס TracioErrorCode. ה-getter בשם retryable (והפונקציה isRetryableError()) מדווחים האם ניסיון חדש עשוי להצליח.
| Code | משמעות | ניתן לניסיון חוזר |
|---|---|---|
invalid_config | התצורה שהועברה ל-Tracio.init() אינה תקינה | לא |
multiple_keys | יותר ממפתח ציבורי אחד נעשה בו שימוש באותו עמוד | לא |
non_browser | בוצע await על getResult() מחוץ לדפדפן (למשל בשרת) | לא |
load_failed | סקריפט הסוכן נכשל בטעינה | כן |
blocked | הסקריפט נחסם (חוסם פרסומות או CSP) | כן |
script_error | הסקריפט שנטען זרק שגיאה בזמן האתחול | כן |
network | כשל רשת/תעבורה בהגעה ל-API | כן |
timeout | הקריאה חרגה מתקציב ה-timeoutMs שהוגדר | כן |
server | ה-edge/השרת החזיר כשל upstream | כן |
destroyed | המופע הושמד (באמצעות destroy()) לפני הקריאה | לא |
קודים סופיים (invalid_config, multiple_keys, non_browser, destroyed) מעידים על בעיית תצורה, שימוש או מחזור חיים — תקנו את הקורא או קראו שוב ל-Tracio.init(). קודים הניתנים לניסיון חוזר הם זמניים, וניסיון חדש עשוי להצליח.
עבור שגיאות הניתנות לניסיון חוזר, נסו שוב עם backoff מול ניסיון חדש, במקום לבצע await חוזר על אותו promise שנדחה:
import { Tracio, isRetryableError } from "@tracio/sdk"
async function identifyWithRetry(maxAttempts = 3) { let attempt = 0 while (true) { const tracio = Tracio.init({ publicKey: "5ca175fc..." }) try { return await tracio.getResult() } catch (error) { attempt++ // Tear down before retrying: init() returns the cached instance for the // same key, and getResult() caches its (rejected) promise — so a genuine // fresh attempt requires destroy() first. tracio.destroy() if (!isRetryableError(error) || attempt >= maxAttempts) throw error await new Promise((r) => setTimeout(r, 2 ** attempt * 250)) } }}