التضمين في تطبيقك

يُثبَّت الودجت بوسم سكربت واحد، وكل ما في هذه الصفحة يبني عليه: أي مفتاح تستخدم، وكيف تحمّله في تطبيق صفحة واحدة، وكيف تركّبه مضمّنًا بدل العائم، وما الذي يجب أن تسمح به سياسة Content-Security-Policy الصارمة.

احصل على مفتاح التضمين

يوثّق الودجت نفسه بمفتاح قابل للنشر. المفاتيح القابلة للنشر آمنة في شيفرة صفحتك: فهي تعرّف مساحة عملك لكنها لا تحمل أي صلاحية سرّية.

1. 1
   افتح مفاتيح API في لوحة التحكماذهب إلى الإعدادات ← مفاتيح API في لوحة تحكم مساحة عملك.
2. 2
   انسخ المفتاح القابل للنشرانسخ المفتاح الذي يبدأ بـ pk_test_ للتطوير أو pk_live_ للإنتاج — وليس أبدًا مفتاحًا سرّيًا gak_ فهو لا يوضع إلا في خادمك.
3. 3
   طابق المفتاح مع البيئةيستنتج الودجت البيئة من بادئة المفتاح؛ أضِف data-env فقط عندما تحتاج إلى تجاوز ذلك صراحةً.

وسم السكربت

ألصق الوسم قبل إغلاق body مباشرة في كل صفحة يجب أن يظهر فيها المساعد. يجب أن يبقى type="module" — فالودجت وحدة ES ولا يُحمَّل من دونها.

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_test_..."
  data-position="bottom-right"
  data-env="development"
></script>

هذا هو التثبيت كله: يظهر المشغّل في الزاوية المختارة، وكل ما عداه يُصمَّم في لوحة التحكم. القائمة الكاملة للسمات في مرجع التهيئة.

React وVue وسائر تطبيقات الصفحة الواحدة

في تطبيق الصفحة الواحدة يبقى أبسط تثبيت هو الوسم الثابت في index.html — فالودجت يتجاوز تنقّل جانب العميل من تلقاء نفسه. وإن فضّلت التحكم في التركيب من شجرة مكوّناتك، فاحقن السكربت داخل تأثير وفكّكه عند التنظيف:

import { useEffect } from 'react';

export function SyncanixWidget({ embedKey }: { embedKey: string }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.type = 'module';
    script.src = 'https://cdn.syncanix.com/widget.js';
    script.setAttribute('data-key', embedKey);
    document.body.appendChild(script);
    return () => {
      window.syncanix?.unmount();
      script.remove();
    };
  }, [embedKey]);
  return null;
}

النمط نفسه يعمل أينما وُجدت خطافات تركيب وتنظيف: onMounted/onUnmounted في Vue، وngOnInit/ngOnDestroy في Angular، وonMount في Svelte.

التركيب المضمّن بدل العائم

يطفو الودجت افتراضيًا كمشغّل في زاوية الصفحة. لوضع الدردشة داخل تصميمك — لوحة مساعدة، شريط جانبي، صفحة كاملة — استخدم data-chat-size="embedded" ووجّه data-mount-target إلى محدد CSS للحاوية التي يملؤها الودجت:

<div id="assistant-panel"></div>

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_live_..."
  data-chat-size="embedded"
  data-mount-target="#assistant-panel"
></script>

أرسل هوية مستخدمك

من دون هوية يعامل المساعد كل زائر كمجهول. وليتصرف باسم المستخدم المسجّل، سجّل مزوّد رموز: يستدعيه الودجت قبل كل دور، فيُرسل دائمًا رمز محدَّث. الإعداد الكامل لكل أنماط التوثيق في توثيق مستخدميك.

window.syncanix?.setTokenProvider(async () => {
  // Called before each turn — return the signed-in user's current token.
  return auth.getTokenSilently();
});

متطلبات Content-Security-Policy

إذا كان موقعك يطبّق سياسة CSP صارمة، فاسمح بهذه الأمور الثلاثة قبل التضمين:

script-src  https://cdn.syncanix.com;
connect-src https://api.syncanix.com;
style-src   'unsafe-inline';

• يجب أن يسمح script-src بـ cdn.syncanix.com — من حيث يُقدَّم widget.js وأجزاؤه الكسولة.
• يجب أن يسمح connect-src بـ api.syncanix.com — حيث يبثّ الودجت المحادثات.
• يجب أن يسمح style-src بـ 'unsafe-inline' — يحقن الودجت أنماطه داخل Shadow DOM خاص به، فلا تمسّ أنماط صفحتك أبدًا.
• الصفحات التي تفرض Trusted Types مدعومة دون تعديل: الودجت لا يغذّي أي string sink أبدًا.

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