تعامل مع الأخطاء بسلاسة في بيئة الإنتاج لتفادي حالات الفشل الصامتة. عندما يفشل استدعاء مثل 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) }}يُحمَّل العميل (agent) بشكل غير متزامن في الخلفية. إذا فشل التحميل قبل أن تستدعي getResult() أصلاً، فإن الفشل يُسلَّم عبر نداء 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. تُبلِّغ خاصية الجلب retryable (وكذلك الدالة المساعدة isRetryableError()) عمّا إذا كانت محاولة جديدة قد تنجح.
| الرمز | المعنى | قابل لإعادة المحاولة |
|---|---|---|
invalid_config | الإعداد المُمرَّر إلى Tracio.init() غير صالح | لا |
multiple_keys | استُخدِم أكثر من مفتاح عام واحد في الصفحة نفسها | لا |
non_browser | جرى انتظار getResult() خارج المتصفح (مثلاً على الخادم) | لا |
load_failed | فشل تحميل سكربت العميل (agent) | نعم |
blocked | جرى حجب السكربت (مانع إعلانات أو CSP) | نعم |
script_error | أطلق السكربت المُحمَّل خطأً أثناء التهيئة | نعم |
network | فشل في الشبكة/النقل عند الوصول إلى API | نعم |
timeout | تجاوز الاستدعاء ميزانية timeoutMs المُعدَّة | نعم |
server | أعاد طرف الحافة/الخادم فشلاً من الطبقة الأعلى | نعم |
destroyed | جرى تدمير النسخة (عبر destroy()) قبل الاستدعاء | لا |
تشير الرموز النهائية (invalid_config وmultiple_keys وnon_browser وdestroyed) إلى مشكلة في الإعداد أو الاستخدام أو دورة الحياة — أصلِح المستدعي أو استدعِ Tracio.init() من جديد. أما الرموز القابلة لإعادة المحاولة فهي عابرة، وقد تنجح محاولة جديدة.
بالنسبة إلى الأخطاء القابلة لإعادة المحاولة، أعِد المحاولة بتراجع تدريجي (backoff) عبر محاولة جديدة بدلاً من إعادة انتظار الوعد المرفوض نفسه:
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)) } }}