§ 00نظرة عامة
تتحدث حزمة تطوير Flutter البروتوكول المجهول نفسه الذي تستخدمه محادثة موقعك الإلكتروني — حتى يتمكن العملاء من الوصول إلى الدعم من داخل تطبيقك المحمول، ضمن المحادثات نفسها التي يتعامل معها وكلاؤك بالفعل في صندوق الوارد المشترك.
تُشحن على هيئة حزمتين:
easylivechat— عميل بروتوكول بلا واجهة مع حالة تفاعلية، دون أي واجهةeasylivechat_ui— عناصر واجهة جاهزة وقابلة للتنسيق — المُشغِّل، شاشة المحادثة، نموذج ما قبل المحادثة، المرفقات، CSAT
§ 01التثبيت
أضف حزمة التطوير إلى ملف pubspec.yaml الخاص بتطبيقك. تحتاج معظم التطبيقات إلى easylivechat_ui — فهي تُعيد تصدير النواة. لا تلجأ إلى easylivechat بلا واجهة بمفردها إلا عندما تبني واجهة مخصصة بالكامل.
dependencies: easylivechat_ui: ^0.1.0 # prebuilt UI + the headless core # — or, headless only — easylivechat: ^0.1.0
يتطلب Flutter بإصدار 3.19 أو أحدث. يجب أن يكون socket_io_client من إصدارات 3.x (Engine.IO v4) ليتوافق مع الخادم.
§ 02البدء السريع (واجهة جاهزة للاستخدام)
هيّئ العميل مرة واحدة باستخدام مُعرّف مساحة عملك المختصر، ثم أضف مُشغِّلًا إلى شجرة عناصر الواجهة لديك. تفتح الفقاعة محادثة موصولة بالكامل: نموذج ما قبل المحادثة، خيط في الوقت الفعلي، مؤشر الكتابة، المرفقات، CSAT، نموذج عدم الاتصال خارج ساعات العمل، إضافةً إلى التنسيق المُدار من الخادم ودعم RTL.
import 'package:easylivechat_ui/easylivechat_ui.dart';
await EasyLiveChat.instance.boot(
const EasyLiveChatConfig(
apiBase: 'https://api.livechattools.com',
tenantSlug: 'acme', // your workspace slug
),
storage: SecurePrefsStorage(), // durable visitorId + JWT
);
// In your widget tree — a floating bubble that opens the full chat:
Stack(children: [ MyApp(), const EasyLiveChatLauncher() ]);ابحث عن مُعرّف مساحة عملك المختصر في لوحة التحكم الخاصة بك. يبدأ المُشغِّل بالتهيئة بشكل كسول عند الفتح الأول؛ مرّر تخزينًا دائمًا حتى تبقى هوية الزائر صامدةً عبر عمليات إعادة تشغيل التطبيق.
§ 03بلا واجهة (ابنِ واجهتك الخاصة)
هل تفضّل نظام التصميم الخاص بك؟ تحكّم في العميل بلا واجهة مباشرةً. كل شيء مُتاح على هيئة ValueListenables و Streams يمكنك ربطها بأي نظام لإدارة الحالة.
import 'package:easylivechat/easylivechat.dart';
final chat = EasyLiveChat.instance;
await chat.boot(const EasyLiveChatConfig(
apiBase: 'https://api.livechattools.com', tenantSlug: 'acme'),
storage: myDurableStorage); // implement EasyLiveChatStorage
await chat.open(); // config → resume → prechat/anon → connect
chat.messages.addListener(rebuild); // ValueListenable<List<ChatMessage>>
chat.agentTyping.addListener(rebuild);
final res = chat.sendMessage('Hello!'); // optimistic; res.serverMessageId on ack
await chat.submitFeedback(rating: 5);تُنسّق open() دورة الحياة الكاملة: جلب الإعدادات، استئناف أي محادثة مفتوحة، التحقق عبر نموذج ما قبل المحادثة أو البدء بشكل مجهول، ثم الاتصال بالمقبس في الوقت الفعلي.
§ 04كيف يعمل
عند فتح جلسة، يُصدر الخادم رمزًا قصير الأجل خاصًا بكل محادثة. تستخدمه حزمة التطوير في استدعاءات REST والمقبس في الوقت الفعلي، وتُعيد إصداره بشفافية قبل انتهاء صلاحيته، وتُعيد الاتصال بإعادة تعبئة آمنة من الفجوات عند انقطاع شبكة الجوال.
كل شيء مجهول الهوية أولًا: تُولّد حزمة التطوير مُعرّف زائر دائمًا على الجهاز — دون الحاجة إلى تسجيل دخول — وتجمع اختياريًا اسمًا وبريدًا إلكترونيًا عبر نموذج ما قبل المحادثة الخاص بالمستأجر.
الأمان: لا تُضمّن مفتاح واجهة برمجة التطبيقات الخاص بالمستأجر داخل تطبيق مشحون أبدًا — فهذا سرٌّ من خادم إلى خادم. لا تستخدم حزمة تطوير Flutter سوى رمز جلسة الزائر، وهو آمن للعميل الموزّع.
§ 05ما الذي يحتاج إلى عمل على جانب الخادم
تعمل تجربة المحادثة الكاملة في الواجهة الأمامية اليوم دون أي تغييرات على الخادم الخلفي. القدرة الوحيدة التي تحتاج إلى عمل على الخادم هي الإشعارات في الخلفية — أي إيصال إشعار «ردّ الوكيل» إلى تطبيق مُغلَق — لأن الخادم الخلفي يدفع الإشعارات حاليًا إلى الوكلاء فقط. يلزم وجود سجل دفع للزوار وآلية توزيع لتمكينها؛ ويبقى خطّاف الدفع في حزمة التطوير خاملًا حتى ذلك الحين.
متابعات موصى بها قبل الإطلاق العام: تحديد المعدّل على إنشاء الجلسات وإرسال الرسائل، ونقطة نهاية لتحديث الرمز، ودعم رفع HEIC/MOV لوسائط الهاتف.