أداة الاشتراك

أداة الاشتراك هي مطالبة وجرس تشغيل يدعوان زوار الموقع للاشتراك في إشعارات الدفع، ويتم تكوينهما معًا ضمن subscriptionWidget لكن تفعيلهما مستقل: المطالبة وحدها، أو الجرس وحده، أو كلاهما معًا. يؤدي تفعيل أي منهما إلى استبدال زر الاشتراك في إشعارات Push ونافذة الاشتراك المنبثقة المخصصة وأدوات طلب الاشتراك — وطالما أن أحد الجزأين مفعّل، لا تُحمَّل أي من هذه الأدوات الثلاث الأقدم على الصفحة.

الزائر الذي لم يقرر بعد يرى طلب المطالبة. الزائر الذي حظر الإشعارات بالفعل يرى بدلاً من ذلك شرحًا لكيفية إلغاء حظرها.

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

تأكد من أنك قمت بتطبيق Pushwoosh Web SDK 3.0 على موقعك. للقيام بذلك، اتبع دليل التكامل الخاص بنا.

1. تفعيل المطالبة والجرس

أضف المعامل subscriptionWidget إلى تهيئة WebSDK وعيّن prompt.enabled و/أو launcher.enabled إلى true:

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: { enabled: true },
    launcher: { enabled: true },
  }
}]);

لا يوجد مفتاح واحد على المستوى الأعلى

لا تتم قراءة subscriptionWidget.enable على المستوى الأعلى. تعيين هذا الحقل وحده لا يفعّل شيئًا. راجع الترحيل من الأدوات القديمة أدناه.

كل حقل أدناه اختياري. الحقل المحذوف يعود إلى قيمته الافتراضية. في مقتطف init، يتم تقييد الرقم خارج نطاقه بصمت إلى أقرب حد، وتعود قيمة enum غير الصالحة بصمت إلى قيمتها الافتراضية، دون تحذير في وحدة التحكم. نماذج Control Panel الموصوفة أدناه تتحقق من كل حقل وترفض حفظ أي قيمة غير صالحة.

2. تكوين المطالبة والجرس

Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    prompt: {
      enabled: true,
      layout: 'card',       // 'card' | 'bar' | 'modal'
      position: 'bottom-right',
      iconUrl: 'https://url-image.png',
      borderRadius: 12,     // 0–32
      overlay: false,
    },
    launcher: {
      enabled: true,
      position: 'bottom-right', // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
      offset: 20,           // 0–100
      width: 48,             // 16–200
      height: 48,            // 16–200
      imageUrl: 'https://url-image.png',
      background: '#4285f4',
      iconColor: '#ffffff',
    },
    display: {
      trigger: 'auto',      // 'auto' | 'launcher' | 'manual'
      delay: 5,             // seconds, 0–3600
      cappingCount: 3,      // auto-shows per visitor, 0–100, 0 = unlimited
      cappingInterval: 24,  // hours between auto-shows, 0–8760
    },
    texts: {
      title: 'Stay in the loop',
      message: 'Get notified about news and updates.',
      acceptText: 'Allow',
      declineText: 'Not now',
      closeText: 'Close',
      blockedTitle: 'Notifications are blocked',
      blockedMessage: 'Enable notifications in your browser settings to stay updated.',
      launcherLabel: 'Subscribe to notifications',
      launcherBlockedLabel: 'Notifications are blocked',
    },
    colors: {
      background: '#ffffff',
      accent: '#4285f4',
      text: '#000000',
      textSecondary: '#666666',
    },
  }
}]);

التخطيط والموضع

يحدد prompt.layout شكل المطالبة:

• card — بطاقة مدمجة مثبتة عند حافة أو زاوية. يقبل prompt.position القيم top أو bottom أو top-left أو top-right أو bottom-left أو bottom-right.
• bar — شريط يمتد على كامل عرض الصفحة. يقبل prompt.position فقط top أو bottom.
• modal — نافذة تتوسط الصفحة. prompt.position دائمًا center.

راجع القائمة أعلاه لمعرفة التخطيط الذي قمت بتعيينه قبل اختيار موضع. في مقتطف init، يتم استبدال الموضع غير المدعوم من التخطيط الحالي بصمت بالقيمة الافتراضية للتخطيط. نموذج Control Panel يرفض هذا المزيج بدلاً من ذلك.

متى يتم عرض المطالبة

يتحكم display.trigger فيما يفتح المطالبة:

• auto — يفتح تلقائيًا بعد display.delay ثانية من تحميل الصفحة، ثم مرة أخرى كل display.cappingInterval ساعة إذا لم يقرر الزائر، حتى display.cappingCount مرة إجمالاً (0 تعني بلا حد).
• launcher — لا تُفتح أبدًا بمؤقت. عيّنه مع launcher.enabled: true حتى يتمكن النقر على الجرس من فتحها. لا تزال واجهة API اليدوية تفتحها بغض النظر عن هذا الإعداد أو عن تفعيل الجرس.
• manual — يفتح فقط عبر Pushwoosh.moduleRegistry.subscriptionWidget، الموصوف أدناه.

تنطبق display.delay وdisplay.cappingCount وdisplay.cappingInterval فقط على المشغّل auto.

جرس التشغيل

يعرض launcher.enabled جرسًا عائمًا للزائر الذي لا يزال بإمكانه الاستجابة للطلب (لم يشترك بعد، أو حظر الإشعارات)، بشكل مستقل عن المطالبة وعن display.trigger. يبقى الجرس على الشاشة أثناء فتح المطالبة. يضع launcher.position الجرس في إحدى الزوايا الأربع. يحدد launcher.offset بعده عن الحواف بالبكسل.

يعتمد أثر النقر على الجرس على المطالبة. إذا كانت prompt.enabled تساوي true، فإن النقر يبدّل حالتها: يفتحها، أو يغلقها إن كانت مفتوحة بالفعل. إذا كانت المطالبة معطّلة، يطلب النقر الإذن من المتصفح مباشرة، تمامًا مثل Pushwoosh.subscribe() — ما لم يكن الزائر قد حظر الإشعارات بالفعل، وعندها لا يحدث شيء عند النقر.

يحدد launcher.width وlauncher.height حجم الجرس بالبكسل (16–200، والافتراضي 48 لكل منهما). يرسم launcher.imageUrl صورة بدلاً من زر الجرس المستدير. يحدد launcher.background وlauncher.iconColor لون تعبئة الزر المستدير ولون الرمز. إذا تُرك launcher.background غير معيّن فقيمته الافتراضية هي لون التمييز في لوحة الألوان، وlauncher.iconColor لون رمز يُحسب لتحقيق التباين معه.

النصوص والألوان

تظهر texts.blockedTitle وtexts.blockedMessage وtexts.closeText بدلاً من المطالبة بمجرد أن يبلغ المتصفح أن الزائر حظر الإشعارات — لا تظهر texts.acceptText وtexts.declineText أبدًا في تلك الحالة. texts.launcherLabel وtexts.launcherBlockedLabel هما تلميح الجرس في كل حالة. يقبل كل حقل نصي حتى 300 حرف.

تقبل colors.accent وcolors.background وcolors.text وcolors.textSecondary قيمة hex أو اسم لون CSS. تتحقق نماذج Control Panel من كل منها، ومن launcher.background وlauncher.iconColor، بهذه الطريقة، حتى 64 حرفًا. يقبل مقتطف init أي سلسلة غير فارغة لـ colors.* دون التحقق من تنسيقها أو طولها. أما بالنسبة لـ launcher.background وlauncher.iconColor فلا يتحقق من التنسيق، لكنه يقطع القيمة بصمت إلى 64 حرفًا.

ملاحظة

تتوفر لوحة ألوان الوضع الداكن، وlauncher.zIndex، وfontFamily مخصص كحقول إضافية عبر معاملات init فقط. وهي غير متاحة في نماذج Control Panel الموصوفة أدناه.

إدارتها في Control Panel

للتطبيقات المُدارة من اللوحة فقط

بطاقتا Control Panel متاحتان فقط للتطبيقات التي تكون فيها منصة الويب في وضع الإدارة من اللوحة. (انظر Web Push SDK 3.0). بالنسبة لتطبيق مُهيأ عبر المقتطف، عيّن subscriptionWidget في مقتطف init كما هو موضح أعلاه.

في تطبيق مُدار من اللوحة، انتقل إلى Settings → Configure platforms → Web. المطالبة والجرس بطاقتان منفصلتان هناك، لكل منهما شارة On/Off وزر Configure خاص بها:

• Subscription invitation تعدّل المطالبة: Invitation (التخطيط، الموضع، الأيقونة) وWhen to show (المشغّل، التأخير، الحد الأقصى) وTexts وColors.
• Subscription bell تعدّل جرس التشغيل: الموضع، وعنوان URL للصورة، والعرض/الارتفاع، ولون الخلفية والأيقونة، ونصوص التلميح الخاصة به.

يفتح زر Configure في كل بطاقة معاينة مباشرة بجانب النموذج. لا ترسم المعاينة شيئًا ما دام مفتاح تلك البطاقة معطّلاً. بمجرد تفعيله، تبدّل قائمة منسدلة فوق المعاينة بين طلب الزائر الذي لم يقرر وشرح الزائر المحظور. يؤدي حفظ بطاقة إلى استبدال نصفها فقط من نسخة تكوين الأداة في اللوحة — أما إعدادات البطاقة الأخرى ومقتطف init الخاص بـ WebSDK على موقعك فلا يتأثران.

طالما أن التطبيق مُدار من اللوحة، فإن القيم المحفوظة في أي من البطاقتين تتجاوز نفس المفاتيح في مقتطف init الخاص بالموقع.

3. التحكم في المطالبة من الكود الخاص بك

بمجرد تحميل حزمة الأداة، تنشر واجهة برمجة تطبيقات على Pushwoosh.moduleRegistry.subscriptionWidget:

Pushwoosh.moduleRegistry.subscriptionWidget.show();          // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.hide();          // Closes the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.toggle();        // Toggles the current state
Pushwoosh.moduleRegistry.subscriptionWidget.toggle(true);    // Opens the prompt
Pushwoosh.moduleRegistry.subscriptionWidget.isVisible();     // Returns whether the prompt is open

لا تأثير لـ show() وtoggle() ما دامت prompt.enabled تساوي false، ولا تأثير لهما بالنسبة لزائر اشترك بالفعل. يؤدي فتح المطالبة إلى إطلاق حدث show-subscription-widget. ويؤدي إغلاقها إلى إطلاق hide-subscription-widget:

Pushwoosh.addEventHandler('show-subscription-widget', function() {
  console.log('Triggered event: show-subscription-widget');
});

Pushwoosh.addEventHandler('hide-subscription-widget', function() {
  console.log('Triggered event: hide-subscription-widget');
});

الترحيل من الأدوات القديمة

يستمر زر الاشتراك في إشعارات Push ونافذة الاشتراك المنبثقة المخصصة وطلب الاشتراك في العمل كما هو موثق في صفحاتها الخاصة طالما ظل كل من subscriptionWidget.prompt.enabled وsubscriptionWidget.launcher.enabled في الموقع غير معيّن أو false. يؤدي تفعيل أي منهما إلى إيقاف تحميل الثلاثة جميعًا، سواء في تطبيق مُهيأ عبر المقتطف أو مُدار من اللوحة.

تنبيه

استخدم إصدار سابق من الأداة مفتاحًا واحدًا على المستوى الأعلى هو subscriptionWidget.enable بدلاً من prompt.enabled/launcher.enabled المنفصلين. لم تعد هذه الصيغة تُقرأ. المقتطف الذي لا يزال يعيّن enable: true فقط يؤدي الآن إلى إيقاف الأداة تمامًا: لا ترسم المطالبة ولا الجرس شيئًا، ويسجل WebSDK تلميحًا في وحدة التحكم يذكر الحقلين اللذين يجب تعيينهما بدلاً من ذلك، وتُحمَّل الأدوات الثلاث الأقدم كما لو أن subscriptionWidget لم يُعيَّن أبدًا. كما أن تبديل تطبيق مُدار من اللوحة إلى الأداة الجديدة لا ينقل إعدادات الأداة القديمة التي تستبدلها — تبدأ كل بطاقة من قيمها الافتراضية الخاصة.