أحداث الويدجت
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();