عون كير

حزمة الودجت

حزمة الودجت (SDK)

ضمّن ودجت محادثة عون كير وتحكّم فيه من جافاسكربت عبر الواجهة العامة window.AwnCare.

التثبيت

أضِف وسم سكربت واحدًا مع معرّف مساحة العمل. يُركّب الودجت نفسه داخل Shadow DOM معزول فلا يتعارض مع تنسيقات صفحتك.

وسم السكربت

أبسط طريقة للتثبيت — الصق هذا قبل وسم إغلاق الصفحة.

html
<script
  src="https://awn.care/widget/awncare.js"
  data-workspace-id="YOUR_WORKSPACE_ID"
  async>
</script>

طابور الأوامر غير المتزامن

عرّف دالة صغيرة قبل تحميل الحزمة لتُخزَّن الأوامر المبكرة وتُنفَّذ فور تركيب الودجت.

html
<script>
  window.AwnCare = window.AwnCare || function () {
    (AwnCare.q = AwnCare.q || []).push(arguments);
  };
</script>
<script
  src="https://awn.care/widget/awncare.js"
  data-workspace-id="YOUR_WORKSPACE_ID"
  async>
</script>

<script>
  // Safe to call immediately — queued until the widget mounts.
  AwnCare("identify", { email: "[email protected]", name: "Sara" });
  AwnCare("on", "ready", function () {
    console.log("AwnCare widget ready");
  });
</script>
فضِّل استخدام window.awncareSettings أو سمات data-* للإعداد — يفوز الإعداد الصريح دائمًا على سمة data المقابلة.

الإعداد

عيّن window.awncareSettings قبل تحميل الحزمة لضبط الإقلاع. تتجاوز هذه القيم سمات data-* في وسم السكربت.

الحقلالنوعالوصف
workspaceIdstringمعرّف مساحة العمل. مطلوب ما لم يُمرَّر عبر data-workspace-id.
locale"ar" | "en"لغة واجهة الودجت الأولية.
position"bottom-right" | "bottom-left"الزاوية التي يظهر فيها زر الإطلاق.
colorstringلون الزر واللون المميّز (أي لون CSS).
zIndexnumberترتيب طبقة الودجت. القيمة الافتراضية هي القصوى.
hideLauncherbooleanابدأ وزر الإطلاق مخفيًا، ثم أظهِره لاحقًا عبر AwnCare.show().
baseUrlstringتجاوز أصل الـ API الذي يتصل به الودجت.
html
<script>
  window.awncareSettings = {
    workspaceId: "YOUR_WORKSPACE_ID",
    locale: "ar",              // "ar" | "en"
    position: "bottom-left",   // "bottom-right" | "bottom-left"
    color: "#0F766E",          // launcher / accent color
    zIndex: 2147483000,
    hideLauncher: false,       // start hidden, reveal later with AwnCare.show()
    baseUrl: "https://awn.care"
  };
</script>
<script src="https://awn.care/widget/awncare.js" async></script>

مرجع الواجهة

كل الدوال المتاحة على window.AwnCare. الدوال المستدعاة قبل اكتمال تركيب الودجت تُخزَّن وتُنفَّذ تلقائيًا.

version: string

نص إصدار الحزمة الدلالي، مثل "1.0.0".

js
console.log(AwnCare.version); // "1.0.0"

open(): void

فتح نافذة المحادثة.

js
AwnCare.open();

close(): void

إغلاق نافذة المحادثة.

js
AwnCare.close();

toggle(): void

تبديل فتح/إغلاق نافذة المحادثة.

js
AwnCare.toggle();

isOpen(): boolean

تُعيد true عندما تكون نافذة المحادثة مفتوحة.

js
if (!AwnCare.isOpen()) {
  AwnCare.open();
}

sendMessage(text: string): void

إرسال رسالة من الزائر إلى المحادثة النشطة.

js
// Sends a message from the visitor into the active conversation.
AwnCare.sendMessage("مرحبًا، أحتاج مساعدة في طلبي");

setUser(data): void

تعيين سمات جلسة خفيفة (الاسم والبريد وأي مفاتيح إضافية) للزائر الحالي.

js
// Lightweight attributes for the current session (name/email + extras).
AwnCare.setUser({
  name: "Sara Al-Otaibi",
  email: "[email protected]",
  plan: "pro"
});

identify(data: IdentifyData): void

حفظ سمات جهة الاتصال في سجل الزائر على الخادم ليعرف الوكلاء مع من يتحدثون.

js
// Persist contact traits to the server visitor record.
AwnCare.identify({
  externalId: "usr_10294",
  name: "Sara Al-Otaibi",
  email: "[email protected]",
  phone: "+966500000000",
  company: "Acme",
  metadata: { plan: "pro", mrr: 199 }
});

on(event, callback): void

الاشتراك في حدث من أحداث الودجت عبر دالة استدعاء.

js
function onAgentReply(payload) {
  console.log("Agent said:", payload.text);
}
AwnCare.on("message:received", onAgentReply);

off(event, callback?): void

إزالة مُستمِع معيّن، أو كل المستمعين لحدث عند عدم تمرير دالة.

js
// Remove one listener…
AwnCare.off("message:received", onAgentReply);
// …or every listener for an event:
AwnCare.off("message:received");

setLocale(locale: "ar" | "en"): void

تبديل لغة واجهة الودجت أثناء التشغيل.

js
AwnCare.setLocale("en"); // switch the widget UI to English at runtime

getUnreadCount(): number

إرجاع عدد الرسائل غير المقروءة الحالي.

js
const badge = AwnCare.getUnreadCount(); // e.g. 3

hide(): void

إخفاء الودجت تمامًا من العرض.

js
AwnCare.hide(); // remove the widget from view entirely

show(): void

استعادة الودجت بعد hide()، ويُظهر أيضًا زر إطلاق بدأ مخفيًا عبر hideLauncher.

js
AwnCare.show(); // restore it (also reveals a hidden launcher)

destroy(): void

إزالة الودجت من DOM بالكامل.

js
AwnCare.destroy(); // unmount and remove the widget from the DOM

logout(): void

مسح هوية الزائر الحالية — استخدمها عند تسجيل الخروج لبدء جلسة جديدة.

js
// Clear the current visitor identity (e.g. on app sign-out).
AwnCare.logout();

trackEvent(name, data?): void

تسجيل حدث زائر مخصّص مع بيانات اختيارية للسياق والأتمتة.

js
// Record a custom visitor event for context / automations.
AwnCare.trackEvent("checkout_started", { cart: 2, total: 349 });

بيانات ()identify

السمات التي تقبلها AwnCare.identify(). جميع الحقول اختيارية؛ مرّر ما تعرفه.

الحقلالنوعالوصف
namestringالاسم المعروض لجهة الاتصال.
emailstringالبريد الإلكتروني لجهة الاتصال.
phonestringرقم هاتف جهة الاتصال.
externalIdstringمعرّف ثابت من نظامك لربط جهة الاتصال هذه.
companystringاسم شركة جهة الاتصال.
metadataRecord<string, unknown>أي سمات مخصّصة إضافية، تُدمج في سجل الزائر.

الأحداث

اشترك عبر AwnCare.on(name, callback). تستقبل الدوال الحمولة الموضحة أدناه.

الحدثالحمولةالوصف
ready—يُطلَق بمجرد تركيب الودجت وجاهزيته للاستخدام.
open—يُطلَق عند فتح نافذة المحادثة.
close—يُطلَق عند إغلاق نافذة المحادثة.
messageMessageاسم بديل قديم — يُطلَق لكل رسالة من وكيل أو بوت مع كائن الرسالة الكامل.
message:received{ text, sender: "agent" | "bot" }يُطلَق عند وصول رسالة من وكيل أو بوت.
message:sent{ text }يُطلَق عند إرسال الزائر رسالة.
conversation:started{ conversationId }يُطلَق عند إنشاء محادثة جديدة.
unreadnumberيُطلَق عند تغيّر عدد الرسائل غير المقروءة.

ready

js
AwnCare.on("ready", function () {
  console.log("Widget mounted and ready");
});

open

js
AwnCare.on("open", function () {
  console.log("Chat window opened");
});

close

js
AwnCare.on("close", function () {
  console.log("Chat window closed");
});

message

js
// Legacy alias — fires for every agent/bot message (full message object).
AwnCare.on("message", function (message) {
  console.log(message.body, message.sender);
});

message:received

js
AwnCare.on("message:received", function (payload) {
  // payload: { text: string, sender: "agent" | "bot" }
  console.log(payload.sender, "→", payload.text);
});

message:sent

js
AwnCare.on("message:sent", function (payload) {
  // payload: { text: string }
  console.log("Visitor sent:", payload.text);
});

conversation:started

js
AwnCare.on("conversation:started", function (payload) {
  // payload: { conversationId: string }
  console.log("New conversation:", payload.conversationId);
});

unread

js
AwnCare.on("unread", function (count) {
  // count: number — the current unread badge value
  document.title = count > 0 ? "(" + count + ") Support" : "Support";
});