أحداث الويدجت

Callbacks وأحداث للاستجابة لإجراءات المستخدم وتخصيص مسار الحجز.

مقدمة

يُصدر الويدجت أحداثاً في لحظات مختلفة من مسار الحجز. يمكنك الاشتراك في هذه الأحداث عبر callbacks في التكوين الأولي:

JavaScript
SalonBookIt.init({
    apiKey: 'hh_pub_live_...',
    container: '#widget',

    // Callbacks الأحداث
    onReady: (business) => { /* ... */ },
    onStepChange: (step, data) => { /* ... */ },
    onServiceSelect: (service) => { /* ... */ },
    onBookingComplete: (booking) => { /* ... */ },
    onError: (error) => { /* ... */ }
});

مرجع الأحداث

onReady

يتم تشغيله عندما يتم تحميل الويدجت بالكامل ويكون جاهزاً للاستخدام.

المعلمات

المعامل النوع الوصف
business object معلومات النشاط التجاري المحمّل

مثال

JavaScript
onReady: (business) => {
    console.log('النشاط التجاري:', business.nombre);
    console.log('الخدمات المتاحة:', business.servicios_count);

    // تحديث واجهة المستخدم الخارجية
    document.querySelector('.loading').style.display = 'none';
}

الكائن business

JSON
{
    "id": "uuid-del-tenant",
    "nombre": "Mi Salon",
    "telefono": "+34612345678",
    "email": "info@misalon.com",
    "direccion": "Calle Principal 123",
    "logo_url": "https://...",
    "servicios_count": 12,
    "profesionales_count": 5,
    "moneda": "EUR",
    "simbolo_moneda": "€"
}

onStepChange

يتم تشغيله عندما يتقدم المستخدم أو يرجع في مسار الحجز.

المعلمات

المعامل النوع الوصف
step string اسم الخطوة الحالية
data object البيانات المتراكمة حتى الآن

الخطوات المتاحة

  • 'services' - اختيار الخدمات
  • 'staff' - اختيار المحترف
  • 'datetime' - اختيار التاريخ والوقت
  • 'customer' - بيانات العميل
  • 'payment' - الدفع (إذا كان ساري المفعول)
  • 'confirmation' - التأكيد النهائي

مثال

JavaScript
onStepChange: (step, data) => {
    console.log('الخطوة الحالية:', step);

    // Analytics
    gtag('event', 'booking_step', {
        'step_name': step,
        'services_selected': data.services?.length || 0
    });

    // تحديث التنقل الخارجي
    updateBreadcrumbs(step);
}

onServiceSelect

يتم تشغيله عندما يختار المستخدم خدمة أو يلغي اختيارها.

المعلمات

المعامل النوع الوصف
service object الخدمة المختارة
selected boolean إذا تم اختيارها أو إلغاء اختيارها
allSelected array جميع الخدمات المختارة حالياً

مثال

JavaScript
onServiceSelect: (service, selected, allSelected) => {
    console.log(selected ? 'تمت الإضافة:' : 'تمت الإزالة:', service.nombre);

    // تحديث السعر الإجمالي في الواجهة الخارجية
    const total = allSelected.reduce((sum, s) => sum + s.precio, 0);
    document.querySelector('.total-price').textContent = `€${total}`;
}

onStaffSelect

يتم تشغيله عندما يختار المستخدم محترفاً.

مثال

JavaScript
onStaffSelect: (staff) => {
    console.log('المحترف:', staff.nombre);
    // staff = { id, nombre, imagen_url, especialidades }
}

onDateSelect

يتم تشغيله عندما يختار المستخدم تاريخاً ووقتاً.

مثال

JavaScript
onDateSelect: (datetime) => {
    console.log('التاريخ:', datetime.fecha);  // '2024-01-20'
    console.log('الوقت:', datetime.hora);    // '10:30'
}

onBookingComplete

يتم تشغيله عندما يتم إنشاء الحجز بنجاح (قبل الدفع إذا كان ساري المفعول).

مثال

JavaScript
onBookingComplete: (booking) => {
    console.log('تم إنشاء الحجز:', booking.id);

    // Analytics
    gtag('event', 'purchase', {
        'transaction_id': booking.id,
        'value': booking.total,
        'currency': 'EUR'
    });

    // إعادة التوجيه لصفحة التأكيد
    window.location.href = `/reserva-confirmada/${booking.id}`;
}

الكائن booking

JSON
{
    "id": 12345,
    "codigo": "ABC123",
    "fecha": "2024-01-20",
    "hora_inicio": "10:30",
    "hora_fin": "11:00",
    "servicios": [
        { "id": 1, "nombre": "القص الكلاسيكي", "precio": 25.00 }
    ],
    "profesional": {
        "id": 5,
        "nombre": "Carlos Garcia"
    },
    "cliente": {
        "nombre": "Juan Perez",
        "email": "juan@email.com",
        "telefono": "+34612345678"
    },
    "total": 25.00,
    "estado": "مؤكد",
    "pago_pendiente": true
}

onPaymentComplete

يتم تشغيله عندما يكتمل الدفع بنجاح.

مثال

JavaScript
onPaymentComplete: (payment) => {
    console.log('دفع مكتمل');
    console.log('ID:', payment.payment_intent_id);
    console.log('المبلغ:', payment.amount);

    // عرض رسالة النجاح
    showSuccessMessage('تم استلام الدفع!');
}

onError

يتم تشغيله عند حدوث خطأ في أي نقطة من المسار.

مثال

JavaScript
onError: (error) => {
    console.error('Error:', error.code, error.message);

    // الإبلاغ لنظام الأخطاء
    Sentry.captureException(error);

    // عرض رسالة للمستخدم
    if (error.code === 'SLOT_UNAVAILABLE') {
        alert('نعتذر، هذا الموعد لم يعد متاحاً.');
    }
}

رموز الخطأ الشائعة

الرمز الوصف
INVALID_API_KEY مفتاح API غير صالح
NETWORK_ERROR خطأ في الاتصال
SLOT_UNAVAILABLE الموعد لم يعد متاحاً
PAYMENT_FAILED خطأ في الدفع
VALIDATION_ERROR بيانات النموذج غير صالحة

onClose

يتم تشغيله عندما يغلق المستخدم الويدجت (فقط في وضع النافذة المنبثقة).

مثال

JavaScript
onClose: () => {
    console.log('تم إغلاق الويدجت');

    // السؤال عما إذا كان يريد حفظ المسودة
    if (hasUnsavedData()) {
        saveBookingDraft();
    }
}

طرق الويدجت

بالإضافة إلى الأحداث، يمكنك التحكم في الويدجت برمجياً:

JavaScript
// الحصول على مرجع للويدجت
const widget = SalonBookIt.init({ ... });

// فتح النافذة المنبثقة (فقط في وضع modal/button)
widget.open();

// إغلاق النافذة المنبثقة
widget.close();

// الانتقال إلى خطوة محددة
widget.goToStep('services');

// إعادة تشغيل الويدجت
widget.reset();

// تدمير الويدجت
widget.destroy();