دليل الإعداد

بدء سريع

1. انسخ مفتاح موقعك (يبدأ بـ cd_) من لوحة التحكم ضمن الإعدادات ← التثبيت.
2. أضف الشيفرة الموجودة أعلى هذه الصفحة إلى جميع صفحات موقعك، قبل الوسم </body> مباشرة. ضع مفتاحك مكان SITE_KEY.
3. أعد تحميل الصفحة؛ يظهر زر الدردشة في الزاوية السفلية. ما دمت متصلًا في لوحة التحكم يستطيع الزوار مراسلتك.

لا تبطئ الشيفرة صفحتك: المحمِّل صغير ومخزَّن مؤقتًا، والأداة تُحمَّل منفصلة وبإصدار محدد. وإذا تعذّر الوصول إلى خادمنا يظهر زر بسيط يقود إلى العنوان الذي تكتبه في الإعدادات ← عام ← رابط تواصل احتياطي.

ووردبريس

للتثبيت دون شيفرة نزّل الإضافة. تضيف الإضافة أداة الدردشة، ويمكنها إن شئت تعريف أعضائك المسجّلين بهوية موقّعة.

تنزيل إضافة ووردبريس

1. في لوحة إدارة ووردبريس ارفع ملف zip من الإضافات ← أضف جديد ← رفع إضافة ثم فعّلها.
2. الصق مفتاح موقعك في صفحة الإعدادات ← Layvchat.
3. اختياري: فعّل هوية العضو وأدخل مفتاح التوقيع السري (في لوحة التحكم: الإعدادات ← معرّف الزائر ← إظهار المفتاح السري).

متوافقة مع إضافات التخزين المؤقت: لا تُكتب هوية العضو في HTML الصفحة، بل تُجلب لكل زائر بطلب مستقل غير مخزَّن. ويبقى مفتاح التوقيع على خادم موقعك.

التحكم في الأداة بالشيفرة

تضيف شيفرة التثبيت الكائن window.layvchat إلى الصفحة. يمكن استخدام الأوامر فور تحميل الشيفرة: إذا لم تكن الأداة جاهزة بعد تُؤجَّل الاستدعاءات وتُنفَّذ عند جاهزيتها. لكل أمر اسم تركي أيضًا (مثلًا open = ac) وكلاهما يعمل.

الأوامر

// "Ask about this product" button
document.querySelector('#ask-product').addEventListener('click', function () {
  window.layvchat.prefill('مرحبًا، أود معرفة المزيد عن "الحقيبة الجلدية".')
})

// Show the signed-in member and their cart to the agent
window.layvchat.setVisitor({ ad: 'سارة أحمد', eposta: '[email protected]' })
window.layvchat.setAttributes({ 'السلة': '499 ر.س', 'العضوية': 'ذهبية' })

بيانات setVisitor وsetAttributes تأتي من المتصفح وغير موقّعة؛ وتعرضها لوحة التحكم على أنها غير موثّقة. لتعريف حساب العضو بأمان استخدم هوية الزائر.

الأحداث

window.layvchat.on('chatStarted', function () {
  gtag('event', 'live_chat_started')        // analytics
})
window.layvchat.on('message', function (m) {
  if (m.kim === 'ajan') console.log(m.ajan + ': ' + m.metin)
})

// The same events are also dispatched on window (English and Turkish names)
window.addEventListener('layvchat:unread', function (e) { badge(e.detail.n) })

إذا كانت شيفرتك تعمل قبل شيفرة التثبيت فأضف الاستدعاءات إلى الطابور:

(window.layvchatKuyruk = window.layvchatKuyruk || []).push(['open'], ['setAttributes', { 'Page': 'Checkout' }])

متغيرات CSS

يمكن تجاوز موضع الزر وترتيب طبقته من CSS موقعك؛ وتتموضع النافذة بالنسبة إلى الزر. استخدمها إذا تداخلت الأداة مع شريط ملفات تعريف الارتباط أو شريط التنقل السفلي على الجوال.

@media (max-width: 768px) {
  :root { --layvchat-alt: 84px; }   /* stay above the mobile bottom bar */
}

إن كنت تستخدم Tawk.to أو Comm100 سابقًا، فإن استدعاءاتك الحالية Tawk_API.maximize() وComm100API.do('livechat.button.click') تفتح نافذة Layvchat أيضًا؛ لا حاجة إلى تغيير أزرارك.

هوية الزائر

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

تُثبَت الهوية بتوقيع يُنشأ على خادم موقعك، فلا يستطيع أحد انتحال عضو آخر من المتصفح. احصل على مفتاح التوقيع من لوحة التحكم عبر الإعدادات ← معرّف الزائر ← إظهار المفتاح السري واحفظه على خادمك فقط.

التوقيع

imza = HMAC-SHA256(secret, id + "|" + username + "|" + zaman)   → lowercase hex (64 characters)

ثلاث طرق لتمرير الهوية إلى الأداة

1. كتابتها في الصفحة. إذا كنت تُنشئ الصفحات على الخادم فأضف هذا قبل شيفرة التثبيت. لا تستخدم هذه الطريقة مع التخزين المؤقت للصفحات؛ فقد يُقدَّم توقيع عضو لزوار آخرين.

<script>
  window.layvchatKimlik = { id: "123", username: "sara", zaman: 1760000000, imza: "…" }
</script>

2. الإبلاغ عند تسجيل الدخول والخروج. مناسبة لتطبيقات الصفحة الواحدة (React وVue…). ولأن التوقيع صالح ساعتين، استدعِها مجددًا بتوقيع جديد في الصفحات التي تبقى مفتوحة طويلًا.

window.layvchat.identify({ id: "123", username: "sara", zaman: 1760000000, imza: "…" })
window.layvchat.identify(null)   // after sign-out

3. نقطة نهاية الهوية. في لوحة التحكم ضمن الإعدادات ← معرّف الزائر ← نقطة نهاية الهوية اكتب عنوانًا نسبيًا في موقعك يعيد الهوية الموقّعة (مثلًا /layvchat/identity). تقرأه الأداة من الأصل نفسه مع ملفات تعريف الارتباط، وتحدّثه عند تحميل الصفحة وكل 15 ثانية وعند العودة إلى التبويب وعند التنقل داخل الصفحة. للزائر غير المسجّل أعد {"id": null}؛ والرد غير JSON أو الفاشل يُعدّ "خروجًا".

<?php // /layvchat/identity
session_start();
header('Content-Type: application/json');
header('Cache-Control: no-store');
$secret = getenv('LAYVCHAT_IDENTITY_SECRET');
if (empty($_SESSION['member_id'])) { echo json_encode(['id' => null]); exit; }
$id = (string) $_SESSION['member_id'];
$name = (string) $_SESSION['member_username'];
$time = time();
echo json_encode([
  'id' => $id, 'username' => $name, 'zaman' => $time,
  'imza' => hash_hmac('sha256', "$id|$name|$time", $secret),
]);

// Express — /layvchat/identity
import crypto from 'node:crypto'
app.get('/layvchat/identity', (req, res) => {
  res.set('Cache-Control', 'no-store')
  const member = req.session?.member
  if (!member) return res.json({ id: null })
  const id = String(member.id), name = String(member.username), time = Math.floor(Date.now() / 1000)
  const imza = crypto.createHmac('sha256', process.env.LAYVCHAT_IDENTITY_SECRET).update(`${id}|${name}|${time}`).digest('hex')
  res.json({ id, username: name, zaman: time, imza })
})

# Flask — /layvchat/identity
import hmac, hashlib, os, time
from flask import jsonify, session

@app.get("/layvchat/identity")
def layvchat_identity():
    if "member_id" not in session:
        response = jsonify(id=None)
    else:
        uid, name, ts = str(session["member_id"]), str(session["member_username"]), int(time.time())
        imza = hmac.new(os.environ["LAYVCHAT_IDENTITY_SECRET"].encode(), f"{uid}|{name}|{ts}".encode(), hashlib.sha256).hexdigest()
        response = jsonify(id=uid, username=name, zaman=ts, imza=imza)
    response.headers["Cache-Control"] = "no-store"
    return response

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

سياسة أمان المحتوى (CSP)

إذا كان موقعك يستخدم CSP فاسمح بعنوان Layvchat كما يلي:

script-src   {{KOK}}
connect-src  {{KOK}} {{WS}}     ('self' too if you use an identity endpoint)
frame-src    {{KOK}}
style-src    'unsafe-inline'
img-src      https:            (only with a custom button image)
media-src    {{KOK}}           (only with a custom notification sound)

لا تُنشئ الأداة ملفات تعريف ارتباط في موقعك. يُحفظ مفتاح الزائر والرابط الاحتياطي في localStorage بالبادئة layv_cd_؛ ويبقى محتوى المحادثة ورمز الوصول في الأصل الخاص بنافذة Layvchat فقط.

التكامل مع الموقع Pro

أثناء المحادثة يرى موظفو الدعم بيانات حساب الزائر الموثّق (الطلبات الأخيرة، الحالة…) ويمكنهم تنفيذ الإجراءات التي تسمح بها. يجلب Layvchat هذه البيانات من بضع نقاط نهاية على خادمك بطلبات موقّعة. يعمل التكامل مع الزوار الموثّقين فقط.

1. أنشئ نقاط النهاية أدناه على خادمك (مثلًا تحت https://yoursite.com/layvchat-api).
2. أدخل هذا العنوان في لوحة التحكم ضمن الإعدادات ← التكامل مع الموقع. يُعرض مفتاح التوقيع (يبدأ بـ entg_) مرة واحدة فقط؛ احفظه على خادمك.
3. امنح الموظفين الصلاحيات اللازمة من الإعدادات ← موظفو الدعم (عرض البيانات، الملاحظات، الحظر).

الطلبات

:id هو قيمة id في هوية الزائر. وyapan هو الموظف الذي نفّذ الإجراء (canli-destek:username).

تحقّق من التوقيع

يصل كل طلب مع الترويستين X-Imza-Zaman (ثواني يونكس) وX-Imza:

X-Imza = HMAC-SHA256(secret, time + "." + METHOD + "." + fullPath + "." + rawBody)   → lowercase hex

fullPath هو مسار الطلب متضمّنًا مسار عنوانك: إذا كان العنوان https://yoursite.com/layvchat-api فهو /layvchat-api/uye/42. في طلبات GET يكون المحتوى نصًا فارغًا. ارفض الطوابع الزمنية الأقدم من 5 دقائق.

<?php
function layvchat_verify(string $secret): bool {
  $time = $_SERVER['HTTP_X_IMZA_ZAMAN'] ?? '';
  $sig  = $_SERVER['HTTP_X_IMZA'] ?? '';
  if (!ctype_digit($time) || abs(time() - (int) $time) > 300) return false;
  $body = file_get_contents('php://input');
  $expected = hash_hmac('sha256', $time . '.' . $_SERVER['REQUEST_METHOD'] . '.' . $_SERVER['REQUEST_URI'] . '.' . $body, $secret);
  return hash_equals($expected, $sig);
}

// Express: needs the raw body → app.use(express.json({ verify: (req, _r, buf) => { req.rawBody = buf.toString() } }))
import crypto from 'node:crypto'
function layvchatVerify(req, secret) {
  const time = req.get('x-imza-zaman') || '', sig = req.get('x-imza') || ''
  if (!/^\d+$/.test(time) || Math.abs(Date.now() / 1000 - Number(time)) > 300) return false
  const expected = crypto.createHmac('sha256', secret)
    .update(`${time}.${req.method}.${req.originalUrl}.${req.rawBody || ''}`).digest('hex')
  return expected.length === sig.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))
}

رد بطاقة العميل

يجب أن يعيد GET /uye/:id كائن JSON. الحقل uye.id وحده إلزامي؛ وتُتجاهل الحقول غير المعروفة. إذا لم يكن العضو موجودًا فأعد 404.

{
  "uye": {
    "id": "42", "kullaniciAdi": "sara", "ad": "سارة", "soyad": "أحمد",
    "eposta": "[email protected]", "telefon": "5551112233", "ulke": "SA", "paraBirimi": "SAR",
    "toplamHarcama": 5000, "toplamIade": 320,
    "durum": "aktif", "kayitTarihi": "2025-03-14T10:00:00Z", "sonGiris": "2026-10-04T21:10:00Z",
    "riskEtiketleri": ["حساب جديد"]
  },
  "sonIslemler": [
    { "id": "S1001", "tur": "siparis", "tutar": 500, "durum": "تم الشحن", "aciklama": "منتجان", "zaman": "2026-10-04T20:00:00Z" }
  ]
}

في طلبات POST أعد عند النجاح 2xx وكائن JSON (مثلًا {"ok": true}). وللرفض أعد {"hata": "short_code"}. يظهر 404 للموظف بعبارة "غير موجود"، وبقية رموز الخطأ بعبارة "أعاد الموقع خطأ".

تُرسل الطلبات عبر https فقط إلى المنفذ 443 وإلى عناوين عامة على الإنترنت؛ ولا تُتبع إعادات التوجيه. المهلة 10 ثوانٍ، والرد بحد أقصى 512 كيلوبايت.

الويب هوك Pro

أرسل أحداث المحادثة إلى أنظمتك (إدارة العملاء، الإشعارات، التقارير) فورًا. اختر العنوان والأحداث من لوحة التحكم ضمن الإعدادات ← Webhooks وAPI؛ ويُعرض مفتاح التوقيع (يبدأ بـ whsec_) مرة واحدة.

{
  "id": "6f1c…",                 // delivery ID — stays the same on retries
  "olay": "sohbet.bitti",          // event
  "zaman": "2026-10-05T09:12:00.000Z",
  "deneme": 1,                     // attempt
  "veri": {
    "konusma": {                   // conversation
      "id": "…", "durum": "kapandi", "kaynak": "ziyaretci",
      "baslatildi": "…", "kapandi": "…", "kapanisSebep": "kapatildi",
      "ziyaretci": { "no": 128, "ad": "سارة", "kullaniciAdi": "sara", "uyeId": "42", "ulke": "SA" },
      "ajan": "خالد", "etiketler": ["دفع"], "puan": 5
    }
  }
}

لا يُملأ kullaniciAdi (اسم المستخدم) وuyeId (معرّف العضو) إلا للزوار الموثّقين.

الترويسات والتوقيع

<?php
$body = file_get_contents('php://input');
$time = $_SERVER['HTTP_X_IMZA_ZAMAN'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $time . '.' . $body, getenv('LAYVCHAT_WEBHOOK_SECRET'));
if (!ctype_digit($time) || abs(time() - (int) $time) > 300 || !hash_equals($expected, $_SERVER['HTTP_X_IMZA_IMZA'] ?? '')) {
  http_response_code(401); exit;
}
$event = json_decode($body, true);
// skip if $event['id'] was already processed; then return 2xx
http_response_code(204);

import crypto from 'node:crypto'
app.post('/layvchat/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const time = req.get('x-imza-zaman') || '', raw = req.body.toString()
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.LAYVCHAT_WEBHOOK_SECRET).update(`${time}.${raw}`).digest('hex')
  const sig = req.get('x-imza-imza') || ''
  const valid = /^\d+$/.test(time) && Math.abs(Date.now() / 1000 - Number(time)) <= 300 &&
    sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
  if (!valid) return res.sendStatus(401)
  const event = JSON.parse(raw)
  // skip if event.id was already processed
  res.sendStatus(204)
})

أعد 2xx خلال 8 ثوانٍ؛ وضع الأعمال الثقيلة في طابور. يُعاد التسليم الفاشل بعد 5 ث و30 ث ودقيقتين (4 محاولات كحد أقصى). وبعد 20 محاولة فاشلة متتالية يُعطَّل الويب هوك؛ ويمكنك في لوحة التحكم رؤية آخر 50 تسليمًا وإرسال تجربة بزر "اختبار". يجب أن يكون العنوان https على المنفذ 443 ومتاحًا على الإنترنت.

واجهة REST Pro

اسحب التقارير والمحادثات إلى أنظمتك. أنشئ مفتاحًا في لوحة التحكم ضمن الإعدادات ← Webhooks وAPI ← مفاتيح API (لمالك مساحة العمل فقط)؛ ويُعرض المفتاح السري مرة واحدة. حتى 5 مفاتيح نشطة؛ ولكل مفتاح قائمة عناوين IP مسموح بها. المفاتيح للقراءة فقط.

curl -u "layv_…:layvs_…" "{{KOK}}/api/v1/canli/rapor?gun=7"

الكائن konusma هو نفسه في الويب هوك. رموز الخطأ: 401 المفتاح مفقود أو غير صالح (لا يُذكر السبب لدواعٍ أمنية) · 402 باقتك لا تتضمن API · 404 المحادثة غير موجودة.

حل المشكلات

لا يظهر زر الدردشة

تحقّق من مفتاح الموقع (يبدأ بـ cd_). قد يكون الإعدادات ← عام ← الدعم المباشر مفعّل متوقفًا في لوحة التحكم، أو الإعدادات ← مظهر أداة الدردشة ← إخفاء على الجوال مفعّلًا. وإذا كان موقعك يستخدم CSP فأضف الأذونات. في وحدة تحكم المتصفح انظر إلى رد الطلب /cd/v/ayar: الرمز 404 يعني أن المفتاح غير معروف.

لا يظهر الزائر موثّقًا

أشهر الأسباب: إرسال zaman بالمللي ثانية (يجب أن يكون بالثواني)، أو توقيع بأحرف كبيرة، أو ساعة خادم خاطئة، أو اختلاف اسم المستخدم الموقّع عن المرسل، أو احتواء id على أحرف غير مسموح بها. التوقيع صالح ساعتين؛ جدّده في الصفحات التي تبقى مفتوحة طويلًا.

لا تصل أحداث الويب هوك

راجع سجل التسليم في لوحة التحكم ضمن الإعدادات ← Webhooks وAPI. يجب أن يكون العنوان https وأن يعيد 2xx خلال 8 ثوانٍ ودون إعادة توجيه. بعد 20 خطأ متتاليًا يُعطَّل الويب هوك؛ أعد تفعيله بعد الإصلاح.

لا تُفتح بطاقة العميل

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