Android SDK의 기능 플래그

Pushwoosh.getInstance().featureFlags는 Control Panel에서 애플리케이션에 구성된 기능 플래그를 Android 앱에 제공합니다. Pushwoosh는 현재 기기와 사용자에 대해 서버에서 플래그 규칙을 평가하고, SDK는 그 결과를 반환합니다. 즉, 이 기기에 플래그가 켜져 있는지와 어떤 속성 값이 적용되는지를 반환합니다.

사전 요구 사항

Android SDK 가이드에 설명된 대로 통합한 Pushwoosh Android SDK 6.16.0 이상. 기능 플래그는 기본 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`이고, 플래그가 강제 종료(kill)된 경우 빈 문자열입니다.

속성 유형에 맞는 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분 이상 있다가 돌아올 때
앱이 포그라운드에 있는 동안 1시간마다
기기가 처음 등록된 후
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에서 플래그를 강제 종료(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분에 한 번으로 제한됩니다. 콜백은 실패 시 `FeatureFlagsException`이 담긴 `Result`를 받으며, 콜백은 `null`일 수 있습니다.
`addUpdateListener(listener)`	플래그 값을 변경한 모든 새로 고침 후에 `listener`를 호출합니다.
`removeUpdateListener(listener)`	`addUpdateListener`로 추가한 리스너를 제거합니다.
`logImpression(key)`	플래그의 현재 규칙과 상태에 대한 `PW_FeatureFlagImpression` 이벤트를 전송합니다.