ويدجت صندوق الوارد للويب

إن دمج صندوق رسائل الويب في موقعك الإلكتروني يزيد من التحويلات بشكل كبير. يتوفر ويدجت صندوق الوارد للويب جاهز للاستخدام ومشترك بشكل افتراضي في جميع الطرق اللازمة للتواصل مع المستخدمين. ما عليك سوى دمج الويدجت في موقعك الإلكتروني وتخصيص مظهره ليتناسب مع علامتك التجارية.

يؤدي تعيين inboxWidget.enable: true إلى تسجيل جهاز الزائر لتسليم رسائل صندوق الوارد حتى لو لم يمنح الزائر إذن إشعارات الدفع، لذلك يمكنه الوصول إلى الزوار الذين لم يشتركوا أبدًا في إشعارات الدفع.

ملاحظة هامة حول إصدارات SDK (v3.66.0+)

بدءًا من الإصدار 3.66.0، يتم تتبع جهاز الزائر بواسطة معرف الجهاز (hardware ID) المرتبط بمتصفحه قبل تسجيل الدخول. إذا قام الزائر بمسح بيانات الموقع، أو تغيير المتصفحات، أو تغيير الأجهزة قبل استدعاء registerUser، فإن هذا التتبع ينقطع. يتم فقدان سجل رسائله السابقة ولا يتم نقله حتى بعد تسجيل دخول الزائر.

المتطلبات الأساسية

لدمج صندوق الرسائل للمواقع الإلكترونية، يرجى اتباع الدليل.

دمج الويدجت

عند تهيئة Pushwoosh WebSDK، أضف المعلمة inboxWidget:

مثال

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox'
  }
}]);

المشغّل (Trigger)

لعرض الويدجت، يجب عليك تحديد عنصر مشغّل للويدجت. يمكن أن يكون أي عنصر DOM في الصفحة هو المشغّل. حدد معرّفه (ID) كـ “pwInbox” أو قم بتعيين أي معرّف مخصص للمعلَمة triggerId عند تهيئة SDK. عند تهيئة WebSDK، يتم عرض شارة الرسائل غير المقروءة على عنصر المشغّل. بمجرد النقر على عنصر المشغّل، يظهر الويدجت على الصفحة.

تحديد الموضع

بشكل افتراضي، يتم وضع الويدجت في الاتجاه المعاكس من حافة الشاشة الأقرب إلى عنصر المشغّل. يمكنك تعيين موضع الويدجت من خلال معلمات التكوين:

مثال

Pushwoosh.push(['init', {

  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    position: 'top'
  }
}]);

بشكل افتراضي، يجب وضع inboxWidget قبل وسم الإغلاق </body>. اعرض الويدجت في أي مكان على الصفحة كما هو موضح في المثال أدناه:

مثال

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {

    enable: true,
    triggerId: 'pwInbox',
    appendTo: '.widget-parent-element-class'
  }
}]);

يتم البحث عن عنصر أصل بواسطة querySelector، لذلك يحتاج إلى تحديد واضح للفئة (class) أو المعرّف (id) أو العنصر.

تخصيص الويدجت

تخصيص النصوص

لتخصيص نص الويدجت، أضف المعلمتين emptyInboxTitle و emptyInboxText:

مثال

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    title: 'Inbox',                                 // عنوان الويدجت
    emptyInboxTitle: 'You\'re all caught up',       // عنوان ويدجت صندوق الوارد الفارغ
    emptyInboxText: 'There are no new messages. Stay tuned!'    // نص ويدجت صندوق الوارد الفارغ
  }
}]);

النتيجة تبدو هكذا:

تخصيص المظهر

لتخصيص مظهر الويدجت، استخدم المعلمات التالية:

مثال

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    bgColor: '#ffffff',         // خلفية الويدجت
    borderColor: 'transparent', // لون إطار الويدجت
    borderRadius: 4,            // نصف قطر إطار الويدجت (px)
    widgetWidth: 350,           // عرض الويدجت (px)
    zIndex: 100                 // z-index
  }
}]);

يمكن تخصيص شارة عدد الرسائل غير المقروءة كما يلي:

مثال

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    badgeBgColor: '#ff4c00',    // لون الشارة
    badgeTextColor: '#ffffff'   // لون نص الشارة
  }
}]);

لتخصيص خصائص النص، أضف الكود التالي:

مثال

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    textColor: '#333333',                       // لون النص
    fontFamily: 'Helvetica, Arial, sans-serif', // الخط
    messageTitleColor: '#7a7a7a',               // لون عنوان الرسائل
    timeTextColor: '#c4c4c4',                   // لون نص الطابع الزمني
    emptyInboxTitleColor: '#333333',            // لون عنوان صندوق الوارد الفارغ
    emptyInboxTextColor: '#7a7a7a'              // لون نص صندوق الوارد الفارغ
  }
}]);

أخيرًا، يمكنك تحديد أيقونة صندوق الوارد الفارغ:

مثال

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    emptyInboxIconUrl: 'https://pushon.pushwoosh.com/images/icon-empty-inbox.png'   // مسار URL للأيقونة
  }
}]);

تخصيص تخطيطات الخلايا

يعرض الويدجت الرسالة كواحد من أربعة تخطيطات للخلايا — classic، banner، captioned، أو carousel — وهي نفس التخطيطات التي تظهر في معاينة الحملة في لوحة التحكم. التخطيط الذي لا يمكن عرضه بما تحمله الرسالة يتحول إلى classic: يتطلب banner صورة رئيسية، ويتطلب captioned صورة رئيسية بالإضافة إلى عنوان ونص، ويتطلب carousel شريحة واحدة على الأقل بالإضافة إلى عنوان ونص.

لتخصيص مظهر التخطيطات، استخدم المعلمات التالية:

مثال

Pushwoosh.push(['init', {
  ...,
  inboxWidget: {
    enable: true,
    triggerId: 'pwInbox',
    unreadDotColor: '#ff4c00',    // نقطة غير مقروءة على الصورة الرمزية الكلاسيكية
    avatarBgColor: '#e6e6e6',     // خلفية الصورة الرمزية الكلاسيكية
    avatarTextColor: '#333333',   // لون الحرف الأول في الصورة الرمزية الكلاسيكية
    avatarSize: 52,               // حجم الصورة الرمزية الكلاسيكية (px)
    mediaRadius: 8,               // نصف قطر زاوية وسائط banner/captioned/carousel (px)
    slideCaptionColor: '#ffffff', // لون نص تعليق شريحة carousel
    slideScrimColor: '#000000',  // خلفية تعتيم تعليق شريحة carousel
    pagerDotActiveColor: '#ff4c00', // نقطة الصفحة النشطة في carousel
    pagerDotColor: '#c4c4c4'      // نقاط الصفحة غير النشطة في carousel
  }
}]);

استعادة الخلية الكلاسيكية لما قبل الإصدار 3.75

قم بتعيين inboxWidget.legacyClassicCell: true للحفاظ على المظهر السابق للخلية الكلاسيكية — عمود أيقونة بحجم 40 بكسل بدلاً من الصورة الرمزية المستديرة بحجم 52 بكسل، بدون نقطة غير مقروءة، ونص غير مقيد. لا تتأثر تخطيطات banner و captioned و carousel بهذا الخيار.

إدارته في Control Panel

المتطلبات

• يحمّل الموقع Web SDK من شبكة CDN الخاصة بـ Pushwoosh، كما تذكر البطاقة. تعمل البطاقة أيًا كان Settings source، سواء كان مقتطف init في موقعك أو هذه الصفحة (انظر Web Push SDK 3.0)، لكن إصدار SDK المطلوب يعتمد على هذا المصدر:
  • مقتطف init في موقعك: Web SDK 3.93.1 أو أحدث. يتجاهل SDK الأقدم البطاقة ويقرأ inboxWidget من المقتطف فقط.
  • هذه الصفحة: Web SDK 3.92 أو أحدث لقيم البطاقة، و3.93.0 أو أحدث لإيقاف التشغيل في npm الموضح أدناه.
• تحتوي الصفحة على العنصر الذي يفتح صندوق الوارد، وهو #pwInbox افتراضيًا. إذا كان مفقودًا، فلن يُفتح صندوق الوارد، وتعرض وحدة تحكم المتصفح الخطأ Error during Pushwoosh initialization الذي يسمّي العنصر المفقود ويوضح أين يمكن تغيير معرّفه.
• في موقع يثبّت SDK من npm، يمكن للبطاقة إيقاف الويدجت لكن لا يمكنها تشغيله، لأن الموقع هو من ينشئ الويدجت بنفسه.

لإعداد الويدجت من Control Panel:

1. انتقل إلى Settings → Configure platforms → Web.

2. في بطاقة Inbox widget، انقر على Configure.

   

3. شغّل Show the inbox on the site.

4. املأ الحقول التي تريد إدارتها من اللوحة، واترك الباقي فارغًا. لا يُحفظ الحقل الفارغ، لذلك تظل قيمة المقتطف، أو القيمة الافتراضية في SDK، سارية. اترك ID of the element that opens the inbox وInsert into (CSS selector) فارغين للإبقاء على triggerId وappendTo في المقتطف بجانب الترميز الذي يشيران إليه.

5. تحقق من النتيجة في المعاينة. بدّل بين With messages وNo messages لرؤية الحالتين.

   

6. احفظ النموذج. يقبل Width, px عددًا صحيحًا من 200 إلى 1200، ويقبل Corner radius, px عددًا صحيحًا من 0 إلى 64. أي قيمة أخرى تعرض خطأً أسفل الحقل ولا تُحفظ.

كيف تعمل البطاقة مع المقتطف

القيم المحفوظة في البطاقة تتجاوز مفاتيح inboxWidget نفسها في مقتطف init، مفتاحًا بمفتاح. يضبط كل حقل مفتاحًا واحدًا:

القسم	الحقل	مفتاح inboxWidget
Placement	ID of the element that opens the inbox	triggerId
Placement	Opens	position
Placement	Insert into (CSS selector)	appendTo
Texts	Widget title	title
Texts	Title when there are no messages	emptyInboxTitle
Texts	Text when there are no messages	emptyInboxText
Texts	Image when there are no messages (URL)	emptyInboxIconUrl
Appearance	Width, px (200–1200)	widgetWidth
Appearance	Corner radius, px (0–64)	borderRadius
Appearance	Font	fontFamily
Appearance	Background, Text, Border	bgColor, textColor, borderColor
Appearance	Counter background, Counter text, Unread mark	badgeBgColor, badgeTextColor, unreadDotColor

أما المفاتيح غير الموجودة في البطاقة، مثل معلمات تخطيط الخلايا وlegacyClassicCell، فتُقرأ دائمًا من المقتطف.

يعمل المفتاح Show the inbox on the site بالطريقة نفسها. إلى أن يُحفظ في اللوحة، تعرض شارة البطاقة Set in the snippet، ويحدد enable في المقتطف ما إذا كان الويدجت سيظهر. بعد حفظ المفتاح، تعرض الشارة On أو Off، وتتجاوز البطاقة المقتطف:

• يخفي Off الويدجت حتى لو عيّن المقتطف enable: true.
• يُظهر On الويدجت حتى لو لم يحتوِ المقتطف على inboxWidget إطلاقًا. ومثل enable: true، يسجّل الزوار لتسليم رسائل صندوق الوارد دون إذن إشعارات الدفع.

تصل التغييرات المحفوظة إلى الموقع خلال دقيقة، عند التحميل التالي للصفحة.

لإعادة الويدجت إلى المقتطف، انقر على Return to snippet في البطاقة وأكّد. يظهر الزر بمجرد حفظ أي شيء في البطاقة. يحذف كل إعدادات صندوق الوارد المحفوظة في اللوحة، ويعود الموقع إلى استخدام إعدادات inboxWidget في مقتطفه.

واجهة برمجة التطبيقات (API)

لفتح أو إغلاق الويدجت، استخدم طريقة API التالية:

مثال

Pushwoosh.pwinboxWidget.toggle(open?: boolean);

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