דלג לתוכן הראשי
עיון בתיעוד

הטמעה באפליקציה שלכם

כל הדרכים להציב את הווידג׳ט של Syncanix באתר: תגית הסקריפט, אפליקציות עמוד יחיד, עיגון בתוך הדף, זהות ו-CSP.

הווידג׳ט מותקן בתגית סקריפט אחת, וכל השאר בעמוד הזה נבנה עליה: באיזה מפתח להשתמש, איך לטעון אותו באפליקציית עמוד יחיד, איך לעגן אותו בתוך הדף במקום כצף, ומה Content-Security-Policy מחמירה צריכה להתיר.

השיגו את מפתח ההטמעה

הווידג׳ט מאמת עצמו עם מפתח לפרסום. מפתחות לפרסום בטוחים בקוד העמוד: הם מזהים את סביבת העבודה שלכם אך אינם נושאים שום יכולת סודית.

  1. פתחו את מפתחות ה-API בלוח הבקרהעברו אל הגדרות ← מפתחות API בלוח הבקרה של סביבת העבודה.
  2. העתיקו את המפתח לפרסוםהעתיקו את המפתח שמתחיל ב-pk_test_ לפיתוח או ב-pk_live_ לפרודקשן — לעולם לא מפתח סודי gak_, שמקומו רק בשרת שלכם.
  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.

השלבים הבאים

מדריך תצורהכל תכונת data-* שהתגית מקבלת.אימות המשתמשים שלכםחברו את הווידג׳ט למשתמשים המחוברים האמיתיים שלכם.