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

**أداة الاشتراك** هي جرس تشغيل بالإضافة إلى مطالبة تدعو زوار الموقع للاشتراك في إشعارات الدفع. تحل محل [زر الاشتراك في إشعارات Push](/ar/developer/pushwoosh-sdk/web-push-notifications/push-subscription-button/) و[نافذة الاشتراك المنبثقة المخصصة](/ar/developer/pushwoosh-sdk/web-push-notifications/custom-subscription-popup/) وأدوات [طلب الاشتراك](/ar/developer/guides/messaging-channels/subscription-prompt/) في مكون واحد. طالما أنها مفعّلة، لا يتم تحميل أي من هذه الثلاثة على الصفحة، لذا لا يرى الزوار أبدًا طلبين متنافسين.

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

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

تأكد من أنك قمت بتطبيق Pushwoosh Web SDK 3.0 على موقعك. للقيام بذلك، اتبع [دليل التكامل](/ar/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/#integration) الخاص بنا.

## 1. تفعيل الأداة

أضف المعامل `subscriptionWidget` إلى تهيئة WebSDK وعيّن `enable` إلى `true`:

```javascript
Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    enable: true,
  }
}]);
```

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

## 2. تكوين المطالبة

```javascript
Pushwoosh.push(['init', {
  //...
  subscriptionWidget: {
    enable: true,
    prompt: {
      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
      size: 48,             // 32–80
    },
    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`** — يفتح فقط عندما ينقر الزائر على الجرس.
- **`manual`** — يفتح فقط عبر `Pushwoosh.moduleRegistry.subscriptionWidget`، الموصوف أدناه.

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

### جرس التشغيل

يعرض `launcher.enabled` جرسًا عائمًا طالما أن الزائر غير مشترك، بغض النظر عن `display.trigger` — حتى مع `trigger: 'auto'`، يبقى الجرس مرئيًا حتى يتمكن الزائر من إعادة فتح المطالبة بعد إغلاقها. يضع `launcher.position` الجرس في إحدى الزوايا الأربع. يقوم `launcher.offset` (المسافة بالبكسل من الحواف) و`launcher.size` (قطر الجرس بالبكسل) بضبط الموضع بدقة.

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

تظهر `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 من كل حقل بهذه الطريقة، حتى 64 حرفًا. يقبل مقتطف init أي سلسلة غير فارغة لهذه الحقول دون التحقق من تنسيقها أو طولها.

<Aside type="note">
تتوفر لوحة ألوان الوضع الداكن، و`zIndex` الخاص بالمُشغّل، و`fontFamily` مخصص كحقول إضافية عبر معاملات init فقط. وهي غير متاحة في نموذج Control Panel الموصوف أدناه.
</Aside>

## إدارتها في Control Panel

<Aside type="caution" title="للتطبيقات المُدارة من اللوحة فقط">
بطاقة Control Panel متاحة فقط للتطبيقات التي تكون فيها منصة الويب في وضع **الإدارة من اللوحة**. (انظر [Web Push SDK 3.0](/ar/developer/pushwoosh-sdk/web-push-notifications/web-push-sdk-30/)). بالنسبة لتطبيق مُهيأ عبر المقتطف، عيّن `subscriptionWidget` في مقتطف init كما هو موضح أعلاه.
</Aside>

في تطبيق مُدار من اللوحة، انتقل إلى **Settings → Configure platforms → Web** وافتح بطاقة **Subscription widget**. تُظهر شارة على البطاقة ما إذا كانت الأداة **On** أو **Off**.

انقر على **Configure** لتعديل نفس الحقول الموضحة أعلاه، المُجمعة كـ **Prompt** و**When to show** و**Bell** و**Texts** و**Colors**، بجانب معاينة مباشرة تُظهر حالة الزائر غير القرار وحالة الزائر المحظور معًا. يؤدي الحفظ إلى استبدال نسخة تكوين الأداة في اللوحة. لا يمس مقتطف init الخاص بـ WebSDK على موقعك.

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

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

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

```javascript
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()` بالنسبة لزائر اشترك بالفعل. يؤدي فتح المطالبة إلى إطلاق حدث `show-subscription-widget`. ويؤدي إغلاقها إلى إطلاق `hide-subscription-widget`:

```javascript
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.enable` غير معيّن أو `false`. يؤدي تعيينه إلى `true` إلى إيقاف تحميل الثلاثة جميعًا، سواء في تطبيق مُهيأ عبر المقتطف أو مُدار من اللوحة.

<Aside type="caution">
تبديل تطبيق مُدار من اللوحة إلى أداة الاشتراك لا ينقل إعدادات الأداة القديمة التي يستبدلها — تبدأ الأداة من قيمها الافتراضية الخاصة، وتقوم بتكوينها من الصفر في بطاقتها.
</Aside>