Android SDK 中的功能开关

Pushwoosh.getInstance().featureFlags 为您的 Android 应用提供在 Control Panel 中为该应用配置的功能开关。Pushwoosh 在服务器上针对当前设备和用户评估开关规则，SDK 返回评估结果：该开关是否对此设备开启，以及适用哪些属性值。

前提条件

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 对象；当 SDK 尚未获得该设备的开关，或响应中不包含该开关时，返回 null。已归档的开关不会出现在响应中。get 仅读取存储的开关，从不等待网络。该对象包含以下字段：

字段	类型	描述
`key`	String	开关键。
`isEnabled`	Boolean	该开关是否对此设备开启。
`ruleId`	String	决定结果的规则，例如 `r_1a2b3c4d`。没有规则匹配该设备时为 `default`，开关被终止（killed）时为空字符串。

请使用与属性类型匹配的 getter 读取属性值。当属性缺失或其值属于其他类型时，每个 getter 都会返回您的默认值。当开关关闭时，属性保存的是在 Control Panel 中设置的默认值。

方法	返回值
`getString(property, defaultValue)`	String 属性的值。
`getNumber(property, defaultValue)`	Number 属性的值，以 `Double` 返回。
`getBool(property, defaultValue)`	Boolean 属性的值。
`getJsonObject(property, defaultValue)`	保存对象的 JSON 属性的值，以 `JSONObject` 返回。
`getJsonArray(property, defaultValue)`	保存数组的 JSON 属性的值，以 `JSONArray` 返回。

当 get(key) 返回 null 时，isEnabled(key, defaultValue) 返回 defaultValue。

保持开关最新

SDK 会将最近一次响应存储在设备上，最长 24 小时。存储的开关仅对请求它们时的 User ID 有效。SDK 会在以下情况下刷新开关：

会话开始时，即应用首次进入前台，或在后台停留至少 30 分钟后回到前台时；
应用处于前台期间每小时一次；
设备首次注册后；
通过 setUserId 变更 User ID 后立即刷新。上一个用户的存储开关会被丢弃，因此新用户永远不会看到它们。

要响应新值，请注册一个监听器。每次刷新改变了任一开关值后，都会调用它：

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 分钟最多发送一次请求，并在该时间窗口内使用存储的开关作答。回调在主线程上运行：

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。当请求未收到 HTTP 响应时，其 httpStatus 为 0；当服务器已响应但响应无法使用时，为 200。

如果 Pushwoosh 无法及时匹配设备所属的 Segment，它会返回部分响应。SDK 不会存储该响应，下一次刷新会带来完整响应。

当某个开关在 Control Panel 中被终止（killed）时，设备会在下一次刷新时获得关闭状态的开关及默认属性值。当 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 分钟一次。回调会收到一个 `Result`，失败时其中包含 `FeatureFlagsException`；回调可以为 `null`。
`addUpdateListener(listener)`	每次刷新改变了开关值后调用 `listener`。
`removeUpdateListener(listener)`	移除通过 `addUpdateListener` 添加的监听器。
`logImpression(key)`	针对该开关当前的规则和状态发送 `PW_FeatureFlagImpression` 事件。