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

הטמעה באפליקציה ניידת

הכניסו את סוכן Syncanix לאפליקציית React Native או Flutter על ידי טעינת רכיב הווב בתוך WebView — ללא צורך ב-SDK מקורי.

רכיב Syncanix הוא רכיב ווב ו-WebView הוא דפדפן, ולכן אותה הטמעה בתג יחיד שרצה באתר שלכם רצה ללא שינוי בתוך אפליקציית React Native או Flutter. אתם מקבלים את הצ'אט המלא — מותאם לנייד, עם טיפול מובנה באזור הבטוח ובמקלדת המסך — בלי לפרסם SDK מקורי. העמוד הזה הוא המתכון.

איך זה עובד

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

  1. ארחו דף שנושא את ההטמעהדף HTML יחיד במקור ה-HTTPS שלכם — לרוב נתיב ייעודי כמו /assistant — עם תג הסקריפט של Syncanix. הוסיפו את המקור הזה לרשימת המקורות המורשים של הרכיב במרחב העבודה שלכם בלוח הבקרה.
  2. טענו את הדף הזה בתוך WebView במסך מלאהפנו את react-native-webview או webview_flutter לכתובת הדף ותנו לו למלא את המסך. אין צורך בחיווט מקורי נוסף כדי שהצ'אט יעבוד.

הדף שאתם מארחים

הטעינו את הצ'אט כך שימלא את ה-WebView, ונקבו בשם ספק אסימון שהרכיב קורא לו בכל תור כדי לפעול בשם המשתמש המחובר. תג ה-meta viewport-fit=cover מאפשר לצ'אט לכבד את האזורים הבטוחים של המכשיר.

<!-- https://help.yourapp.com/assistant — a page you host, loaded by the WebView -->
<!doctype html>
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
<style>
  html, body { margin: 0; height: 100%; }
  #assistant { height: 100vh; }
</style>
<div id="assistant"></div>

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_live_..."
  data-chat-size="embedded"
  data-mount-target="#assistant"
  data-token-provider="getSyncanixToken"
></script>
<script>
  // The widget calls this once per turn; return the token your app injected.
  window.getSyncanixToken = () => window.__SYNCANIX_TOKEN__ ?? undefined;
</script>

הסקריפט המוטמע מגדיר את הפונקציה הגלובלית שהרכיב קורא לה בכל תור; הקוד המקורי שלכם מגדיר את window.__SYNCANIX_TOKEN__ לפני שהדף נטען (למטה).

React Native

הציגו WebView במסך מלא והזריקו את אסימון המשתמש לפני שתוכן הדף נטען. השאירו את JavaScript מופעל — הוא מופעל כברירת מחדל.

import { WebView } from 'react-native-webview';

export function AssistantScreen({ userToken }: { userToken: string }) {
  return (
    <WebView
      source={{ uri: 'https://help.yourapp.com/assistant' }}
      // Hand the signed-in user's token to the page before its content loads.
      injectedJavaScriptBeforeContentLoaded={
        `window.__SYNCANIX_TOKEN__ = ${JSON.stringify(userToken)}; true;`
      }
      // JavaScript is enabled by default; the widget needs it.
    />
  );
}

כאשר האסימון מתחדש, דחפו את הערך החדש עם webviewRef.injectJavaScript('window.__SYNCANIX_TOKEN__ = "..."; true;').

Flutter

השתמשו ב-webview_flutter עם JavaScript ללא הגבלה, והגדירו את האסימון כשהדף מתחיל להיטען.

final controller = WebViewController()
  ..setJavaScriptMode(JavaScriptMode.unrestricted)
  ..setNavigationDelegate(NavigationDelegate(
    onPageStarted: (_) => controller.runJavaScript(
      'window.__SYNCANIX_TOKEN__ = ${jsonEncode(userToken)};',
    ),
  ))
  ..loadRequest(Uri.parse('https://help.yourapp.com/assistant'));

// In build(): return WebViewWidget(controller: controller);

חיבור המשתמש

WebView אינו חולק שום סשן עם האפליקציה המקורית שלכם, ולכן הרכיב אינו יכול לדעת מי מחובר אלא אם תגידו לו. מסרו לו את אסימון המשתמש מ-SDK הזהות של האפליקציה שלכם; הרכיב אז פועל בשם אותו משתמש, מוגבל בהרשאות שלו עצמו — אותו מודל פעולה בשם המשתמש כמו בווב.

  • האסימון הוא ה-JWT של המשתמש מספק הזהות שלכם — אותו אחד שה-API שלכם כבר בוטח בו.
  • הוא נקרא פעם אחת בכל תור צ'אט, כך שאסימון מחודש נקלט אוטומטית.
  • בעת ההתנתקות, נקו אותו (הגדירו את window.__SYNCANIX_TOKEN__ ל-null) כדי שהעוזר יפסיק לפעול בשם אותו משתמש.

לפני ההשקה

  • ארחו את הדף במקור HTTPS אמיתי (לא נכס file:// ארוז) והוסיפו את המקור הזה לרשימת המקורות המורשים של הרכיב — הרשימה מותאמת לפי מקור.
  • הפעילו JavaScript ב-WebView (React Native: מופעל כברירת מחדל; Flutter: JavaScriptMode.unrestricted).
  • הוסיפו viewport-fit=cover כדי שהצ'אט יתרחק מהמגרעת וממחוון הבית.
  • תנו למקלדת המסך לשנות את גודל ה-viewport במקום לכסות אותו; הרכיב שומר את תיבת הכתיבה גלויה באמצעות visualViewport.

השלבים הבאים

הטמעה באפליקציה שלכםההתקנה המלאה בווב: SPA, זהות, ו-CSP.הגדרהכל תכונת data-* שההטמעה מקבלת.