علامات الميزات في Web SDK

يوفّر Pushwoosh.featureFlags لموقع الويب الخاص بك علامات الميزات (feature flags) التي تم إعدادها للتطبيق في لوحة التحكم. يقيّم Pushwoosh قواعد العلامة على الخادم للجهاز والمستخدم الحاليين، ويُرجع SDK النتيجة: هل العلامة مفعّلة لهذا الزائر، وما قيم الخصائص التي تنطبق.

ميزة تجريبية

علامات الميزات في المرحلة التجريبية (beta) ومتاحة فقط في الخطط التي تتضمنها. في الخطط الأخرى لا يُرجع الخادم أي علامات، لذا تعود كل علامة إلى القيمة الافتراضية التي تمررها في الكود.

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

• Web SDK 3.94.1 أو أحدث، يتم تحميله من Pushwoosh CDN كما هو موضح في دليل Web SDK 3.0، أو حزمة npm web-push-notifications 3.95.0 أو أحدث.
• علامة واحدة على الأقل تم إنشاؤها في Audience → Feature Flags. تحتاج إلى Key الخاص بها ومفاتيح خصائصها وأنواعها. استخدم المفاتيح كما تظهر هناك تمامًا، بما في ذلك حالة الأحرف. على سبيل المثال، لا يعثر get('New_Checkout') على علامة مفتاحها new_checkout.

قراءة علامة

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

Pushwoosh.push(() => {
  const flags = Pushwoosh.featureFlags;

  const render = () => {
    const checkout = flags.get('new_checkout');
    if (checkout && checkout.enabled) {
      showNewCheckout({
        buttonColor: checkout.getString('button_color', 'blue'),
        maxItems: checkout.getNumber('max_items', 3),
      });
    } else {
      showOldCheckout();
    }
  };

  render();
  flags.addUpdateListener(render);
});

مع حزمة npm، استخدم مثيل Pushwoosh الذي أنشأته:

import { Pushwoosh } from 'web-push-notifications';

const pushwoosh = new Pushwoosh();
pushwoosh.push(['init', { applicationCode: 'XXXXX-XXXXX' /* ... */ }]);

pushwoosh.push(() => {
  const isNewCheckout = pushwoosh.featureFlags.isEnabled('new_checkout', false);
  // ...
});

لا يرسل SDK أي طلبات للعلامات على الصفحة حتى يستدعي الكود الخاص بك لأول مرة get() أو isEnabled() أو refresh() أو addUpdateListener()، لذا لا ترسل الصفحات التي لا تستخدم العلامات أي حركة مرور إضافية.

ما الذي تُرجعه العلامة

يُرجع get(key) كائن FeatureFlag، أو null عندما لا تتوفر لدى SDK علامات للصفحة بعد أو عندما لا تكون العلامة موجودة في الاستجابة. العلامة المؤرشفة لا تكون موجودة في الاستجابة. يحتوي الكائن على الحقول التالية:

الحقل	النوع	الوصف
key	string	مفتاح العلامة.
enabled	boolean	هل العلامة مفعّلة لهذا الزائر.
ruleId	string	القاعدة التي حدّدت النتيجة، على سبيل المثال r_1a2b3c4d. القيمة default عندما لا تتطابق أي قاعدة مع الزائر، وسلسلة فارغة عندما يتم إيقاف العلامة إيقافًا طارئًا (killed).

اقرأ قيم الخصائص باستخدام الدالة getter التي تطابق نوع الخاصية. تُرجع كل دالة getter قيمتك الافتراضية عندما تكون الخاصية مفقودة أو تحمل قيمة من نوع آخر. عندما تكون العلامة معطّلة، تحمل الخصائص القيم الافتراضية المعيّنة في لوحة التحكم.

الطريقة	تُرجع
getString(property, defaultValue)	قيمة خاصية من نوع String.
getNumber(property, defaultValue)	قيمة خاصية من نوع Number.
getBool(property, defaultValue)	قيمة خاصية من نوع Boolean.
getJson(property, defaultValue)	قيمة خاصية من نوع JSON، كقيمة JSON محلَّلة.
getProperties()	نسخة من جميع قيم خصائص العلامة.

isEnabled(key, defaultValue) اختصار لـ get(key)?.enabled، ويُرجع defaultValue عندما لا توجد علامة.

إبقاء العلامات محدّثة

يخزّن SDK آخر استجابة في IndexedDB الخاص بالمتصفح لمدة تصل إلى 24 ساعة. تكون العلامات المخزّنة صالحة فقط لـ User ID الذي طُلبت من أجله. يحدّث SDK العلامات:

• عند أول استخدام على الصفحة، عندما يكون عمر العلامات المخزّنة أكثر من 15 دقيقة أو تكون غير موجودة؛
• كل ساعة طالما بقيت الصفحة مفتوحة؛
• بعد تسجيل الجهاز، عندما تكون العلامات قد طُلبت قبل التسجيل؛
• مباشرة بعد تغيّر User ID. يتم تجاهل العلامات المخزّنة للمستخدم السابق، لذا لا يراها المستخدم الجديد أبدًا.

للاستجابة للقيم الجديدة، سجّل مستمعًا (listener). يتم استدعاؤه بعد تحديث غيّر قيمة أي علامة:

const onFlagsChanged = () => render();
Pushwoosh.featureFlags.addUpdateListener(onFlagsChanged);
// later
Pushwoosh.featureFlags.removeUpdateListener(onFlagsChanged);

لطلب العلامات بنفسك، على سبيل المثال بعد إجراء قد ينقل الزائر إلى Segment مختلف، استدعِ refresh(). طالما أن العلامات المخزّنة صالحة، فإنه يرسل طلبًا واحدًا على الأكثر كل 5 دقائق ويكتمل فورًا ضمن تلك الفترة. يتم رفض الـ promise عند فشل الطلب، وتبقى العلامات المخزّنة قيد الاستخدام.

try {
  await Pushwoosh.featureFlags.refresh();
} catch (error) {
  // the stored flags, or your defaults, stay in effect
}
render();

إذا لم يتمكن Pushwoosh من مطابقة شرائح (Segments) الزائر في الوقت المناسب، فإنه يُرجع استجابة جزئية. يستخدمها SDK على الصفحة الحالية فقط، وفقط عندما لا تتوفر لديه علامات مخزّنة صالحة، ولا يخزّنها أبدًا. يجلب التحديث التالي الاستجابة الكاملة.

عندما يتم إيقاف علامة إيقافًا طارئًا (kill) في لوحة التحكم، يحصل عليها الزوار معطّلة مع قيم الخصائص الافتراضية عند التحديث التالي. عندما يتعذر على SDK الوصول إلى الخادم، يستمر في استخدام العلامات المخزّنة حتى يبلغ عمرها 24 ساعة، ثم يستخدم قيمك الافتراضية بعد ذلك.

تسجيل مرات الظهور

تُخبر مرة الظهور (impression) Pushwoosh بأن الزائر وصل فعلًا إلى الكود الذي تتحكم فيه العلامة، حتى تتمكن من مقارنة الزوار الذين حصلوا على الميزة بالزوار الذين لم يحصلوا عليها. استدعِ logImpression(key) في اللحظة التي يرى فيها الزائر الميزة أو نسختها القديمة، لكل من الفرع المفعّل والفرع المعطّل، لأن الزوار الذين تكون العلامة معطّلة لديهم هم مجموعة المقارنة لديك:

const checkout = Pushwoosh.featureFlags.get('new_checkout');
if (checkout) {
  Pushwoosh.featureFlags.logImpression('new_checkout');
}

يرسل SDK الحدث PW_FeatureFlagImpression مع السمات التالية:

السمة	النوع	القيمة
flag_key	string	مفتاح العلامة.
rule_id	string	القاعدة التي حدّدت النتيجة، كما في ruleId.
enabled	boolean	هل كانت العلامة مفعّلة.

لا تحتاج إلى إنشاء الحدث مسبقًا، لأن Pushwoosh يضيف PW_FeatureFlagImpression مع هذه السمات إلى Audience → Events عند وصول أول مرة ظهور. يرسل SDK مرة ظهور واحدة لكل علامة وقاعدة وحالة على الصفحة، ويتجاوز التكرارات القادمة من علامات تبويب أخرى في المتصفح نفسه لمدة 30 دقيقة. لا يتم رفض logImpression() أبدًا، ولا يرسل شيئًا عندما لا توجد علامة للمفتاح.

تتيح مرات الظهور أيضًا للمسوقين إنشاء شريحة من الزوار الذين وصلوا إلى الميزة: حالة شاهد الميزة (30 يومًا) في شرط علامة الميزة.

مرجع الطرق

يحتوي Pushwoosh.featureFlags على الطرق التالية:

الطريقة	الوصف
get(key)	يُرجع FeatureFlag للمفتاح، أو null. يقرأ العلامات المخزّنة فقط ولا ينتظر الشبكة أبدًا.
isEnabled(key, defaultValue)	يُرجع ما إذا كانت العلامة مفعّلة، أو defaultValue عندما لا توجد علامة.
refresh()	يطلب العلامات، بحد أقصى مرة واحدة كل 5 دقائق طالما أن العلامات المخزّنة صالحة. يُرجع promise.
addUpdateListener(listener)	يستدعي listener بعد كل تحديث غيّر قيمة علامة.
removeUpdateListener(listener)	يزيل مستمعًا تمت إضافته باستخدام addUpdateListener.
logImpression(key)	يرسل حدث PW_FeatureFlagImpression للقاعدة والحالة الحاليتين للعلامة. يُرجع promise.