واجهة وقت تشغيل الأداة

بمجرّد تحميل الأداة، تثبّت كائن window.syncanix الذي يمكنك استدعاؤه من شيفرتك الخاصة.

ما الذي يمكنك فعله

• open() / close() / toggle() — افتح لوحة المحادثة أو أغلقها أو بدّلها من شيفرتك أنت.
• isOpen — هل اللوحة مفتوحة الآن، ليعرض زرّك الحالة المطابقة.
• setPosition(position) — نقل المشغّل إلى زاوية أخرى.
• enable() / disable() — تشغيل الدردشة أو إيقافها أثناء التشغيل دون إزالتها (للأعطال أو الدفع أو ساعات الدعم).
• unmount() — إزالة الأداة من الصفحة.
• registerComponent() / unregisterComponent() / getComponentCatalog() — سجّل مكوّنات React الخاصة بك كي يعرضها المساعد، مُتحقَّقًا منها بمخطّط.
• exposeShadowRoot(host, root) — يخبر الأداة بجزء من صفحتك مبنيّ بمكوّنات الويب، ليتمكّن المساعد من رؤية عناصر التحكّم داخله وتشغيلها. ويعيد دالة تتراجع عن ذلك.
• registerDataSource() / unregisterDataSource() / getDataSourceCatalog() — امنح المساعد طريقة مسمّاة لجلب بيانات من تطبيقك، لتعرض الإجابة المركّبة أرقامًا حيّة بدل وصفها.
• registerAction() / unregisterAction() / getActionCatalog() — تتيح للمساعد استدعاء دوالك الخاصة، مع التحقق من المخطط وبوابة تأكيد اختياريين.
• setContext() / clearContext() — تغذية الحالة الحيّة للتطبيق (المستخدم، الصفحة، السلّة) في الدور التالي. JSON محدود فقط — لا أسرار أبدًا.
• setTokenProvider(fn) — توفير رمز المستخدم النهائي لكل دور (له أولوية على سمة data).
• setStepUpProvider(fn) — توفير تدفّق إعادة المصادقة المعزَّزة.
• setHeadersProvider(fn) — يضيف ترويسات طلب (مثل Authorization أو رمز CSRF) إلى كل استدعاء أداة؛ وله الأولوية على سمة البيانات.
• setTheme(key) — يبدّل السمة الحية بالاسم دون إعادة تركيب الدردشة (لمبدّل فاتح/داكن في الموقع المضيف).
• setConsent(signal) — أخبر الأداة بما وافق عليه الزائر، لتتبع الاختيار الذي جمعه شريط الموافقة الخاص بك أصلًا.
• mapSite() / stopSiteWalk() وteach() / stopTeach() — ابدأ وأوقف من صفحتك جلستَي الرسم اللتين يشغّلهما المشغّل. وتحتاج كل منهما رمزًا لمرة واحدة يُولَّد في لوحة التحكم، ولا تبدأ أي منهما بدونه.

مثال

// Open the chat programmatically
window.syncanix.open();

// Feed live host-app context into the next turn (bounded JSON, no secrets)
window.syncanix.setContext({ page: 'checkout', cartItems: 3 });

// Provide the signed-in user's token per turn (recommended for SSR apps)
window.syncanix.setTokenProvider(async () => await getAccessToken());

ما الذي يمكن للمساعد عرضه — وما الذي لا يمكنه رؤيته

سطح العرض صريح بالتصميم: العناصر الأولية المدمجة، والمكوّنات التي تسجّلها عبر registerComponent، والتضمينات من الأصول التي أدرجها مسؤولك في قائمة السماح. لا يمكن للمساعد التحكم إلا فيما سلّمته له عمدًا.

ما تقرؤه الأداة من صفحتك سؤال منفصل. الاكتشاف مُفعَّل افتراضيًا ويقرأ بنية صفحاتك — أي النماذج موجودة، وما أسماء حقولها، وإلى أين تذهب روابطك — ويقترح كل واحد كقدرة تراجعها. ولا تقرأ أبدًا ما كتبه أحد، وكل ما تجده يصل مُطفأً.

يُحمَّل مرة واحدة

تثبيت الكائن العام عملية مُتكافئة — فإن أُدرِج السكربت مرتين، يُتجاهَل المكرّر مع تحذير، فلا تنتهي أبدًا بأداتين.

الخطوات التالية