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

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

ميزة تجريبية

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

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

• Pushwoosh Android SDK 6.16.0 أو أحدث، مدمج كما هو موضح في دليل Android SDK. علامات الميزات جزء من المكتبة الرئيسية com.pushwoosh:pushwoosh، لذا لا تحتاج إلى إضافة تبعية أخرى. إلى أن تتم تهيئة SDK، يُرجع get القيمة null.
• علامة واحدة على الأقل تم إنشاؤها في Audience → Feature Flags. تحتاج إلى Key الخاص بها ومفاتيح خصائصها وأنواعها. استخدم المفاتيح كما تظهر هناك تمامًا، بما في ذلك حالة الأحرف. على سبيل المثال، لا يعثر get("New_Checkout") على علامة مفتاحها new_checkout.

قراءة علامة

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

import com.pushwoosh.Pushwoosh

val flags = Pushwoosh.getInstance().featureFlags

val checkout = flags.get("new_checkout")
if (checkout != null && checkout.isEnabled) {
    showNewCheckout(
        buttonColor = checkout.getString("button_color", "blue"),
        maxItems = checkout.getNumber("max_items", 3.0).toInt(),
    )
} else {
    showOldCheckout()
}

للتحقق فقط مما إذا كانت العلامة مفعّلة، استخدم isEnabled:

val isNewCheckout = Pushwoosh.getInstance().featureFlags.isEnabled("new_checkout", false)

في Java، استدعِ Pushwoosh.getInstance().getFeatureFlags().

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

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

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

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

الطريقة	تُرجع
getString(property, defaultValue)	قيمة خاصية من نوع String.
getNumber(property, defaultValue)	قيمة خاصية من نوع Number، كقيمة Double.
getBool(property, defaultValue)	قيمة خاصية من نوع Boolean.
getJsonObject(property, defaultValue)	قيمة خاصية من نوع JSON تحمل كائنًا، ككائن JSONObject.
getJsonArray(property, defaultValue)	قيمة خاصية من نوع JSON تحمل مصفوفة، ككائن JSONArray.

يُرجع isEnabled(key, defaultValue) القيمة defaultValue عندما يُرجع get(key) القيمة null.

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

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

• عند بدء جلسة، أي عندما ينتقل التطبيق إلى الواجهة الأمامية لأول مرة أو بعد 30 دقيقة على الأقل في الخلفية.
• كل ساعة طالما بقي التطبيق في الواجهة الأمامية.
• بعد أن يُسجَّل الجهاز لأول مرة.
• مباشرة بعد تغيّر User ID باستخدام setUserId. يتم تجاهل العلامات المخزّنة للمستخدم السابق، لذا لا يراها المستخدم الجديد أبدًا.

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

import com.pushwoosh.featureflags.FeatureFlagsUpdateListener

private val flagsListener = FeatureFlagsUpdateListener { render() }

override fun onStart() {
    super.onStart()
    Pushwoosh.getInstance().featureFlags.addUpdateListener(flagsListener)
}

override fun onStop() {
    Pushwoosh.getInstance().featureFlags.removeUpdateListener(flagsListener)
    super.onStop()
}

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

Pushwoosh.getInstance().featureFlags.refresh { result ->
    if (!result.isSuccess) {
        val status = result.exception?.httpStatus
        // the stored flags, or your defaults, stay in effect
    }
    render()
}

عند الفشل، تكون result.exception من النوع FeatureFlagsException. تكون قيمة httpStatus الخاصة بها 0 عندما لم يتلقَّ الطلب أي استجابة HTTP، و200 عندما ردّ الخادم ولكن تعذّر استخدام الاستجابة.

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

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

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

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

val flags = Pushwoosh.getInstance().featureFlags
val isOn = flags.isEnabled("new_checkout", false)
flags.logImpression("new_checkout")
if (isOn) {
    showNewCheckout()
} else {
    showOldCheckout()
}

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

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

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

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

مرجع الطرق

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

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