يتيح لك Chatwoot Website SDK إرسال معلومات إضافية عن المستخدم إلى Chatwoot.

إذا قمت بتثبيت الكود الخاص بنا على موقعك الإلكتروني، سيقوم الـ SDK بإتاحة كائن `window.$chatwoot`. للتأكد من أن الـ SDK قد تم تحميله بالكامل، يرجى التأكد من الاستماع لحدث `chatwoot:ready` كما يلي:

```
window.addEventListener("chatwoot:ready", function () {
  // استخدم window.$chatwoot هنا
  // ...
});
```

إذا كنت ترغب في الاستماع للرسائل في الودجت، يمكنك استخدام الحدث التالي.

```
window.addEventListener('chatwoot:on-message', function(e) {
  console.log('chatwoot:on-message', e.detail)
})
```

### إعدادات SDK

لإخفاء الفقاعة، يمكنك استخدام الإعداد المذكور أدناه.

**ملاحظة**: إذا استخدمت هذا، يجب عليك تفعيل الودجت أيضًا.

```
window.chatwootSettings = {
  hideMessageBubble: false,
  showUnreadMessagesDialog: false, // تعطيل مربع حوار الرسائل غير المقروءة
  position: "left", // يمكن أن تكون يسار أو يمين
  locale: "en", // اللغة المطلوبة
  useBrowserLanguage: false, // تعيين لغة الودجت من متصفح المستخدم
  type: "standard", // [standard, expanded_bubble]
  darkMode: "auto", // [light, auto]
  // baseDomain: "yourdomain.com" // إعداد إذا كنت تريد تتبع المستخدمين عبر النطاقات الفرعية
};
```

### استخدم لغة المتصفح تلقائيًا في ودجت الدردشة المباشرة

لعرض ودجت الدردشة المباشرة بلغة متصفح المستخدم، عيّن `useBrowserLanguage` إلى `true` في `window.chatwootSettings` كما في الأعلى.

**ملاحظة**: إذا تم تعيين `useBrowserLanguage` إلى `true`، سيتم تجاهل `locale` المذكور. إذا كانت لغة المتصفح غير مدعومة من chatwoot، سيتم استخدام اللغة المذكورة تحت `locale`. إذا لم يتم تحديدها أيضًا، سيعود الودجت إلى لغة لوحة تحكم الوكيل.

### الوضع الداكن

يدعم ودجت الدردشة المباشرة من Chatwoot الوضع الداكن بدءاً من الإصدار v2.4.0. لتمكين الوضع الداكن، اتبع الخطوات المذكورة [هنا](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/live-chat-dark-mode).

### تصاميم الودجت

يدعم Chatwoot تصميمين للودجت.

1. القياسي (الافتراضي)

   ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBeEpVVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cd7e6b995894f8afbcc4a48f8e159ae4e3a1a04b/standard-bubble-chatwoot-live-chatwoot.gif)

2. الفقاعة الموسّعة

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBeE5VVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--2b40967d868bb213b2d4e541ca3ed0e82c7222d0/expanded-bubble-chatwoot-live-chatwoot.gif)

إذا كنت تستخدم الفقاعة الموسعة، يمكنك تخصيص النص المعروض في الفقاعة عن طريق تعيين الوسيط `launcherTitle` على chatwootSettings كما هو موضح أدناه.

```
window.chatwootSettings = {
  type: "expanded_bubble",
  launcherTitle: "تحدث معنا",
};
```

### تفعيل نافذة منبثقة

لتمكين النافذة المنبثقة، أضف التكوين التالي إلى `chatwootSettings`. هذا الخيار معطل افتراضياً.

```
window.chatwootSettings = {
  // ...إعدادات أخرى
  showPopoutButton: true,
}

يمكنك أيضاً فتح نافذة الدردشة برمجياً بواسطة الطريقة `popoutChatWindow()`.
```

### رسائل مخصصة

خصص رسائل الترحيب ورسائل التوافر التي تظهر في رأس الودجت ومؤشرات حالة الفريق.

```
window.chatwootSettings = {
  // ...إعدادات أخرى

  welcomeTitle: "هل تحتاج للمساعدة؟", // رأس الودجت المخصص
  welcomeDescription: "نحن هنا لدعمك.", // العنوان الفرعي للرأس
  availableMessage: "نحن متصلون وجاهزون للدردشة!", // عندما يكون الفريق متصل
  unavailableMessage: "نحن غير متصلين حالياً." // عندما يكون الفريق غير متصل
};
```

### تبديل الميزات

تفعيل أو تعطيل ميزات واجهة المستخدم الاختيارية داخل الودجت:

```
window.chatwootSettings = {
  // ...إعدادات أخرى

  enableFileUpload: true, // إظهار زر إرفاق الملفات
  enableEmojiPicker: true, // تمكين منتقي الرموز التعبيرية في الدردشة
  enableEndConversation: true // السماح للمستخدمين بإنهاء المحادثة
};
```

### فتح النافذة المنبثقة برمجياً

يمكنك فتح النافذة المنبثقة برمجياً باستخدام `popoutChatWindow()`.

لبدء ذلك، استدعِ الطريقة كما يلي.

```
window.$chatwoot.popoutChatWindow();
```

### تبديل ظهور فقاعة الودجت

إذا كنت ترغب في إظهار/إخفاء فقاعة ودجت Chatwoot، يمكنك فعل ذلك باستخدام `toggleBubbleVisibility('show/hide')`

مثال

```
window.$chatwoot.toggleBubbleVisibility("show"); // لإظهار الفقاعة
window.$chatwoot.toggleBubbleVisibility("hide"); // لإخفاء الفقاعة
```

### تفعيل الودجت برمجياً

إذا كنت ترغب في فتح نافذة الدردشة عند النقر على رابط بالموقع، اتبع الطريقة أدناه. في الإجراء الخاص بك، استدعِ الـ SDK الخاص بـ Chatwoot كما هو موضح بالأسفل.

```
window.$chatwoot.toggle();

// تبديل الودجت عبر تمرير الحالة
window.$chatwoot.toggle("open"); // لفتح الودجت
window.$chatwoot.toggle("close"); // لإغلاق الودجت
```

### تعيين المستخدم في الودجت

```
window.$chatwoot.setUser("<unique-identifier-key-of-the-user>", {
  email: "<email-address-of-the-user@your-domain.com>",
  name: "<name-of-the-user>",
  avatar_url: "<avatar-url-of-the-user>",
  phone_number: "<phone-number-of-the-user>",
});
```

تقبل `setUser` معرّف يمكن أن يكون `user_id` في قاعدة بياناتك أو أي وسيط فريد يمثّل المستخدم. يمكنك تمرير البريد الإلكتروني، الاسم، avatar_url، رقم الهاتف كمعاملات. دعم المعاملات الإضافية قيد التطوير.

تأكد من إعادة تعيين الجلسة عندما يقوم المستخدم بتسجيل الخروج من تطبيقك.

### التحقق من الهوية باستخدام HMAC

لحماية المحادثات مع العملاء ومنع انتحال الهوية، ننصح بإعداد التحقق من الهوية في Chatwoot. يتم تفعيل التحقق من الهوية عن طريق إنشاء HMAC (توقيع توثيق الرسائل) بناءً على خاصية `identifier`، باستخدام SHA256. بجانب `identifier` يمكنك تمرير `identifier_hash` أيضاً كما هو موضح أدناه للتأكد من صحة المستخدم.

```
window.$chatwoot.setUser(`<unique-identifier-key-of-the-user>`, {
  name: "", // اسم المستخدم
  avatar_url: "", // رابط الصورة الرمزية
  email: "", // البريد الإلكتروني للمستخدم
  identifier_hash: "", // هاش المعرف الذي يتم إنشاؤه بناءً على webwidget hmac_token
  phone_number: "", // رقم هاتف المستخدم
  description: "", // وصف عن المستخدم
  country_code: "", // رمز الدولة من حرفين
  city: "", // مدينة المستخدم
  company_name: "", // اسم الشركة
  social_profiles: {
    twitter: "", // اسم المستخدم في تويتر
    linkedin: "", // اسم المستخدم في لينكدإن
    facebook: "", // اسم المستخدم في فيسبوك
    github: "", // اسم المستخدم في جيتهاب
  },
});
```

لإنشاء HMAC، اطلع على [التحقق من الهوية](https://www.chatwoot.com/docs/product/channels/live-chat/sdk/identity-validation). لاحظ أن تطبيق توثيق HMAC سيسمح باستمرار سجل الدردشة عبر الجلسات.

### تعيين حقول مخصصة

لتعيين معلومات إضافية عن العميل، يمكنك استخدام حقول السِمات المخصصة للعميل. اقرأ المزيد عن الحقول المخصصة [هنا](https://www.chatwoot.com/hc/user-guide/articles/1788726269-).

لتعيين حقل مخصص، استدعِ `setCustomAttributes` كما يلي

```
window.$chatwoot.setCustomAttributes({
  accountId: 1,
  pricingPlan: "paid",

  // هنا المفتاح يجب أن يكون معرف مسبقاً في السمة المخصصة
  // يجب أن تكون القيمة حسب النوع (حاليًا يدعم الرقم، التاريخ، النص والرقم)
});
```

يمكنك رؤية هذه المعلومات في اللوحة الجانبية للمحادثة.

لحذف حقل مخصص، استخدم `deleteCustomAttribute` كما يلي

```
window.$chatwoot.deleteCustomAttribute("attribute-key");
```

### تعيين اللغة يدويًا

```
window.$chatwoot.setLocale("en");
```

لتعيين اللغة يدويًا، استخدم دالة `setLocale`.

### تعيين تصنيفات على المحادثة

يرجى ملاحظة أن التصنيفات سيتم تعيينها على المحادثة إذا لم يقم المستخدم ببدء محادثة حتى الآن. في هذه الحالة، لن يكون للتعليمات التالية أي تأثير:

```
window.$chatwoot.setLabel("support-ticket");

window.$chatwoot.removeLabel("support-ticket");
```

### تحديث الجلسة (استخدم هذا عند تسجيل خروج المستخدم من تطبيقك)

```
window.$chatwoot.reset();
```

### أخطاء الودجت

لرؤية أي أخطاء في الودجت، يرجى التأكد من الاستماع لحدث `chatwoot:event` كما هو موضح:

```
window.addEventListener("chatwoot:error", function () {
  // ...
});
```

ملاحظة: هذه الميزة متوفرة في الإصدار v2.3.0 وما بعده.

### تخصيص رأس الترحيب والوصف

يمكنك تغيير:

* عنوان الترحيب والوصف

* الرسائل التي تظهر عند تواجد فريقك أونلاين أو أوفلاين

* تفعيل ميزات واجهة المستخدم بشكل اختياري مثل رفع الملفات، منتقي الرموز التعبيرية، وزر إنهاء المحادثة

```
window.chatwootSettings = {
  welcomeTitle: 'هل تحتاج للمساعدة؟',
  welcomeDescription: 'نحن هنا لدعمك.',
  availableMessage: 'نحن متصلون وجاهزون للدردشة!',
  unavailableMessage: 'نحن غير متصلين حالياً.',

  enableFileUpload: true,
  enableEmojiPicker: true,
  enableEndConversation: true
 };
```