التضمين في تطبيق جوال

ضَع وكيل Syncanix في تطبيق React Native أو Flutter عبر تحميل أداة الويب داخل WebView — دون الحاجة إلى SDK أصلي.

أداة Syncanix هي مكوّن ويب وWebView هو متصفح، لذا فإن نفس التضمين ذي الوسم الواحد الذي يعمل على موقعك يعمل دون تغيير داخل تطبيق React Native أو Flutter. تحصل على الدردشة الكاملة — متجاوبة مع الجوال، مع معالجة مدمجة للمنطقة الآمنة ولوحة المفاتيح على الشاشة — دون نشر SDK أصلي. هذه الصفحة هي الوصفة.

كيف يعمل

لا يوجد شيء خاص بالجوال لتثبيته. تستضيف صفحة ويب صغيرة تحمل سكربت التضمين القياسي، ثم تحمّل تلك الصفحة داخل WebView بملء الشاشة. تنطلق الأداة داخل الـWebView تمامًا كما في متصفح سطح المكتب.

استضِف صفحة تحمل التضمينصفحة HTML واحدة على أصل HTTPS الخاص بك — غالبًا مسار مخصص مثل /assistant — مع وسم سكربت Syncanix. أضِف ذلك الأصل إلى قائمة الأصول المسموح بها للأداة في مساحة عملك ضمن لوحة التحكم.
حمّل تلك الصفحة داخل WebView بملء الشاشةوجّه react-native-webview أو webview_flutter إلى رابط الصفحة ودعها تملأ الشاشة. لا حاجة لأي ربط أصلي آخر كي تعمل الدردشة.

الصفحة التي تستضيفها

ركّب الدردشة كي تملأ الـWebView، وسمِّ مزوّد رمز يستدعيه الأداة في كل دور للتصرف نيابةً عن المستخدم المسجّل دخوله. تتيح الوسم 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-* يقبلها التضمين.