Kavchat by maxsave
قائمة الأدلة

iOS

تضيف حزمة Swift من Kavchat بوت الدعم القائم على سيناريوهات إلى تطبيق iOS لديكم، مع مكونات SwiftUI وUIKit. الردود متوقعة، وتستمر في العمل دون اتصال بالشبكة باستخدام آخر إصدار منشور. تتطلب iOS 15 أو أحدث.

تضم الحزمة منتجين: KavchatEngine، وهو نسخة Swift من محرك المحادثة دون UIKit، وKavchat، الذي يشمل الاتصال بالشبكة والتخزين المؤقت على الجهاز والواجهة: KavchatChatView (SwiftUI)، وKavchatLauncher وKavchatViewController (UIKit).

التثبيت

باستخدام Swift Package Manager في Xcode: اختاروا ملف > إضافة تبعيات الحزم، ثم أدخلوا عنوان المستودع:

Package URL
https://bitbucket.org/maxsave/kavchat-ios.git

أو في ملف Package.swift:

Package.swift
.package(url: "https://bitbucket.org/maxsave/kavchat-ios.git", from: "0.0.11"),
// ...
.product(name: "Kavchat", package: "kavchat-ios"),

حزمة SDK مفتوحة المصدر بترخيص MIT: bitbucket.org/maxsave/kavchat-ios.

الإعداد

استدعوا configure مرة واحدة، في أقرب وقت ممكن، مثلًا في init الخاص بـApp أو في application(_:didFinishLaunchingWithOptions:):

Swift
import Kavchat

Kavchat.configure(publicKey: "pk_live_...")            // the public key from the dashboard
// Optional:
// Kavchat.configure(publicKey: "pk_live_...", apiBase: "https://api.kavchat.com", locale: "he")

يمكنكم تضمين المفتاح العام في التطبيق. لا تضمّنوا المفتاح السري (sk_live_...) فيه أبدًا.

SwiftUI

زر عائم في الزاوية المحددة في لوحة التحكم، يفتح الدردشة في نافذة (sheet):

SwiftUI
ContentView()
    .kavchatLauncher()

يمكنكم أيضًا تحديد موضع الزر بأنفسكم، أو تضمين الدردشة في شاشة خاصة بكم:

SwiftUI
KavchatLauncher()
KavchatChatView()                                      // full chat, no close button
KavchatChatView(onClose: { showChat = false })         // with a close button

لفتح نافذة الزر العائم وإغلاقها من الكود، استخدموا Kavchat.open() وKavchat.close().

UIKit

UIKit
Kavchat.present(from: self)                            // modal, with a close button
// or
let chat = KavchatViewController(showsCloseButton: false)
navigationController?.pushViewController(chat, animated: true)

رمز الهوية

عرّفوا المستخدم الذي سجّل دخوله باستخدام JWT يوقّعه خادمكم بالمفتاح السري (راجعوا التعرّف على المستخدمين). يُرسل الرمز في الترويسة Authorization: Bearer <token>. يمكن للمستخدم الذي تم التعرّف عليه رؤية الإصدارات المتاحة فقط لمستخدمي الاختبار، وإرسال نموذج التواصل دون بريد إلكتروني أو رقم هاتف.

Swift
Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // after logout

يؤدي تبديل المستخدم إلى إعادة تحميل الإصدار وبدء محادثة جديدة، حتى لا تظهر محادثة مستخدم لدى مستخدم آخر.

شاشات التطبيق: onScreen

يطلب زر من نوع screen في السيناريو من التطبيق فتح إحدى شاشاته. تُغلق نافذة الدردشة أولًا لتظهر الشاشة:

Swift
Kavchat.onScreen = { screen, targetId in
    router.open(screen, id: targetId)                  // e.g. "orders", "42"
}

لا تنفّذ هذه الأزرار أي شيء دون دالة معالجة. تفتح أزرار link روابط https وtel فقط. ولتحليل البيانات، يُبلغ Kavchat.onEvent عن الأحداث ready وunavailable وopen وclose وeffect وticket.

قائمة الشاشات في المحرر

عرّفوا الشاشات التي يستطيع تطبيقكم فتحها مرة واحدة في Kavchat.configure(..., screens:). ترسل حزمة SDK القائمة إلى Kavchat تلقائيًا، ويعرض محرر السيناريوهات هذه الشاشات بأسمائها في قائمة منسدلة بدلًا من حقل نص حر. يطلب المحرر أيضًا معرّف عنصر عندما تحتاج إليه الشاشة، ويحذّر من أي زر يؤدي إلى شاشة لم تُعرّف. لا حاجة إلى إدخال قائمة الشاشات يدويًا في لوحة التحكم.

Swift
Kavchat.configure(publicKey: "pk_live_...", screens: [
    KavchatScreen(id: "orders", label: "My orders"),
    KavchatScreen(id: "product", label: "Product page", needsTarget: true),  // needs a targetId
])
// or later: Kavchat.registerScreens([...])
  • id هو القيمة التي تصل إلى onScreen: أحرف لاتينية وأرقام و_ و. و-، بحد أقصى 40 حرفًا. label هو الاسم الذي يراه المسؤول، بحد أقصى 60 حرفًا. الحد الأقصى 100 شاشة. تُستبعد الإدخالات غير الصالحة والمعرّفات المكررة.
  • needsTarget: يحمل الزر أيضًا معرّف عنصر (مثل معرّف منتج)، ويصل إلى onScreen باسم targetId.
  • تُرسل القائمة في الخلفية بعد تحميل الإصدار، فقط عند تغيّرها أو مرة أسبوعيًا. لا يظهر أي تنبيه عند فشل الإرسال، وتُعاد المحاولة عند التشغيل التالي. لا يظهر للمستخدم أي شيء.
  • تظهر الشاشات المسجّلة في لوحة التحكم ضمن البوت، الإعدادات، "شاشات التطبيق"، مع المنصات التي أبلغت عن كل شاشة. يمكنكم من هناك حذف أي شاشة أزلتموها من التطبيق.

الألوان

تأتي الألوان من لوحة التحكم (primaryColor). يكون النص فوق لون العلامة التجارية أبيض أو قريبًا من الأسود وفقًا لتباين WCAG. وإذا كان اللون فاتحًا أكثر من اللازم لنص على خلفية بيضاء، يُستبدل بلون قريب من الأسود في الروابط والأزرار. يأتي أيضًا اسم البوت والعنوان الفرعي والصورة وجهة الزر العائم (start أو end) من لوحة التحكم، لذا يمكن تغييرها دون تحديث التطبيق.

تظهر شارة "يعمل بواسطة Kavchat by maxsave" في جميع الخطط، مع رابط إلى kavchat.com. في Premium، يمكنكم إخفاؤها من إعدادات البوت.

اللغات والاتجاه من اليمين إلى اليسار

  • لغة الواجهة هي قيمة locale المُمررة إلى configure. إذا لم تُمرر، تُستخدم لغة الجهاز إن كانت لها ترجمة (he, en, ar, ru, es, fr, de, pt, it, tr)، ثم لغة السيناريو، وأخيرًا الإنجليزية.
  • تتم المطابقة مع السيناريو دائمًا بلغته (الكلمات الشائعة التي يجري تجاهلها، والبادئات في العبرية والعربية).
  • في العبرية والعربية، يكون layoutDirection للدردشة بأكملها من اليمين إلى اليسار. لا يُعكس أي شيء يدويًا: إذا وضعتم المكونات داخل حاويات، فاستخدموا leading وtrailing.

ردود الذكاء الاصطناعي (Premium)

لا يلزم إعداد أي شيء في التطبيق. عند تفعيل ردود الذكاء الاصطناعي في لوحة الإدارة (باستخدام مفتاحكم الخاص لدى مزوّد ذكاء اصطناعي)، يُرسل السؤال الذي لا يجيب عنه أي سيناريو إلى Kavchat. وأثناء الانتظار، لمدة تصل إلى 20 ثانية، تُظهر الدردشة أن البوت يكتب. يظهر الرد كنص عادي مع تسمية صغيرة "رد الذكاء الاصطناعي" بلغة الواجهة، وأسفله زر لموضوع ذي صلة إن وُجد، وزر "التواصل مع الفريق".

إذا لم يتوفر رد، أو فشل الطلب، أو استغرق وقتًا أطول من المسموح، أو تجاوز الحد (10 ردود لكل محادثة خلال كل 15 دقيقة)، تعرض الدردشة رسالة "لم أجد إجابة" المعتادة. يظل السؤال ظاهرًا في تقرير الأسئلة التي لم تجد إجابة، وتُحفظ ردود الذكاء الاصطناعي في المحادثة المحفوظة مثل أي رسالة أخرى.

الدردشة مع موظف الدعم

لا يلزم إعداد أي شيء في التطبيق. عند تفعيل الدردشة مع موظفي الدعم في لوحة الإدارة، تعمل الدردشة في التطبيق تمامًا مثل أداة الدردشة في الموقع.

  • يظهر الخيار فقط عندما تكون الدردشة مع موظفي الدعم مفعّلة في الإصدار المنشور. عندما يعرض البوت "التواصل مع الفريق"، تتحقق حزمة SDK من توفر موظف دعم. تُحفظ نتيجة التحقق لمدة 30 ثانية. إذا توفر موظف، يظهر قبله زر "الدردشة مع موظف الدعم". وإذا لم يتوفر، يظهر نموذج التواصل فقط، وفوقه سطر قصير يوضح السبب: خارج ساعات العمل (مع وقت العودة)، أو أن جميع الموظفين مشغولون.
  • قبل المحادثة، يُملأ نموذج قصير: الاسم، والبريد الإلكتروني أو رقم الهاتف، والقسم (فقط عند توفر أكثر من قسم واحد)، ورسالة أولى (اختيارية). يجب على الزائر ترك بريد إلكتروني أو رقم هاتف. أما المستخدم الذي تم التعرّف عليه برمز الهوية فلا يُطلب منه أي منهما. إذا لم يعد هناك موظف متاح وقت الإرسال، يُفتح نموذج التواصل بالبيانات التي أُدخلت بالفعل.
  • أثناء الانتظار، يظهر الوقت المتبقي حتى تتحول المحادثة إلى تذكرة، وزر "ترك رسالة بدلًا من الانتظار". تُحدد مدة الانتظار في لوحة الإدارة، ومدتها الافتراضية 2 دقيقة. يمكن الكتابة أثناء الانتظار أيضًا، وسيرى الموظف الرسائل. إذا لم يتوفر أي موظف خلال المهلة، تُحفظ المحادثة كتذكرة عادية ويظهر رقمها.
  • أثناء المحادثة، يظهر اسم الموظف، وإشعار عند انضمام موظف (بما في ذلك بعد التحويل إلى موظف آخر)، ومؤشر عندما يكتب الموظف، وزر لإنهاء المحادثة. تحتوي الرسائل على نص عادي فقط، بحد أقصى 2,000 حرف، دون روابط. تظهر عبارة "جارٍ الإرسال..." على الرسالة التي لم تصل إلى الخادم بعد. إذا فشل الإرسال عدة مرات، يمكن النقر على الرسالة لإعادة المحاولة. لا تؤدي إعادة المحاولة إلى تكرار الرسالة.
  • بعد كل انقطاع، تنتظر حزمة SDK قليلًا، ثم تسترجع ما فات وتعيد الاتصال. تزداد مدة الانتظار تدريجيًا. تظهر الرسائل دائمًا بالترتيب ودون تكرار. إذا تعذر الاتصال المستمر (مثلًا عند استخدام خادم وكيل مؤسسي)، تنتقل حزمة SDK مؤقتًا إلى الاستعلام المتكرر من الخادم.
  • عندما ينتقل التطبيق إلى الخلفية، يُغلق الاتصال. وعند العودة إلى التطبيق، تسترجع حزمة SDK ما فات وتعيد الاتصال. تستمر المحادثة المفتوحة حتى بعد إغلاق التطبيق وتشغيله من جديد، ما لم تمر 12 ساعة.
  • لا توجد إشعارات دفع في هذا الإصدار. تصل الرسائل فقط عندما يكون التطبيق مفتوحًا. ويظهر الرد الذي أُرسل أثناء وجود التطبيق في الخلفية فور العودة إليه.
  • تُحفظ بيانات الوصول إلى المحادثة في الذاكرة وفي Keychain على الجهاز فقط. ولا تُحفظ في UserDefaults أو في عنوان URL أو سجل. تُحذف هذه البيانات عندما تنتهي المحادثة، أو تتحول إلى تذكرة، أو تنتهي صلاحيتها، وكذلك عند تبديل المستخدم عبر setUser.

يمكنكم استخدام Kavchat.shared.livePage لإبلاغ موظف الدعم بالشاشة التي جاء منها المستخدم.

الأسئلة والشروط والعملاء المحتملون

لا حاجة إلى إعدادات في التطبيق. يمكن للسيناريو طلب بيانات (اسم أو هاتف أو بريد إلكتروني أو رقم أو نص حر)، وتحديد كيفية المتابعة بناءً على المعلومات المعروفة، وإرسال بيانات عميل محتمل.

  • لوحة مفاتيح مناسبة: عندما ينتظر البوت إجابة، تظهر لحقل النص لوحة مفاتيح للهاتف أو البريد الإلكتروني أو الأرقام. وعند السؤال عن الاسم، تتحول لوحة المفاتيح إلى كتابة الحرف الأول من كل كلمة بحرف كبير. إذا كانت الإجابة غير صالحة، يرد البوت برسالة قصيرة بلغة الدردشة ويُميّز الحقل. يظهر زر "تخطي" مع السؤال الذي يمكن تجاوزه. وكتابة "إلغاء"، بأي لغة مدعومة، تُخرج من السؤال.
  • الهاتف: يُربط الرقم الذي لا يبدأ بـ+ بالبلد الافتراضي لمساحة العمل (المحدد في إعدادات لوحة الإدارة).
  • العميل المحتمل: تعرض خطوة العميل المحتمل نص الموافقة مع زري "إرسال" و"لا، شكرًا"، ثم رسالة التأكيد. تُضاف بيانات العميل المحتمل إلى قائمة الانتظار على الجهاز وتُرسل إلى الخادم. عند انقطاع الشبكة أو عدم توفر الخادم، تُعاد محاولات الإرسال (بما في ذلك عند التشغيل التالي وبعد reload()). يتجاهل الخادم البيانات المكررة.
  • التعبئة المسبقة: يُملأ نموذج التواصل ونموذج طلب الدردشة مع موظف الدعم بالاسم والبريد الإلكتروني ورقم الهاتف التي جُمعت. تُرفق جميع القيم التي جُمعت بالتذكرة أو بطلب الدردشة مع موظف الدعم. وتُطرح أسئلة ما قبل الدردشة مع موظف الدعم (Premium) قبل الاتصال.
  • رمز الهوية: عند استخدام setUser، تملأ الحقول name وemail وphone في الرمز إجابات الأسئلة المقابلة لها، ويتخطاها البوت.
  • الشاشة الحالية: يمكن للشروط التحقق من الشاشة الحالية. اضبطوا Kavchat.shared.livePage (مثلًا "checkout").

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

العمل دون اتصال والتخزين المؤقت

يُحفظ آخر إصدار في UserDefaults مع قيمة ETag الخاصة به، ويُعاد التحقق منه باستخدام If-None-Match (304) عند كل تشغيل. عند غياب الشبكة، تُستخدم النسخة المحفوظة ويظهر إشعار بذلك. عندما يكون البوت متوقفًا، أو متاحًا فقط لمستخدمي الاختبار، أو عند نفاد الحصة، لا يظهر أي شيء. تُحفظ المحادثة المفتوحة لمدة تصل إلى 30 دقيقة دون نشاط، لذا لا يؤدي الخروج من الدردشة أو التطبيق إلى بدئها من جديد. يُرسل تقرير مسار المحادثة بعد ثانيتين من آخر إجراء، وفور انتقال التطبيق إلى الخلفية.